简介本资源面向使用MSVC2017工具链进行三维地理可视化开发的C/Qt工程师与学习者提供OSG 3.63、osgEarth 2.10与Qt 5.14的完整编译产物及一个可直接运行的简单Qt工程帮助解决自编译环境搭建繁琐、依赖库版本难对齐的问题。压缩包约530.29MB共约2000个文件以hpp与h头文件为主配合dll、lib、pdb、ilk等动态库与调试符号另有exe示例程序、earth地球配置、shp/dbf/prj等GIS数据、glsl着色器及jpg/png贴图资源覆盖开发、调试与运行所需。资源还包含QtCreator工程文件与mainwindow等源码便于对照学习OSG与Qt窗口的集成方式。目前已有536人学习下载适合需要快速验证osgEarth地形加载、影像图层与三维场景交互的中高级开发者参考。1. 从一次编译翻车说起msvc2017 OSG3.6.3 osgEarth2.10 Qt5.14 这套组合到底难在哪如果你在 Windows 上做三维地理可视化大概率绕不开 OSG osgEarth Qt 这套组合。但真正动手装过的人都知道这套环境的坑不在单个库而在版本咬合MSVC2017 的 ABI、OSG3.6.3 的 CMake 配置、osgEarth2.10 对 GDAL 和 PROJ 的依赖、Qt5.14 的 qmake 与 MSVC 工具链匹配任何一环版本错位轻则编译报 LNK2019重则运行时直接崩在 osgDB 插件加载上。我见过太多人卡在“osgEarth 编译过了但一跑就白屏”这一步最后发现是第三方依赖库的 Debug/Release 混用。这篇笔记按我实际部署的顺序从环境清单、依赖编译、CMake 参数、Qt 集成到验证排错一步步走完目标是让你装完能跑起一个带地球的 Qt 窗口而不是停在编译成功那一刻。2. 环境清单与版本锁定为什么必须是这几个版本2.1 各组件版本对照与下载来源这套组合的版本不是随便选的。MSVC2017 对应的是 v141 工具集OSG3.6.3 是 3.6 系列里对 v141 支持最稳的一版osgEarth2.10 是 2.x 最后一个大版本对 Qt5.14 的集成接口已经稳定。Qt5.14.2 是 Qt5 最后一个长期维护的补丁版本qmake 对 MSVC2017 的 mkspecs 支持完整。下面是我实际用的版本对照组件版本获取方式备注Visual Studio2017 15.9官方安装器必须装“使用 C 的桌面开发”CMake3.16.x官方安装包3.20 以上对 OSG 老工程有策略警告OSG3.6.3源码不要用 3.6.5插件接口有变动osgEarth2.10源码对应 OSG3.6.3 的分支Qt5.14.2官方安装器勾选 msvc2017 64-bitGDAL2.4.x源码或预编译osgEarth2.10 依赖PROJ5.x源码GDAL 2.4 配套第三方库3rdPartyOSG 官方包必须与 OSG 版本匹配提示第三方库包一定要用 OSG3.6.3 对应的那一版用 3.4 的 3rdParty 会在链接 zlib 和 libpng 时报符号不匹配。2.2 环境变量与目录规划我一般把源码和编译产物分开避免 CMake 缓存污染。目录结构如下D:/dev/ ├── src/ │ ├── OpenSceneGraph-3.6.3/ │ ├── osgearth-2.10/ │ ├── gdal-2.4.4/ │ └── proj-5.2.0/ ├── build/ │ ├── osg-build/ │ ├── osgearth-build/ │ └── gdal-build/ ├── install/ │ ├── osg/ │ ├── osgearth/ │ ├── gdal/ │ └── qt/ └── 3rdParty/ └── x64/环境变量在编译前设好不要等 CMake 报错再补set OSG_ROOTD:\dev\install\osg set OSGEARTH_ROOTD:\dev\install\osgearth set GDAL_ROOTD:\dev\install\gdal set PATH%OSG_ROOT%\bin;%OSGEARTH_ROOT%\bin;%GDAL_ROOT%\bin;%PATH%这样设的原因是 CMake 的 find_package 会优先读环境变量里的路径比手动指定省事也避免多个版本串扰。3. 编译 OSG3.6.3CMake 参数与第三方库对接3.1 CMake 配置命令与关键参数OSG 的编译本身不复杂但参数写错会导致插件缺失。我用的命令如下cd D:/dev/build/osg-build cmake D:/dev/src/OpenSceneGraph-3.6.3 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/install/osg ^ -DACTUAL_3RDPARTY_DIRD:/dev/3rdParty/x64 ^ -DBUILD_OSG_APPLICATIONSON ^ -DOSG_BUILD_PLUGINSON ^ -DBUILD_DOCUMENTATIONOFF ^ -DCMAKE_BUILD_TYPERelease参数说明ACTUAL_3RDPARTY_DIR指向第三方库根目录OSG 的 CMake 脚本会自动在里面找 zlib、libpng、jpeg 等BUILD_OSG_APPLICATIONS打开会编译 osgViewer 等示例程序验证时有用OSG_BUILD_PLUGINS必须开否则 osgEarth 加载影像和地形时找不到 osgDB 插件。CMAKE_BUILD_TYPE在 VS 生成器下其实不生效但写上不影响实际用--config Release控制。3.2 编译与安装cmake --build . --config Release --target INSTALL这一步会编译并安装到D:/dev/install/osg。如果中途报错找不到zlib.lib检查 3rdParty 目录下是否有lib文件夹且里面是zlib.lib而不是zlibd.lib。Release 配置下链接 Debug 库是常见翻车点。注意编译完成后install/osg/bin下应该有osg163-osg.dll等文件install/osg/lib下是.lib。如果 bin 为空说明 INSTALL 目标没执行成功回去看 CMake 输出里有没有 “Install configuration: Release”。4. 编译 osgEarth2.10GDAL、PROJ 与 OSG 的三角关系4.1 先解决 GDAL 和 PROJosgEarth2.10 对 GDAL 的依赖是硬性的而且 GDAL 2.4 又依赖 PROJ 5。我建议先编译 PROJ再编译 GDAL最后编译 osgEarth。PROJ 的编译cd D:/dev/build/proj-build cmake D:/dev/src/proj-5.2.0 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/install/proj ^ -DPROJ_LIBRARY_TYPESHARED cmake --build . --config Release --target INSTALLGDAL 编译时指定 PROJcd D:/dev/build/gdal-build cmake D:/dev/src/gdal-2.4.4 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/install/gdal ^ -DPROJ_INCLUDE_DIRD:/dev/install/proj/include ^ -DPROJ_LIBRARYD:/dev/install/proj/lib/proj.lib ^ -DGDAL_BUILD_OPTIONAL_DRIVERSOFF cmake --build . --config Release --target INSTALLGDAL_BUILD_OPTIONAL_DRIVERSOFF是为了减少编译时间osgEarth 只需要核心的 GeoTIFF、Shapefile 等驱动。4.2 osgEarth 的 CMake 配置osgEarth 的 CMake 需要同时找到 OSG、GDAL、PROJ 和 Qt5cd D:/dev/build/osgearth-build cmake D:/dev/src/osgearth-2.10 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/install/osgearth ^ -DOSG_DIRD:/dev/install/osg/lib/cmake/OSG ^ -DGDAL_INCLUDE_DIRD:/dev/install/gdal/include ^ -DGDAL_LIBRARYD:/dev/install/gdal/lib/gdal.lib ^ -DPROJ_INCLUDE_DIRD:/dev/install/proj/include ^ -DPROJ_LIBRARYD:/dev/install/proj/lib/proj.lib ^ -DQT_QMAKE_EXECUTABLED:/dev/install/qt/5.14.2/msvc2017_64/bin/qmake.exe ^ -DOSGEARTH_BUILD_QTON ^ -DOSGEARTH_BUILD_TESTSOFFOSG_DIR指向 OSG 安装后的 cmake 配置目录这样 find_package(OSG) 才能定位到。OSGEARTH_BUILD_QTON会编译 osgEarth 的 Qt 集成模块后面 Qt 窗口里嵌入地球就靠它。如果 CMake 报 “Could NOT find Qt5”检查 qmake 路径是否写对以及 Qt 安装时是否勾选了 MSVC2017 64-bit 组件。4.3 编译与常见链接错误cmake --build . --config Release --target INSTALL这一步最常见的错误是 LNK2019 找不到osg::Referenced::operator delete之类的符号原因通常是 OSG 编译时用了 Debug 配置而 osgEarth 用 Release 链接。解决办法是确保 OSG 和 osgEarth 的--config一致并且 OSG 安装目录下同时有 Release 的.lib和.dll。5. Qt5.14 集成qmake 工程与 osgEarth 嵌入5.1 Qt 工程的 .pro 配置Qt 这边不需要编译 osgEarth 的源码只需要在 .pro 里链接安装好的库。我的 .pro 关键部分QT core gui widgets TARGET EarthDemo TEMPLATE app OSG_ROOT D:/dev/install/osg OSGEARTH_ROOT D:/dev/install/osgearth INCLUDEPATH $$OSG_ROOT/include INCLUDEPATH $$OSGEARTH_ROOT/include LIBS -L$$OSG_ROOT/lib -losg -losgViewer -losgDB -losgGA -losgUtil LIBS -L$$OSGEARTH_ROOT/lib -losgEarth -losgEarthUtil -losgEarthQtosgEarthQt是 osgEarth 编译时OSGEARTH_BUILD_QTON产出的库里面封装了EarthManipulator和 Qt 窗口的集成类。5.2 嵌入地球的代码骨架#include QApplication #include osgEarth/MapNode #include osgEarthUtil/EarthManipulator #include osgEarthQt/ViewerWidget #include osgViewer/Viewer int main(int argc, char** argv) { QApplication app(argc, argv); // 创建 ViewerWidget内部已经封装了 osgViewer::Viewer osgEarth::QtGui::ViewerWidget viewerWidget; osgViewer::Viewer* viewer viewerWidget.getViewer(); // 加载 earth 文件 osg::Node* earthNode osgDB::readNodeFile(D:/data/earth.osgearth); if (!earthNode) { return -1; // 加载失败检查 osgDB 插件路径 } viewer-setSceneData(earthNode); viewer-setCameraManipulator(new osgEarth::Util::EarthManipulator); viewerWidget.show(); return app.exec(); }这段代码的关键是osgDB::readNodeFile能读到.osgearth文件这要求osgEarth的插件osgdb_osgearth.dll在 PATH 里并且earth.osgearth文件里引用的影像和地形路径正确。提示如果运行时窗口出来但地球不显示先在viewer-setSceneData后加一句viewer-getCamera()-setClearColor(osg::Vec4(0,0,1,1))如果背景变蓝说明渲染正常问题在数据加载如果还是黑屏检查 osgDB 插件是否加载。6. 避坑与排查5 个我实际踩过的坑6.1 现象CMake 配置 OSG 时报 “Could NOT find OpenThreads”原因3rdParty 目录下缺少OpenThreads.lib或者路径层级不对。OSG 的 CMake 期望在3rdParty/x64/lib下找到而不是3rdParty/x64/lib/Release。解决把 3rdParty 包里的 lib 文件直接放到x64/lib下不要带配置子目录。6.2 现象osgEarth 编译通过但运行时提示 “Failed to load osgdb_osgearth.dll”原因osgdb_osgearth.dll依赖osgEarth.dll和gdal.dll而这些 DLL 不在同一目录或 PATH 里。解决把install/osg/bin、install/osgearth/bin、install/gdal/bin都加到系统 PATH或者用windeployqt的思路把所有依赖 DLL 拷到 exe 同目录。6.3 现象Qt 窗口里地球显示为白色控制台无报错原因.osgearth文件里引用的影像路径是相对路径而工作目录不对。解决在代码里用osgDB::Options设置CURL或文件搜索路径或者把.osgearth里的路径改成绝对路径。我一般会在readNodeFile前加osgDB::Registry::instance()-getDataFilePathList().push_back(D:/data)。6.4 现象链接时 LNK2038 检测到 “RuntimeLibrary” 不匹配原因OSG 编译时用了/MD而 Qt 工程默认也是/MD但某个第三方库用了/MT。解决统一所有库的运行时库设置在 CMake 里加-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreadedDLLQt 的 .pro 里加QMAKE_CXXFLAGS_RELEASE /MD。6.5 现象osgEarth 加载地形时崩溃在osg::Texture::apply原因OSG 的osgdb_jpeg或osgdb_png插件是 Debug 版而 osgEarth 是 Release 版。解决确保 OSG 编译时CMAKE_BUILD_TYPERelease并且 INSTALL 后 bin 目录下只有 Release 插件。如果之前编译过 Debug先删掉 install 目录重新来。7. 装完怎么验证从 osgViewer 到 Qt 窗口的完整检查链验证分三层不要跳步。第一层命令行验证 OSG 本身osgviewer.exe D:/dev/src/OpenSceneGraph-3.6.3/data/cow.osg如果能看到奶牛模型说明 OSG 的渲染、插件、DLL 路径都正常。这一步不过后面不用看。第二层验证 osgEarth 的数据加载osgearth_viewer.exe D:/data/earth.osgearthosgearth_viewer是 osgEarth 编译时自带的示例程序在install/osgearth/bin下。如果它能显示地球说明 GDAL、PROJ、osgDB 插件链都通了。这一步常见的失败是黑屏但无报错此时在命令行加--log-level debug看详细日志通常会提示某个 tif 或 shp 文件找不到。第三层验证 Qt 集成。编译一个最小的 Qt 工程就是第 5 章那段代码运行后应该出现一个 Qt 窗口里面是可旋转缩放的地球。如果窗口出来但地球不显示按 6.3 的方法查数据路径如果窗口直接崩溃用 Dependency Walker 或dumpbin /dependents检查 exe 依赖的 DLL 是否都能找到。我自己的习惯是每次装完这套环境都会把这三层验证命令写成一个check.bat放在桌面。因为这套组合的依赖太多换一台机器或者重装系统后很容易某个 DLL 版本不对三层验证能快速定位是 OSG 层、osgEarth 层还是 Qt 层的问题。从那以后我每次部署新机器都强制走一遍这个检查链不再凭感觉“应该没问题”。希望帮到你。本文还有配套的精品资源点击获取
