简介面向需要在 MSVC2017 与 Qt 5.14/QtCreator 环境下集成 OSG 3.6.3 与 osgEarth 2.10 的 C/三维 GIS 开发者尤其适合被第三方库版本冲突、CMake 配置繁杂、编译时间长困扰的初学者。压缩包共 2000 个文件约 530.29 MB内容按头文件、库、插件、资源与示例工程系统组织hpp/h 头文件覆盖 osg/osgEarth 主要接口lib/dll 提供链接与运行支持exe 工具便于场景转换与调试earth/osg 文件包含典型场景描述frag/vert 着色器与 jpg/png 纹理为渲染效果提供素材shp/tif 等 GIS 数据可直接用于测试。整体目录结构完整便于按需查找。另附 pdb/ilk 符号文件、lua 脚本等调试与扩展素材省去自行收集散落依赖的麻烦。附带的简单 Qt 工程演示了如何在 Qt 窗口中加载 osgEarth 场景可作为新项目起点配合作者博文可快速重建开发环境。已有 532 人浏览学习适合希望减少环境搭建时间、直接进入三维可视化开发的研习者。 我这套环境包前后折腾了将近四周中途一度想把电脑扔出窗外。OSG 3.6.3、osgEarth 2.10、Qt 5.14三个库纯粹的版本对齐还只是一部分真正让我崩溃的是MSVC2017下的依赖大战好在最后把所有东西打到同一个7z包里才算彻底解脱。做这个压缩包的目的很简单让团队里任何一个新人拿到手就能跑起来三维GIS项目不用再花一周时间跟CMake和依赖库较劲。如果你也正在Windows上搞OSG或osgEarth开发这个包能帮你把环境搭建时间压缩到半小时以内。成品压缩包里面包含了完整的三方依赖、Qt库、所有插件DLL、头文件和CMake配置模块解锁、配置、运行三步走完就能看到你的第一个地球模型。1. 为什么会诞生这个压缩包三维GIS开发环境的老大难问题1.1 编译OSG和osgEarth本质上是一场依赖地狱的探险熟悉OpenSceneGraph和osgEarth的朋友应该深有体会Windows平台上源码编译这两个库是个典型的惊险一跳。OSG本身依赖zlib、libpng、libjpeg、tiff、giflib、freetype、sqlite3osgEarth在此基础上又要追加GDAL、CURL、protobuf、libzip、expat一堆东西。每次CMake配置都会弹出一堆红色的未找到提示你以为装上依赖就完事了实际上还有版本匹配、Debug和Release库混用、运行库动态/静态不统一等一系列暗坑等着你。我最初几次编译都卡在一个诡异的问题上OSG编译完成插件正常运行但加载geotiff格式影像时总是白屏。排查到最后发现是libtiff库版本和GDAL的冲突编译时用的libtiff 4.0.6GDAL内部却链接了4.0.3的符号导致运行时数据错乱。这种问题百度都查不到只能自己拉出来一个个试。1.2 为什么坚持一个包全带走传统的环境搭建方式无非三种一是自己源码编译全部依赖二是用vcpkg或conan三是下载别人散装的预编译库。三个方案各有利弊但对做项目交付的团队来说都不友好。自己编译要花时间vcpkg对老版本支持不完整散装包经常缺东少西。最后决定把重复劳动一次做完——我先在纯净的Windows MSVC2017环境下把所有依赖编译好调试通过全部功能后把bin、lib、include、CMake模块统一整理用7z重新打包。这就是你这个压缩包的来历。整个包没有动系统环境变量全部采用相对路径和可迁移的目录结构解压之后不依赖注册表也不污染系统任何机器上都能直接展开使用。2. 这个压缩包里的版本组合各自解决什么问题2.1 MSVC2017为什么要锁死一个版本C开发的都清楚MSVC的ABI兼容性是个严肃问题。MSVC2015、2017、2019的主版本号分别是19.0、19.1、19.2运行时库和标准库实现都有差异。OSG和osgEarth的预编译二进制都对编译器版本很敏感不同版本编译的库直接混用轻则链接报警告重则程序启动就崩溃。这个包从头到尾锁定MSVC2017即Visual Studio 15.x系列编译等于解决了底层ABI一致性问题。如果你的项目是用VS2019或2022打开的也不用太担心。C代码层面兼容用CMake设置工具链还是能正常链接只是遇到老式C API时需要简单适配毕竟OSG 3.6.3这个版本的历史感摆在那里。2.2 OSG 3.6.3和osgEarth 2.10的匹配逻辑OSG和osgEarth的版本对应关系没有官方明确承诺但社区实践有迹可循。osgEarth 2.10要求OSG最低版本3.4.0我自己实测下来OSG 3.6.3配合osgEarth 2.10是目前最稳定的组合之一比OSG 3.7系列更稳妥因为3.7开始对部分插件的API做了破坏性调整osgEarth某些功能需要额外打补丁才能编译过。Qt选5.14.7z也是从稳定性和OSG的osgdb_qt插件适配角度考虑的。Qt 5.15之后开源版本对Windows的支持开始收紧5.14是Qt 5里最后一道还在持续维护的稳定支线。osgEarth 2.10的渲染窗口集成模块跟Qt 5.14的QOpenGLWidget搭档起来很顺编译期不用额外改任何源码运行时也不会有glGetString返回空指针这类经典问题。2.3 包内包含的完整目录结构展开压缩包后你会看到以下核心目录osgosgearthqt/ ├── bin/ # 所有DLL、可执行文件和插件dll │ ├── osgPlugins-3.6.3/ # OSG核心插件 │ └── osgdb_osgearth/ # osgEarth插件 ├── lib/ # 静态库和导入库 ├── include/ # 全部头文件 ├── cmake/ # CMake配置模块 └── share/ # 资源和样例数据DLL全部集中在bin目录不像某些预编译包把DLL分散在多个目录里配置PATH时只需要加一条路径就能覆盖所有运行时搜索需求。osgPlugins-3.6.3和osgdb_osgearth两个插件目录也在bin下OSG的插件查找规则会自动搜索可执行文件同级目录下的插件文件夹所以运行时不会出现插件加载失败的提示。3. 解压之后怎么让项目跑起来环境配置的完整手记3.1 三分钟内完成的初始配置拿到压缩包解压路径建议不要带中文和空格比如D:\SDK\osg-osgearth-qt。然后做三个设置第一步添加环境变量。新建一个OSG_ROOT指向解压根目录把%OSG_ROOT%\bin追加到PATH。osgEarth开发还会读取OSGEARTH_ROOT两个变量指向同一个根目录即可。第二步Qt对接。Qt本身就通过CMake传入路径不需要设置全局环境变量。但如果你要在命令行里跑osgviewer测试Qt插件可以把Qt的bin目录也加入PATH否则运行时找不到Qt5Cored.dll会报启动错误。第三步验证。打开终端执行osgversion osgearth_version --caps两个命令都能正确输出版本信息说明环境和插件都正常。3.2 在CMake中对接这套环境项目CMakeLists.txt里推荐直接使用包自带的CMake配置文件不需要去系统目录乱翻。下面是实测可用的最小化配置示例cmake_minimum_required(VERSION 3.10) project(MyEarthApp) # 指定OSG和osgEarth的安装前缀 set(CMAKE_PREFIX_PATH $ENV{OSG_ROOT} $ENV{OSGEARTH_ROOT}) find_package(OpenSceneGraph REQUIRED COMPONENTS osgDB osgGA osgUtil osgViewer osgText) find_package(osgEarth REQUIRED) include_directories(${OPENSCENEGRAPH_INCLUDE_DIRS} ${OSGEARTH_INCLUDE_DIRS}) link_directories(${OPENSCENEGRAPH_LIBRARY_DIRS} ${OSGEARTH_LIBRARY_DIRS}) add_executable(MyEarthApp main.cpp) target_link_libraries(MyEarthApp ${OPENSCENEGRAPH_LIBRARIES} ${OSGEARTH_LIBRARIES} )这里CMAKE_PREFIX_PATH是关键CMake会优先到这两个路径下查找OpenSceneGraph和osgEarth的config模块不会跟系统中安装的其他版本冲突。3.3 一个能直接跑起来的入门示例环境配好之后不妨写个最简单的程序测试osgEarth加载在线影像能出来地球就算全链路通了#include osgEarth/MapNode #include osgEarth/Map #include osgViewer/Viewer #include osgEarthDrivers/xyz/XYZOptions using namespace osgEarth; int main(int argc, char** argv) { osg::ref_ptrMap map new Map(); // 使用XYZ瓦片图层作为底图 osg::ref_ptrxyz::XYZOptions opt new xyz::XYZOptions(); opt-url() https://some-tile-server.com/{z}/{x}/{y}.png; map-addLayer(new ImageLayer(base, opt.get())); osg::ref_ptrMapNode mapNode new MapNode(map.get()); osgViewer::Viewer viewer; viewer.setSceneData(mapNode.get()); return viewer.run(); }链接依赖库和头文件都指向包含包里的lib和include目录构建成功后运行看到三维地球并成功加载瓦片说明整个工具链完全正常工作。4. 预编译包最容易踩的坑插件搜索路径和运行时依赖问题4.1 osgPlugins目录不是你想想中那样按固定路径查找的使用预编译包时最常遇到的坑是编译通过但运行时报找不到osgdb_osgearth_xyz.dll或者加载earth文件时提示无法解析插件。很多人会去检查PATH里有没有把osgearth插件目录加上其实这不是PATH的问题。OSG运行时搜索插件的顺序是先看当前工作目录再看可执行文件所在目录最后检查环境变量OSG_LIBRARY_PATH。预编译包把插件放在bin\osgdb_osgearth下如果你的程序启动时工作目录不在bin下又没有显式设置OSG_LIBRARY_PATH就会报插件找不到。解决办法是在main函数最前面加上一行osgDB::Registry::instance()-setLibraryFilePathList(D:/SDK/osg-osgearth-qt/bin);或者直接设置环境变量OSG_LIBRARY_PATH指向bin目录。推荐后者一劳永逸不用改代码。4.2 Qt运行时DLL的搜索顺序和常见的双击崩溃之前的包在别人电脑上出现过双击exe直接弹错误框提示找不到Qt5Cored.dll或Qt5Guid.dll。原因是Qt的DLL搜索机制跟普通Windows程序不太一样默认不会搜索exe同级的子目录只会在exe当前目录和PATH里找。解决办法有两个一是把Qt的bin目录加入PATH简单粗暴但有效二是把Qt的DLL复制到exe目录下适合发布给终端用户。我通常推荐第二种方式因为发布程序时不会要求客户去装Qt环境。注意Debug和Release对应DLL不能混Qt5Cored.dll是Debug版本Qt5Core.dll才是Release版本这个d字母是血泪教训。4.3 一个隐藏很深的坑插件DLL本身还依赖QT DLL这个坑藏得极其隐蔽一度让我怀疑人生。osgEarth的qt插件本身依赖Qt的platforms和imageformats模块如果你只把Qt的bin加入PATH但平台的插件目录没配好启动时会黑屏但没有任何崩溃提示。查日志发现是无法加载QWindowsIntegrationPlatformPlugin这是Qt的platform插件在作怪。解决方式比较简单把Qt目录下的plugins\platforms和plugins\imageformats这两个文件夹复制到exe同级目录下。但需要注意如果你把exe放在了项目的build目录每次重新编译后这个目录会被清空所以建议在CMake里加一个自定义命令自动复制别手动做这种重复劳动。5. 这套工作流值不值得投入编译成本、使用边界和我的经验体会5.1 自己编译一遍需要多久可能遇到哪些耗时大项很多人会问为什么不直接上传一份本源码让大伙自己编因为成本太悬殊。我最初在四核八线程的老机器上编译OSG全量插件一个release版本要将近1小时加上osgEarth和所有依赖单轮编译到打包顺利情况下需要三四个小时。如果过程中发现某个依赖选型不对改一个配置就是又一轮全量重编。依赖库里最耗时的是GDAL和Qt的集成。GDAL编译时如果打开全部驱动单个文件编译时间长得可以去做顿饭Qt集成则涉及到OSG插件osgdb_qt的编译需要精确对齐Qt版本和MSVC编译选项。这两个模块总共能占据整体编译时间的四成以上想省时间的话GDAL只需要编译核心库和常见栅格驱动不需要把全部四百多个驱动全拉出来编译。5.2 这个包适合谁不适合谁如果你的项目是用CMake构建、需要跨平台或者打算长期维护这个预编译包非常合适因为背后依赖链和插件全部配齐你只需要把精力集中在业务功能上。但如果你是研究底层渲染算法、需要频繁改动OSG或osgEarth源码的预编译包就不适合了还是从源码编译一套自定义环境更灵活。另外如果你的目标平台是Linux服务器或嵌入式设备这个Windows专用包也用不上直接看官方文档做交叉编译更实际。5.3 我踩过几次坑之后的建议从我自己的经验来说有几点建议值得放在前面提醒你。一是拿到压缩包后第一时间用osgversion和osgearth_version验证基础环境别等写完几百行代码才发现插件路径配置有问题。二是项目CMakeLists里千万不要写死绝对路径用环境变量引用这个SDK的位置这样换电脑或迁移项目时不用改一行代码。三是如果你的系统里之前装过其他版本的OSG或osgEarth务必在CMake缓存里清理干净旧路径否则find_package会优先找到旧版本链接出各种诡异的符号错误。四是Debug和Release的库文件尽量不要混用这个包目录下我没做交叉混编处理你用Debug编译的exe就让它去链Debug版本DLLRelease同理省得出现内存问题排查一整晚。最后说一个我使用过程中最值回票价的操作把DLL全部集中在bin目录之后所有项目的运行时环境统一成一个环境变量排查DLL问题时只需要看一个路径不用满系统找各种不同位置的库文件。这个包我自己用了一年多中间迁移了三台电脑每次都只需要解压、配环境变量、跑测试程序十分钟搞定。希望它也能帮你从那场无穷无尽的依赖编译大战里彻底解脱出来。本文还有配套的精品资源点击获取