osgEarth 入門實戰：從環境配置到地球渲染完整指南

前言

osgEarth 是基於 OpenSceneGraph (OSG) 的地理空間可視化引擎，支援加載各類地圖數據（影像、高程、矢量）並渲染 3D 地球。本文記錄 OSG 3.1.4 + osgEarth 2.3 在 Windows VC10 下的完整編譯配置、最小可運行項目構建、.earth 文件解析與常見問題排查，適合初學者快速上手。

一、環境準備與編譯包獲取

• 下載預編譯包：pan.baidu.com/s/1eSE1sd0#path=/VS相關（含 OSG 3.1.4、osgEarth 2.3、VC10 編譯庫）
• 解壓後目錄結構包含 bin、include、lib、data 等標準 SDK 目錄。

二、環境變量配置（關鍵步驟）

新建三個系統環境變量：

將 %OSG_ROOT%\bin 添加到系統 Path 變量，確保運行時能找到 DLL。

三、驗證環境：命令行快速測試

cd %OSGEARTH_ROOT%\bin
osgearth_viewer mymap.earth

若彈出紋理地球窗口，說明環境配置成功。

四、VC++ 2010 項目從零構建

1. 新建控制台應用程序

項目名稱：osgEarth_HelloWorld

2. 項目屬性配置

• VC++ 目錄 → 包含目錄 添加：
  $(OSG_ROOT)\include
$(OSGEARTH_ROOT)\include
• VC++ 目錄 → 庫目錄 添加：
  $(OSG_ROOT)\lib
$(OSGEARTH_ROOT)\lib
• 鏈接器 → 輸入 → 附加依賴項 添加（Debug 版）：
  OpenThreadsd.lib osgd.lib osgDBd.lib osgFXd.lib osgGAd.lib osgManipulatord.lib osgParticled.lib osgShadowd.lib osgSimd.lib osgTerraind.lib osgTextd.lib osgUtild.lib osgViewerd.lib
  Release 版去掉 d 後綴。
• 鏈接器 → 清單工具 → 嵌入清單：設為 否 (No)，否則可能報 LNK1123 錯誤。

3. 核心代碼 (main.cpp)

#include 
#include 
#include 
#include 

int main() {
    // 1. 創建 Viewer
    osg::ref_ptr viewer = new osgViewer::Viewer();

    // 2. 構建場景圖根節點
    osg::ref_ptr root = new osg::Group();

    // 3. 加載 .earth 文件（包含圖層配置）
    osg::ref_ptr node = osgDB::readNodeFile("mymap.earth");
    if (!node) {
        std::cerr << "Failed to load mymap.earth" << std::endl;
        return -1;
    }
    root->addChild(node.get());

    // 4. 場景優化
    osgUtil::Optimizer optimizer;
    optimizer.optimize(root.get());

    // 5. 設置場景並運行
    viewer->setSceneData(root.get());
    viewer->realize();
    return viewer->run();
}

4. 編寫 mymap.earth 配置文件

放在項目目錄（與 main.cpp 同級）：

5. 複製必要數據文件

• 從 %OSG_ROOT%\data 複製 world.tif 到項目目錄（與 mymap.earth 同級）。
• 關鍵：運行時工作目錄必須包含這兩個文件。VC++ 默認工作目錄為項目目錄，若報錯「找不到文件」，請手動複製到 $(OutDir)（如 Debug/）或設置「調試 → 工作目錄」為項目目錄。

6. 構建運行

按 F5 運行，應彈出可交互的 3D 地球窗口：

• 鼠標左鍵拖拽：旋轉地球
• 鼠標中鍵/滾輪：縮放
• 鼠標右鍵拖拽：平移視角

五、.earth 文件深度解析

.earth 文件採用 XML 格式，定義地圖圖層、數據源、投影坐標系等。osgEarth 安裝目錄 tests/ 下提供豐富示例，替換 mymap.earth 內容即可快速體驗不同效果：

• 單層影像：基礎藍色大理石紋理（本文示例）
• 多層疊加：影像 + 高程 + 矢量標注
• WMTS/TMS 服務：在線地圖服務（需網絡）
• 本地 MBTiles/GeoPackage：離線地圖包
• 高程誇張：

建議逐個測試 tests/ 下的 .earth 文件，觀察渲染差異，理解圖層結構。

六、常見問題排查

七、進階學習路徑

1. 閱讀 osgEarth 官方文檔：https://osgearth.org/documentation.html
2. 學習 osgEarth::Map、ImageLayer、ElevationLayer、FeatureLayer 核心類 API。
3. 掌握 osgEarth::GeoPoint、GeoExtent 地理坐標操作。
4. 嘗試加載本地 Shapefile、KML、GeoJSON 矢量數據。
5. 整合 Qt/MFC/Win32 實現嵌入式地球窗口。

八、項目源碼下載

完整 VC10 項目：pan.baidu.com/s/1eSE1sd0#path=/VS相關