C# 整合 Google Earth COM API 開發實戰 (一)：環境建置與 Hello World

Google Earth 提供 COM API 讓開發者以程式控制 3D 地球引擎。本系列第一篇介紹開發環境建置、參考加入、基本物件模型，並實作最簡單的「啟動 GE、截圖、開啟截圖」Hello World 程式，為後續嵌入、互動、進階控制奠基。

版本與授權說明

• 免費版/Pro 版：個人開發免費版即可，企業商業用途需購買 Pro 版 (年費 $400)
• COM API 版本：僅提供 1.0 版型別程式庫，功能有限，已停止更新
• 官方文件：https://earth.google.com/comapi/index.html

Visual Studio 專案設定

1. 安裝 Google Earth (確認 googleearth.exe 可正常執行)
2. VS 建立 Windows Forms 專案 (.NET Framework 3.5+)
3. 專案 → 加入參考 → COM 標籤 → 勾選 Google Earth 1.0 Type Library
4. 參考清單出現 EARTHLib，命名空間包含 ApplicationGEClass、FeatureGE 等介面

核心類別與介面

Hello World 完整程式碼

using System;
using System.Windows.Forms;
using EARTHLib;
using System.Runtime.InteropServices;
using System.IO;
using System.Diagnostics;

namespace GEDemo
{
    public partial class Form1 : Form
    {
        private bool _isGeStarted = false;
        private ApplicationGEClass _geApp;

        public Form1()
        {
            InitializeComponent();
        }

        // 啟動/連接 GE
        private void btnStart_Click(object sender, EventArgs e) => StartGE();

        private void StartGE()
        {
            if (_isGeStarted) return;

            try
            {
                // 嘗試連接已執行的 GE 實例
                _geApp = (ApplicationGEClass)Marshal.GetActiveObject("GoogleEarth.Application");
                _isGeStarted = true;
            }
            catch
            {
                // 無執行中實例，建立新實例
                _geApp = new ApplicationGEClass();
                _isGeStarted = true;
            }
        }

        // 截圖儲存
        private void btnScreenshot_Click(object sender, EventArgs e)
        {
            string path = Path.Combine(Application.StartupPath, "ScreenShot.jpg");
            try
            {
                // quality 0-100，數值越高品質越好
                _geApp.SaveScreenShot(path, 100);
                MessageBox.Show($"截圖已儲存：{path}");
            }
            catch (Exception ex)
            {
                MessageBox.Show($"截圖失敗：{ex.Message}");
            }
        }

        // 開啟截圖檔案
        private void btnOpenImage_Click(object sender, EventArgs e)
        {
            string path = Path.Combine(Application.StartupPath, "ScreenShot.jpg");
            if (!File.Exists(path))
            {
                MessageBox.Show("找不到截圖檔案！");
                return;
            }
            Process.Start(path);
        }

        // 關閉應用程式
        private void btnExit_Click(object sender, EventArgs e)
        {
            Close();
            Application.Exit();
        }
    }
}

關鍵技術點

1. Marshal.GetActiveObject：連接已執行的 COM 物件，避免重複啟動多個 GE 進程
2. ApplicationGEClass：COM 介面的 RCW (Runtime Callable Wrapper)，實際呼叫轉發至 googleearth.exe 進程
3. SaveScreenShot：官方截圖 API，輸出 黑白 圖片，品質參數 0-100
4. 例外處理：COM 呼叫易發生 COMException、UnauthorizedAccessException，務必 try-catch

執行結果

點擊「啟動 GE」 → 桌面出現 Google Earth 視窗 → 點擊「截圖」 → 專案目錄產生 ScreenShot.jpg → 點擊「開啟圖片」 → 關聯圖片檢視器開啟。

常見問題排查

系列文章規劃

1. (一) Hello World：環境建置、啟動、截圖、基本控制 ← 本文
2. (二) 視窗嵌入：隱藏原生視窗、渲染畫面重定向至 WinForms 容器
3. (三) 互動增強：自適應、滑鼠座標轉經緯度、彩色截圖
4. (四) 進階控制：滾輪縮放、地標/圖層樹狀管理、可見度切換

總結與展望

Google Earth COM API 雖功能有限且已停止維護，但對於需要在桌面應用快速整合 3D 地球視覺化的專案，仍具參考價值。現代專案建議評估：

• Web 端：CesiumJS、Mapbox GL JS、Google Maps JavaScript API
• 桌面端：NASA WorldWind (.NET 原生)、Cesium for Unity/Unreal
• 企業級 GIS：ArcGIS Runtime SDK、QGIS Python API

本系列完整原始碼：GEDemo_2009-05-22.rar