简介本资源面向使用 MSVC2017 进行三维地理可视化开发的 C 工程师与 Qt 桌面应用开发者提供一套可直接编译运行的 OSG 3.6.3 与 osgEarth 2.10 集成环境并附带一个简单 Qt 工程示例帮助读者省去自行编译第三方库的繁琐过程快速搭建地球场景与三维渲染原型。压缩包约 530MB共约 2000 个文件以 hpp 与 h 头文件为主配合 dll、lib、pdb、ilk 等编译链接产物另有 earth、shp、tif、osgb 等地理数据与模型资源以及 frag、vert、lua、qml 等渲染与脚本文件覆盖开发、调试与运行所需。目前已有 536 人学习下载。借助其中的 Qt 工程与库文件读者可对照参考文章完成环境配置理解 OSG 与 osgEarth 的目录组织、依赖关系与调用方式并在此基础上扩展自己的三维 GIS 应用。1. 从一次编译翻车说起msvc2017 osg3.63 osgEarth2.10 Qt5.14 这套组合到底难在哪有个做三维可视化的朋友在群里发了一张截图满屏的 LNK2019 和 LNK2001末尾一行写着无法解析的外部符号。他用的正是 msvc2017 编译 osg3.63再叠上 osgEarth2.10最后想塞进 Qt5.14 的 QWidget 里显示。这套组合在桌面端三维 GIS 和仿真项目里太常见了常见到几乎每个做 OSG 的人都会走一遍但真正能一次编过的没几个。问题不在某个库本身而在四者之间的版本咬合MSVC 的工具集版本、OSG 的第三方依赖、osgEarth 对 GDAL/PROJ 的链接方式、Qt 的构建套件任何一处对不上就是几小时的链接报错。这篇笔记按我实际装过的顺序把环境列清、把编译参数写死、把翻车点标出来适合第一次搭这套环境的人照着走也适合被 LNK 折磨过想复盘的人。2. 装之前先把版本和目录定死msvc2017 工具集与依赖清单2.1 为什么是 msvc2017 而不是更新的工具集osg3.63 和 osgEarth2.10 这两个版本都停留在 2019 年前后它们的 CMake 脚本里对MSVC_VERSION的判断、对std::filesystem的用法都是按 VS2017工具集 v141写的。如果你用 VS2019 的 v142 或 VS2022 的 v143 去编大概率会在 osgEarth 的GDAL驱动或PROJ转换那块遇到 C17 标准差异导致的编译错误。常见做法是装 Visual Studio 2017安装时勾选「使用 C 的桌面开发」确保VC\Tools\MSVC\14.16.xxxxx这个目录存在。命令行里用vcvarsall.bat x64初始化环境后面所有编译都在这个 x64 原生工具命令提示符里做别用默认的 x86。:: 在 VS2017 的 x64 Native Tools Command Prompt 里执行 call C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat x64 cl :: 输出应显示 19.16.xxxxx for x64确认工具集版本这段的作用是确认当前 shell 的编译器版本。vcvarsall.bat x64会把cl.exe、link.exe、rc.exe的路径和INCLUDE、LIB环境变量都指向 x64 工具集。如果cl输出的版本不是 19.16 开头说明你进错了命令行后面 CMake 生成的工程会混用工具集链接阶段必炸。2.2 目录规划把源码、依赖、安装前缀分开我一般会建一个根目录比如D:\dev\osg_stack下面分四个子目录src放源码3rdparty放预编译依赖build放 CMake 生成物install放最终安装结果。这样做的原因是 OSG 和 osgEarth 的 CMake 都支持CMAKE_INSTALL_PREFIX把安装前缀统一到install下Qt 工程里配置 include 和 lib 路径时只需要指一个根不用满硬盘找头文件。目录用途示例路径src存放 OSG、osgEarth 源码D:\dev\osg_stack\src\osg-3.6.33rdparty第三方预编译库D:\dev\osg_stack\3rdpartybuildCMake 构建目录D:\dev\osg_stack\build\osginstall统一安装前缀D:\dev\osg_stack\install第三方依赖这块OSG 官方推荐用3rdParty预编译包但那个包比较老里面的 zlib、libpng 版本和 osgEarth2.10 需要的 GDAL 可能对不上。我的做法是zlib、libpng、libjpeg、libtiff、freetype 用 vcpkg 装 x64-windows 版本GDAL 和 PROJ 单独下源码用 msvc2017 编因为 osgEarth 对 GDAL 的版本敏感2.10 配 GDAL 2.4.x 比较稳配 GDAL 3.x 会在OGRFeature接口上报错。2.3 环境变量与 CMake 生成器的选择CMake 生成器必须选Visual Studio 15 2017 Win64不要选 Ninja除非你确定 Ninja 调用的也是 v141 工具集。在 CMake GUI 里CMAKE_INSTALL_PREFIX填D:/dev/osg_stack/installBUILD_MFC_EXAMPLE关掉BUILD_OSG_EXAMPLES按需开。OSG 的ACTUAL_3RDPARTY_DIR指向3rdparty目录CMAKE_DEBUG_POSTFIX设成d这样 debug 版库是osgd.librelease 版是osg.libQt 工程里切换构建类型时不会混。:: 在 build\osg 目录下执行 cmake ..\..\src\osg-3.6.3 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg_stack/install ^ -DACTUAL_3RDPARTY_DIRD:/dev/osg_stack/3rdparty ^ -DCMAKE_DEBUG_POSTFIXd ^ -DBUILD_MFC_EXAMPLEOFF-G指定生成器^是 Windows 命令行的续行符。CMAKE_DEBUG_POSTFIXd这个参数很关键它让 debug 库带d后缀避免和 release 库同名覆盖。ACTUAL_3RDPARTY_DIR告诉 OSG 去哪里找 zlib、libpng 这些依赖的头文件和 lib。生成完用cmake --build . --config Release --target INSTALL编译并安装debug 版同理把--config换成Debug。3. 编译 osg3.63 与 osgEarth2.10参数怎么填、依赖怎么链3.1 OSG 3.6.3 的编译与安装OSG 的编译相对独立只要第三方依赖找得到一般能过。但有几个 CMake 选项要手动确认ZLIB_INCLUDE_DIR、ZLIB_LIBRARY、PNG_LIBRARY、JPEG_LIBRARY这些如果 vcpkg 装好了CMake 会自动找到如果找不到就在 CMake GUI 里手动指到3rdparty对应目录。OSG_USE_UTF8_FILENAMES建议打开中文路径下加载模型不会乱码。编译时用 Release 和 Debug 各来一遍因为 Qt 工程调试时需要 debug 版 OSG 库。:: 编译并安装 Release 版 cmake --build . --config Release --target INSTALL :: 编译并安装 Debug 版 cmake --build . --config Debug --target INSTALL--target INSTALL会把头文件、lib、dll、可执行文件按CMAKE_INSTALL_PREFIX的目录结构拷过去。装完后install\include\osg下应该有Version.hinstall\lib下应该有osg.lib、osgd.lib、osgDB.lib、osgDBd.lib等。如果install\bin下没有 dll检查 CMake 里的CMAKE_INSTALL_SYSTEM_RUNTIME_LIBS是否被关掉了。3.2 osgEarth 2.10 对 GDAL 和 PROJ 的链接方式osgEarth2.10 的 CMake 会去找GDAL和PROJ它默认用find_package(GDAL)但 Windows 下 GDAL 的 CMake 配置经常不完整。我一般直接指定GDAL_INCLUDE_DIR和GDAL_LIBRARYPROJ 同理。GDAL 用 2.4.4 版本PROJ 用 5.2.0这两个版本和 osgEarth2.10 的接口匹配。编译 osgEarth 前确保 OSG 的OSG_DIR指向install\lib\cmake\osg或者手动设OSG_INCLUDE_DIR和OSG_LIBRARY。cmake ..\..\src\osgearth-2.10 ^ -G Visual Studio 15 2017 Win64 ^ -DCMAKE_INSTALL_PREFIXD:/dev/osg_stack/install ^ -DOSG_INCLUDE_DIRD:/dev/osg_stack/install/include ^ -DOSG_LIBRARYD:/dev/osg_stack/install/lib/osg.lib ^ -DOSGDB_LIBRARYD:/dev/osg_stack/install/lib/osgDB.lib ^ -DGDAL_INCLUDE_DIRD:/dev/osg_stack/3rdparty/gdal/include ^ -DGDAL_LIBRARYD:/dev/osg_stack/3rdparty/gdal/lib/gdal.lib ^ -DPROJ_INCLUDE_DIRD:/dev/osg_stack/3rdparty/proj/include ^ -DPROJ_LIBRARYD:/dev/osg_stack/3rdparty/proj/lib/proj.lib ^ -DCMAKE_DEBUG_POSTFIXd这里每个-D都是在补 CMake 自动查找的缺口。OSG_LIBRARY只指了osg.lib但 osgEarth 还会链osgUtil、osgViewer、osgText这些 CMake 会通过OSG_LIBRARY所在目录去推所以install\lib下必须有完整的 OSG 库。GDAL 和 PROJ 的 lib 路径要指到具体文件不能只给目录否则 CMake 会报GDAL_LIBRARY is not set。编译时如果遇到PROJ的pj_init_plus找不到说明 PROJ 版本不对换 5.2.0 重编。3.3 把 osgEarth 的插件和数据路径配好osgEarth 编译完会生成一堆插件 dll放在install\bin\osgPlugins-3.6.3下。运行时 osgEarth 会去OSG_LIBRARY_PATH或可执行文件同级的osgPlugins目录找这些插件。我一般把install\bin加到系统PATH然后在 Qt 工程里用osgDB::Registry::instance()-getLibraryFilePathList()把插件路径加进去。数据路径方面osgEarth 需要osgEarth\resources下的 shader 和纹理这些在安装时已经拷到install\share\osgearth代码里用osgEarth::Registry::instance()-getDefaultOptions()时它会自动找。// Qt 工程初始化时设置 OSG 插件路径 osgDB::Registry* reg osgDB::Registry::instance(); reg-getLibraryFilePathList().push_back(D:/dev/osg_stack/install/bin/osgPlugins-3.6.3); // 设置 osgEarth 资源路径 osgEarth::Registry::instance()-setDefaultResourcePath(D:/dev/osg_stack/install/share/osgearth);这段代码放在main函数里、创建 viewer 之前。getLibraryFilePathList()返回的是一个FilePathListpush 进去的路径会被osgDB::readNodeFile用来找插件。setDefaultResourcePath告诉 osgEarth 去哪里读resources下的文件不设的话地球加载出来是黑的因为 shader 没找到。4. Qt5.14 集成 osgEarthQWidget 嵌入与构建套件配置4.1 Qt5.14 的安装与 msvc2017 套件Qt5.14 在线安装时组件里要勾MSVC 2017 64-bit这个套件对应的就是 v141 工具集。装完后在 Qt Creator 的「工具 选项 构建和运行 构建套件」里确认Desktop Qt 5.14.2 MSVC2017 64bit这个套件存在编译器选Microsoft Visual C Compiler 15.0 (x86_amd64)。如果编译器列表里没有手动添加路径指向 VS2017 的VC\Tools\MSVC\14.16.xxxxx\bin\Hostx64\x64\cl.exe。# Qt 工程 .pro 文件里配置 OSG 和 osgEarth OSG_DIR D:/dev/osg_stack/install INCLUDEPATH $$OSG_DIR/include LIBS -L$$OSG_DIR/lib -losg -losgDB -losgViewer -losgUtil -losgGA -losgText LIBS -L$$OSG_DIR/lib -losgEarth -losgEarthUtil -losgEarthAnnotation.pro里LIBS的顺序有讲究-losgEarth依赖-losg所以 osgEarth 的库要放在 OSG 库后面。INCLUDEPATH指到install/include这样#include osgViewer/Viewer和#include osgEarth/MapNode都能找到。debug 构建时 Qt 会自动加d后缀去找osgd.lib前提是.pro里没有硬编码库名用-l让 qmake 自己拼。4.2 用 QWidget 承载 osgQOpenGLWidgetQt5.14 集成 OSG 有两种方式一种是osgQt里的QGLWidget但那个在 Qt5.14 下已经过时另一种是用osgQOpenGL库它提供一个osgQOpenGLWidget直接继承QOpenGLWidget。osg3.63 的源码里带了osgQOpenGL例子但没编成库。我一般从 osg 源码的examples\osgQOpenGL里把osgQOpenGLWidget.cpp和头文件拷到工程里或者单独编一个静态库。// 在 Qt 窗口里嵌入 osgQOpenGLWidget #include osgQOpenGLWidget.h #include osgViewer/Viewer #include osgEarth/MapNode osgQOpenGLWidget* osgWidget new osgQOpenGLWidget(this); osgViewer::Viewer* viewer osgWidget-getOsgViewer(); osg::Node* earth osgDB::readNodeFile(D:/data/earth.earth); viewer-setSceneData(earth); viewer-setCameraManipulator(new osgEarth::Util::EarthManipulator()); osgWidget-setGeometry(0, 0, width(), height());osgQOpenGLWidget构造时会创建QOpenGLContextgetOsgViewer()返回内部的osgViewer::Viewer。setSceneData把 osgEarth 的 earth 文件加载进来EarthManipulator提供地球的旋转缩放操作。setGeometry让 widget 填满父窗口。如果运行时地球不显示检查osgQOpenGLWidget的initializeGL是否被调用有时候需要手动show()一下。4.3 运行时 dll 的部署与 PATH 设置Qt 工程编译出的 exe 运行时需要能找到 OSG、osgEarth、GDAL、PROJ 的 dll。最省事的做法是把install\bin、3rdparty\gdal\bin、3rdparty\proj\bin都加到系统PATH或者用 Qt 的windeployqt把 Qt 相关 dll 拷到 exe 同级再手动把 OSG 那堆 dll 也拷过去。我一般写一个deploy.bat编译完自动拷。:: deploy.bat 把运行时 dll 拷到输出目录 set OUTD:\dev\osg_stack\build\myapp\Release copy D:\dev\osg_stack\install\bin\*.dll %OUT% copy D:\dev\osg_stack\3rdparty\gdal\bin\*.dll %OUT% copy D:\dev\osg_stack\3rdparty\proj\bin\*.dll %OUT% xcopy D:\dev\osg_stack\install\bin\osgPlugins-3.6.3 %OUT%\osgPlugins-3.6.3 /E /Icopy把 dll 拷到 exe 同级xcopy /E /I把插件目录整个拷过去。这样 exe 在没配PATH的机器上也能跑。注意osgPlugins-3.6.3这个目录名要和 OSG 版本一致osgEarth 读插件时按这个目录名找。5. 避坑与排查msvc2017 编译 osgEarth 时最常见的 5 个翻车点5.1 LNK2019 无法解析的外部符号指向 GDAL 的 OGRFeature现象编译 osgEarth 的OGRFeatureSource时链接报无法解析的外部符号 public: virtual __cdecl OGRFeature::~OGRFeature(void)。原因GDAL 的 lib 和头文件版本不匹配或者 GDAL 是用 v142 工具集编的和当前 v141 的 ABI 不兼容。解决换 GDAL 2.4.4 源码用同一个 msvc2017 命令行重新编编的时候CMAKE_DEBUG_POSTFIX也设成d确保 debug 和 release 的 lib 都生成。5.2 运行时地球黑屏控制台报找不到 shader现象Qt 窗口里地球加载出来是纯黑控制台输出Warning: could not find shader file skinning.vert。原因osgEarth::Registry的默认资源路径没设或者install\share\osgearth目录没被拷到运行环境。解决在main里调setDefaultResourcePath或者把install\share\osgearth整个拷到 exe 同级osgEarth 会按相对路径找。5.3 Qt 工程 debug 构建时链接到 release 版 OSG 库现象debug 构建的 exe 运行时报MSVCP140.dll版本冲突或者堆损坏。原因.pro里LIBS写死了-losgqmake 在 debug 下没加d后缀链到了 release 库。解决.pro里用-losg而不是-losgd让 qmake 根据CONFIG自动加d同时确认install\lib下osgd.lib存在。5.4 osgEarth 编译时 PROJ 的 pj_init_plus 找不到现象链接 osgEarth 的SpatialReference时报无法解析的外部符号 pj_init_plus。原因PROJ 版本是 6.x 或 7.x这些版本把pj_init_plus改成了proj_create接口不兼容。解决换 PROJ 5.2.0或者改 osgEarth 源码里的 PROJ 调用但改源码工作量大换版本更省事。5.5 Qt Creator 里构建套件选错导致 CMake 重新生成现象在 Qt Creator 里打开 CMake 工程构建时提示CMAKE_CXX_COMPILER不匹配。原因Qt Creator 默认用 Ninja 生成器而之前命令行用的是 VS 生成器两者工具集不同。解决在 Qt Creator 的「项目 构建设置」里把 CMake 生成器改成Visual Studio 15 2017 Win64或者干脆在命令行编好Qt Creator 只用来写代码和调试。6. 装完怎么验证从 osgViewer 到 Qt 窗口的跑通检查验证这套环境是否真的跑通不能只看编译过没过得让地球在 Qt 窗口里转起来。我一般分三步走先单独跑 OSG 的osgViewer加载一个 cow.osg确认 OSG 本身没问题再跑 osgEarth 的osgearth_viewer加载一个 earth 文件确认 osgEarth 和 GDAL 没问题最后在 Qt 工程里嵌入osgQOpenGLWidget确认 Qt 集成没问题。第一步命令行跑osgViewer cow.osg。如果窗口弹出来能看到牛说明 OSG 的 dll、插件、OpenGL 上下文都正常。如果报could not find plugin to read检查osgPlugins-3.6.3目录是否在PATH或 exe 同级。第二步跑osgearth_viewer earth.earth。earth 文件里至少要有image和elevation两层image 可以指一个本地 tifelevation 指一个本地 dem。如果地球出来是平的或者黑的看控制台有没有GDAL相关的报错通常是 GDAL 数据路径不对或者 PROJ 的proj.db没找到。PROJ 5.2.0 需要proj.db文件一般在share\proj下运行时要把这个目录加到PROJ_LIB环境变量。:: 设置 PROJ 数据路径 set PROJ_LIBD:\dev\osg_stack\3rdparty\proj\share\proj osgearth_viewer earth.earthPROJ_LIB指向proj.db所在目录不设的话 osgEarth 做坐标转换时会报Cannot find proj.db。第三步Qt 工程里跑起来后用osgViewer::Viewer::getCamera()检查getGraphicsContext()是否非空非空说明 OpenGL 上下文创建成功。再检查viewer-getSceneData()是否非空非空说明 earth 文件加载成功。最后看帧率如果帧率是个位数检查是不是开了OSG_NOTIFY_LEVELDEBUG导致日志刷太多关掉再跑。验证项命令/代码通过标准OSG 基础osgViewer cow.osg窗口显示牛模型osgEarth 数据osgearth_viewer earth.earth地球带影像和地形Qt 集成osgQOpenGLWidget setSceneData窗口内地球可旋转缩放坐标转换EarthManipulator 操作经纬度跳转正常从那以后我每次搭这套环境都会先把vcvarsall.bat x64跑一遍确认工具集再把PROJ_LIB和OSG_LIBRARY_PATH写进启动脚本最后用osgearth_viewer加载一个最小 earth 文件做冒烟测试。这套流程走完Qt 工程里再出问题基本就是代码层面的不是环境层面的了。希望帮到你。本文还有配套的精品资源点击获取