简介面向VS2019 x64环境下集成OSG与OSGEarth的开发者这份资源提供完整的头文件包与OpenSceneGraph 3.7、osgearth-3.4、osgQt、SQLite3以及GDAL 3.0.4等组件对应可直接用于搭建三维地理信息应用的基础开发环境减少逐项编译和版本适配的繁琐工作。压缩包共2000个文件以hpp和h头文件为主1122个hpp、878个hhpp主要提供现代C接口与模板实现h则包含底层C风格声明覆盖渲染核心、地理数据抽象层、Qt交互封装与轻量级数据库接口整体约727MB。包内头文件包括glext.h、sqlite3.h、ogr_geometry.h等能够支撑从底层图形调用到空间数据读写的常见开发需求使用者可直接将这些头文件加入include目录用于链接工程、查看接口定义或排查编译问题。该资源已有123人学习下载适合具备一定C基础、希望快速获得稳定开发环境的中高级开发者可直接用于后续功能扩展与调试。1. 这一长串文件名其实是 Windows 三维 GIS 开发的第一道坎“VS2019编译 x64 OpenSceneGraph3.7 osgearth-3.4 osgQt sqlite3 release-1911-x64-gdal-3-0-4-ma” 这一串字符拆开看就是在 Windows 上用 VS2019 从源码把 OSGOpenSceneGraph3.7、osgEarth 3.4、osgQt 模块以及配套的 sqlite3 和 GDAL 3.0.4 全部编成 x64 Release 版。你搜这句话大概率是被 osgEarth 的 CMake 配置卡住了——明明按教程装了依赖configure 还是飘红或者编到一半报一堆 LNK 链接错误。这套工具链是三维地形可视化、数字孪生和仿真渲染的常见底座osgEarth 负责加载地形和影像OSG 负责底层渲染osgQt 负责把三维场景嵌进 Qt 界面而 sqlite3 和 GDAL 则承担矢量、栅格数据的读写。适合谁适合要在 Windows 上做三维 GIS 应用、又不想用商业引擎的开发者。这里有个反直觉的结论你以为把依赖库都装上就能顺利编译实际上 80% 的失败不是缺库而是版本配对和 CMake 变量指向的问题。这篇笔记从选版本开始把整套编译流程和最常见的坑一次讲清楚。2. 先定依赖版本为什么 GDAL 和 sqlite3 必须精确配对2.1 版本选型的三条铁律先别急着下载源码。OSG 3.7 和 osgEarth 3.4 对依赖库的版本有隐性要求官方文档从来不会直说只有在 CMake 配置和编译报错里才能看到端倪。我一般会先定三条铁律。第一GDAL 版本不能太新。osgEarth 3.4 的源码里对 GDAL 的 API 调用是基于 2.x 到 3.0 时代的写法GDAL 3.2 以上就把很多旧接口标记为 deprecated 甚至直接移除编译时会出现gdal_priv.h里某个函数找不到定义。标题里的 gdal-3-0-4-ma 这个版本号就是经过验证的可用版本ma后缀是预编译包作者标识你不需要纠结它只需锁定 GDAL 3.0.4 这个大版本。第二sqlite3 必须带扩展。osgEarth 在读取地理数据库时用了 sqlite3 的RTree空间索引扩展普通的官方预编译包不一定带这个扩展所以标题里单独列出 sqlite3 release-1911-x64这是指 sqlite3 的特定构建版本号1911 是 SQLite 的版本日期代码。第三Qt 版本要和 osgQt 模块匹配。OSG 3.7 的 osgQt 模块改成了新的 osgQOpenGL 接口这对应 Qt5 以上的版本如果你用的是 Qt 5.12 以下的老版本osgQt 的 CMake 配置会直接报错。提示锁定版本不是保守是 osgEarth 3.4 那个年代的代码就为这些版本写过适配。你非要用新 GDAL 去编译不是在写新功能而是在给旧代码打补丁成本远高于收益。2.2 文件清单与目录规划编译这套东西之前先把目录结构理清楚。我建议建一个统一的根目录比如D:\osg-dev下面分别放源码和依赖库。源码部分你需要准备 OpenSceneGraph-3.7.0 的源码包、osgEarth-3.4 的源码包、osgQt 模块OSG 源码里已经带了一部分但通常需要单独拉取对应版本。依赖库部分需要 sqlite3 的 release-1911-x64 预编译包、GDAL 3.0.4 的 x64 开发库要包含头文件、lib 和 bin、Qt5 的 x64 版本。文件规划这么做是有原因的。CMake 配置时你会反复修改依赖库路径如果源码和依赖库混在一起路径写起来容易出错而且不同版本的 GDAL 或 sqlite3 如果你以后要切换放在独立目录里可以直接改路径不用动源码。另外所有路径尽量不要带中文和空格CMake 的某些老模块对空格处理有缺陷D:\Program Files\osg-dev这种路径会带来麻烦。依赖库目录里需要你额外检查库里是否带cmake子目录。GDAL 3.0.4 预编译包的 cmake 配置文件是 osgEarth 能找到它的关键。如果下载的包里面只有 lib 和 include 没有 cmake 子目录你后面需要在 CMake 里手动指定 GDAL 的路径会增加配置工作量。3. 编译 OpenSceneGraph 3.7CMake 配置与三个必调参数3.1 用 CMake 生成 VS2019 工程OSG 3.7 的编译是整套流程的第一站也是后续 osgEarth 编译的基础。打开 CMake GUI源码目录选到 OpenSceneGraph 源码解压目录构建目录在源码同级建一个build文件夹。点 Configure编译器选 VS2019 x64注意是 x64不是 Win32平台选 x64。第一次 Configure 完成后重点检查三个变量。第一个是ACTUAL_DEPENDENCIES_DIR这个变量指向依赖库的根目录比如D:/osg-dev/dependenciesOSG 会在这个目录下找第三方库。第二个是CMAKE_INSTALL_PREFIX这是安装路径OSG 编译完成后会把头文件、lib、dll 和 cmake 配置文件装到这里后续 osgEarth 找 OSG 全靠这个目录下的 cmake 配置建议设成D:/osg-dev/install/osg。第三个是ALLOW_OSGQt_MODULE这个变量要勾选为 ON。默认情况下 OSG 3.7 的 osgQt 模块是关闭的不打开这个开关编译出来的 OSG 就没有 Qt 集成能力。Configure 可能会在 ZLIB、PNG 这些图片库上飘红。这些是 OSG 的可选依赖用于读取压缩格式的纹理图片。如果你不需要读取 PNG 压缩纹理可以直接忽略OSG 会禁用相关插件如果需要可以单独编译 zlib 和 libpng。但注意GDAL 库本身依赖 zlib如果你后面通过 GDAL 读数据实际上会间接用到 zlib所以建议把 zlib 也准备好避免 GDAL 在运行时因为找不到 zlib.dll 报错。3.2 编译与安装的正确姿势Configure 通过后点 Generate生成 VS2019 解决方案文件。打开OpenSceneGraph.sln在解决方案配置里选择 Release注意不要选 Debug后续 osgEarth 的 Release 版需要链接 OSG 的 Release 库混用会导致链接错误平台选 x64。编译整个解决方案时不要直接点全部生成而是先在解决方案资源管理器里找到ALL_BUILD项目右键选择生成。这样会按依赖顺序编译所有模块。整个过程大约需要 20 到 40 分钟取决于机器性能。编译完成后在解决方案资源管理器里找到INSTALL项目右键生成这一步会把编译产物安装到你在CMAKE_INSTALL_PREFIX里指定的目录。安装完成后检查安装目录下的结构。bin目录下应该有osg.dll、osgDB.dll等核心动态库lib目录下是导入库文件include目录下是头文件cmake目录下是 CMake 配置文件这个目录的存在与否直接关系到后面 osgEarth 能不能找到 OSG。如果cmake目录缺失九成是CMAKE_INSTALL_PREFIX配置出了问题或者 INSTALL 项目没跑成功。提示编译前先确认磁盘空间至少留 20GB。Release 版 调试符号 中间文件占空间比你想的大得多。空间不足会导致链接阶段报fatal error C1060那是编译器堆空间不够不是你的代码问题。3.3 验证 OSG 编译成果编译完成后把D:\osg-dev\install\osg\bin加入系统 PATH 环境变量然后在命令行里运行osgversion osgversion --build-number运行结果会显示 OSG 版本号和构建信息。如果输出版本号是 3.7.0 且无报错说明 OSG 核心模块编译成功。接下来测试插件模块osgplugins --list这个命令它会列出 OSG 支持的所有插件包括图片格式、模型格式等。重点检查是否有osgdb_gdal.dll这个插件是 OSG 通过 GDAL 读取地理数据的桥梁如果没有这个插件后续 osgEarth 加载地形时会报 “Failed to load plugin” 错误。GDAL 插件的编译依赖 OSG 在 CMake 配置时找到 GDAL 库如果这个插件缺失需要回到 CMake 重新检查 GDAL 的路径配置然后重新编译osgdb_gdal项目。4. 编译 osgEarth 3.4链接 GDAL 与 sqlite3 的完整过程4.1 CMake 配置里最容易翻车的地方osgEarth 3.4 的 CMake 配置是整个流程里最磨人的环节。源码解压后在 CMake 里设好源码目录和构建目录选择 VS2019 x64Configure。第一次 Configure 必然会飘红这是正常的因为 osgEarth 找不到 OSG 和依赖库的位置。先处理 OSG 的路径。在 CMake 变量列表里找到OPENSCENEGRAPH_INCLUDE_DIR和OPENSCENEGRAPH_LIBRARY手动指定为前面安装 OSG 的 include 目录和 lib 目录下的对应文件。正确设置后OPENSCENEGRAPH_INCLUDE_DIR应该指向D:/osg-dev/install/osg/includeOPENSCENEGRAPH_LIBRARY指向D:/osg-dev/install/osg/lib/osg.lib。这两个变量设置后CMake 会自动找到 OSG 的 cmake 配置文件并加载其余库路径。然后是 GDAL。找到GDAL_INCLUDE_DIR和GDAL_LIBRARY变量分别指向 GDAL 3.0.4 开发库的 include 目录和 lib 目录。GDAL 的 include 目录要能直接看到gdal_priv.hlib 目录里要有gdal.lib和gdal_i.lib两个导入库。这里的坑在于GDAL 预编译包的目录结构可能不是标准布局有的包把头文件放在include/gdal子目录里如果不仔细看就直接填根目录CMake 会报找不到头文件。设定完成后CMake 会显示找到 GDAL 的版本号比如GDAL_VERSION 3.0.4这个提示就是判断路径是否正确的重要信号。4.2 sqlite3 的链接参数与空间索引扩展sqlite3 的配置在 osgEarth 的 CMake 里相对隐蔽。找到SQLITE3_INCLUDE_DIR和SQLITE3_LIBRARY分别指向 sqlite3 预编译包的头文件目录和导入库文件。关键在于osgEarth 在编译时会检查 sqlite3 是否支持 RTree 空间索引检查方式是通过编译一个测试程序调用sqlite3_rtree相关的接口如果你的 sqlite3 没启用扩展CMake 会报一个警告。这个警告不阻断编译但会导致 osgEarth 在运行时无法创建空间索引打开大数据量矢量数据时会明显卡顿。验证 sqlite3 是否带 RTree 扩展的方法是用命令行工具跑一段 SQLSELECT load_extension(mod_spatialite); SELECT rtree_version();如果第二条查询返回版本号说明支持如果报错说明你的 sqlite3 没带扩展需要换一个带扩展的版本或者自己编译 sqlite3 时加上-DSQLITE_ENABLE_RTREE1编译选项。另外注意osgEarth 链接 sqlite3 时需要的是动态库版本。你下载的预编译包通常同时带静态库和动态库链接时要选带dll后缀的导入库不要选纯静态库否则 osgEarth 的 dll 会把 sqlite3 静态编译进去导致最终集成时出现 sqlite3 符号重复定义的链接错误。4.3 编译顺序与 Qt 模块集成osgEarth 的 CMake 配置完成后点 Generate生成 VS2019 解决方案。编译前先检查解决方案里是否有osgEarthQt项目。osgEarth 3.4 默认带 osgEarthQt 模块它依赖 OSG 的 osgQt 模块和 Qt 库。如果你前面编译 OSG 时打开了ALLOW_OSGQt_MODULE这里 osgEarthQt 就能正常生成如果没打开osgEarthQt 项目会缺失CMake 里关于 osgEarthQt 的变量也会是空值。在编译 osgEarth 之前需要先检查 Qt5 的版本。osgEarth 3.4 的 osgEarthQt 模块用到了 Qt5 的QOpenGLWidget这是 Qt 5.4 之后才加入的类所以 Qt 版本至少要 5.4我建议直接用 5.12 LTS 版本兼容性最好。CMake 里找到Qt5_DIR变量指向 Qt5 的lib/cmake/Qt5目录。Configure 通过后可以看到Qt5_DIR相关的变量不再是红色说明 Qt 路径可用。编译 osgEarth 时同样先编译ALL_BUILD然后INSTALL。安装目录建议单独设置CMAKE_INSTALL_PREFIX为D:/osg-dev/install/osgearth不要和 OSG 混在一起。osgEarth 的插件比如osgdb_earth.dll在运行时会在注册表和环境变量里找安装目录单独安装目录有助于后续排查插件加载问题。编译完成后照例把D:\osg-dev\install\osgearth\bin加入 PATH。验证 osgEarth 编译成果可以用 osgEarth 自带的命令行工具osgearth_version --version输出osgEarth 3.4就说明核心库编译成功。然后加载一个简单的 earth 文件测试osgearth_viewer --earth simple.earth这里的simple.earth是 osgEarth 源码包tests目录下的示例文件。如果弹出窗口正常显示地形说明 osgEarth 的渲染管线、GDAL 读取、sqlite3 缓存、osgQt 集成整个链路都是通的。如果报错先看 terminal 里有没有 “Failed to load plugin” 字样有就是插件路径问题没有继续看 GDAL 报错。5. 编译避坑指南我在这个工具链上踩过的五个实坑5.1 现象反复出现却在第三方库上翻车之前我第一次编译这套东西时osgEarth 的 CMake 配置全部通过Generate 也正常但一编译就报错提示找不到gdal_priv.h。反复检查 CMake 变量GDAL_INCLUDE_DIR 明明指向了正确目录最后发现是 GDAL 预编译包的头文件里有#include cpl_error.h而cpl_error.h在 GDAL include 目录的cpl子目录下。编译器搜索头文件时没有包含子目录解决方法是把include/cpl这个子目录也加到附加包含目录里。这个现象的本质是预编译包的目录结构不符合编译器默认搜索规范教训是用预编译包时先看头文件目录有没有cpl、gdal这样的子目录结构有就在 CMake 里多加一个INCLUDE_DIR变量。5.2 OSG 编译通过osgEarth 却报一堆链接错误OSG 3.7 自己编译没问题所有示例都能跑但 osgEarth 的 CMake 配置时找不到 OSG 库列出的是空的。排查发现osgEarth 找 OSG 不是直接找 dll 和 lib而是通过OpenSceneGraphConfig.cmake这个文件。这个文件在 OSG 的安装目录下cmake文件夹里如果你的 OSG 安装时CMAKE_INSTALL_PREFIX路径写错了或者安装目录被移动过这个文件里的路径就不匹配了。解决方法是回到 OSG 的 CMake 重新 Configure 和 INSTALL或者手动修改OpenSceneGraphConfig.cmake里的路径变量。这个文件记录的是绝对路径编译完成后移动安装目录就会失效这不是 bug是 CMake 的设计行为。5.3 运行时提示缺少osgDB.dll但 bin 目录里明明有这个坑的本质是 PATH 环境变量没有生效。Windows 下 PATH 变量是启动进程时读取的如果你把 OSG 的 bin 目录加进 PATH 后没有重启命令行窗口或 IDE它们仍然使用旧的 PATH导致 dll 加载失败。另外如果你同时在系统 PATH 和用户 PATH 里加了不同版本的 OSG 路径Windows 按 PATH 里的顺序加载先遇到的先生效可能装上老版本的 dll。排查方法是在命令行里执行where osgDB.dll会列出所有被找到的 dll 路径检查顺序是否符合预期。这个命令能有效定位 dll 加载位置的问题。5.4 地形加载出来一片空白控制台没有任何报错osgEarth 加载地形数据时数据源是 GDAL 读取的影像文件。空白通常意味着 GDAL 读到了数据但没有正确生成纹理坐标。这个问题的根源是 osgEarth 3.4 在读取某些 GeoTIFF 时对坐标参考系统CRS的识别的判断比较严格如果影像文件没有嵌入正确的投影信息osgEarth 默认按 EPSG:4326 处理而实际数据可能是其他投影纹理就会被映射到错误的位置。解决方法是先确认数据本身没问题用 GDAL 命令行工具查看数据信息gdalinfo your_image.tif看输出里的Coordinate System is:部分。如果显示WEB_MERCATOR或WGS 84osgEarth 应该能正确处理如果显示未知或不完整需要先用gdalwarp把数据重投影到 WGS84。很多时候不是 osgEarth 渲染有问题而是数据不符合预期。5.5 VS2019 编译报中文乱码osgEarth 源码里有些文件包含 UTF-8 编码的中文注释VS2019 默认按系统本地代码页GBK读取导致编译器报C4819警告通常是警告不是错误。这个警告不影响编译但会让输出信息很难看也容易掩盖真正的错误。解决方法是给编译器加/utf-8编译选项在 VS2019 的工程属性里C/C 高级选项下的“附加选项”加一行即可。这个选项让编译器按 UTF-8 处理源文件编码能避免这类乱码问题。6. 集成 osgQt 到自己的界面工程一步到位的验证思路到这里OSG 和 osgEarth 都编译完了最后一步是把 osgQt 模块用起来在自己的 Qt 工程里加载三维地形。新建一个 Qt Widgets Applicationx64 Debug 和 Release 都无所谓但不要混用——如果你 osgEarth 编的是 Release这里也要用 Release 配置链接混用会导致运行时崩溃。在 Qt 工程的.pro文件里按如下方式配置QT core gui widgets opengl INCLUDEPATH D:/osg-dev/install/osg/include \ D:/osg-dev/install/osgearth/include \ D:/Qt/5.12.9/msvc2017_64/include LIBS D:/osg-dev/install/osg/lib/osg.lib \ D:/osg-dev/install/osg/lib/osgDB.lib \ D:/osg-dev/install/osg/lib/osgGA.lib \ D:/osg-dev/install/osg/lib/osgViewer.lib \ D:/osg-dev/install/osg/lib/osgQt.lib \ D:/osg-dev/install/osgearth/lib/osgEarth.lib \ D:/osg-dev/install/osgearth/lib/osgEarthQt.lib这里的osgQt.lib是 OSG 3.7 的 osgQt 模块产物如果编译时没生成回到 OSG 的 CMake 检查ALLOW_OSGQt_MODULE是否打开。Qt 路径用的是 msvc2017_64这个目录包含在 Qt 5.12 的 VS2019 兼容安装里如果你用的是其他 Qt 版本改成对应的路径即可。在代码里核心的集成逻辑是创建一个 osgQt 的 OpenGL 窗口部件挂到 Qt 的布局里然后设置 osgEarth 的场景数据。这一步的关键是理解 osgQt 的接口变化。OSG 3.7 里 osgQt 模块的窗口类名是osgQOpenGLWidget它在 Qt5 里替代了老版本的osgQt::GLWidget。初始化时先生成一个 earth 文件的场景图挂到 osgEarth 的 MapNode 下然后把这个根节点交给 osgQOpenGLWidget 的 setSceneData 方法窗口就能渲染三维地形。测试工程只需要几十行代码但跑信息能确认一整条验证链OSG 渲染管线是否正常、osgEarth 能否读取地形文件、osgQt 是否成功桥接 Qt 和 OSG、GDAL 和 sqlite3 运行时依赖是否完整到位。最后给你一个我一直在用的验证习惯集成完成后把 osgEarth 自带的tests目录下所有.earth文件跑一遍每个文件对应不同的数据源和图层类型。跑通一半以上你的工具链基本就稳定了——这条路我走过很多遍踩过的坑都写在前面了按这个顺序编译至少能省掉一个通宵排查的时间希望帮到你。本文还有配套的精品资源点击获取
