简介本资源为在 Windows 10 与 Visual Studio 2019 环境下完整编译的 OpenSceneGraph 3.6.5 与 osgEarth 3.1 三维图形库面向从事三维可视化、GIS 地球渲染与虚拟仿真开发的 C 工程师可省去自行编译配置的繁琐过程直接投入项目使用。压缩包共 1325 个文件约 53.55MB包含 bin、include、lib 三个目录其中 302 个 dll 与 38 个 lib 覆盖 release、debug 双版本运行与链接需求另有大量头文件、插件配置、着色器、地形与图层模块等具备完整依赖。目前已有 855 人学习下载。资源经多次编译与反复测试目录结构清晰可直接用于 osgEarth 地球场景搭建、影像与高程图层加载、模型渲染及交互操作帮助开发者快速验证功能、排查环境问题是三维图形开发中省时可靠的编译成果。1. 拿到 Osg3.6.5-OsgEarth3.1-x64-vs2019-release-debug-win10 编译库先搞清楚它能省掉哪三天如果你在 Win10 上从源码编译过 OsgEarth大概率经历过这样的循环CMake 配置报错、第三方依赖找不到、GDAL 链接失败、Debug 和 Release 混用导致运行时崩溃一轮下来两三天就没了。Osg3.6.5-OsgEarth3.1-x64-vs2019-release-debug-win10.rar 这个完整编译库本质上就是有人替你把这条链路走通了把 OpenSceneGraph 3.6.5 和 OsgEarth 3.1 在 VS2019 工具链下编好的 x64 库、头文件、依赖 DLL 打包在一起同时提供 Release 和 Debug 两套产物。它解决的核心问题是环境一致性你不需要再纠结 CMake 该勾哪个选项、第三方库该用哪个版本、Debug 版和 Release 版能不能混链。适合谁做三维 GIS、战场态势、飞行仿真、数字孪生这类需要加载地形影像和矢量数据的 C 开发者尤其是团队里没人专门维护编译环境、但又必须快速出原型的情况。这一章先把「这个包到底是什么、能给你什么」讲清楚后面几章再拆怎么用、怎么配、怎么排错。2. 拆开这个编译库目录结构、依赖关系与 VS2019 工具链匹配2.1 一个典型的 OsgEarth 编译产物里应该有什么拿到压缩包解压后不要急着往项目里塞。先花五分钟把目录结构看清楚这决定了你后面配置包含目录和库目录时会不会翻车。一个完整的 OsgEarth 编译库通常包含以下几类内容目录/文件作用你需要关注的点include/osg/OSG 核心头文件版本号确认 3.6.5include/osgEarth/OsgEarth 核心头文件版本号确认 3.1lib/或lib/x64/.lib 导入库区分 Release 和 Debugbin/或bin/x64/.dll 动态库运行时必须与 .lib 匹配3rdparty/第三方依赖GDAL、PROJ、CURL 等最容易缺的就是这里plugins/osgDB 插件读影像、地形、模型少了就读不了 jpg/tif/earthRelease 和 Debug 的区别不只是优化等级。Debug 版链接的是osgDBd.lib、osgEarthd.lib这类带d后缀的库Release 版链接的是不带后缀的。如果你在 Debug 模式下链接了 Release 的 lib编译能过运行时会报LNK2038或直接堆损坏。这是最常见的翻车点之一。2.2 用 CMake 把编译库接进你的工程假设你解压到了D:\SDK\osgEarth-3.1-vs2019下面是一个最小可用的CMakeLists.txt用来验证这套库能不能跑通cmake_minimum_required(VERSION 3.15) project(OsgEarthSmokeTest LANGUAGES CXX) # 根据构建类型自动选择 Release 或 Debug 库目录 if(CMAKE_BUILD_TYPE STREQUAL Debug) set(OSG_LIB_DIR D:/SDK/osgEarth-3.1-vs2019/lib/debug) set(OSG_BIN_DIR D:/SDK/osgEarth-3.1-vs2019/bin/debug) else() set(OSG_LIB_DIR D:/SDK/osgEarth-3.1-vs2019/lib/release) set(OSG_BIN_DIR D:/SDK/osgEarth-3.1-vs2019/bin/release) endif() set(OSG_ROOT D:/SDK/osgEarth-3.1-vs2019) # 头文件目录OSG、OsgEarth、第三方依赖都要加 include_directories( ${OSG_ROOT}/include ${OSG_ROOT}/3rdparty/include ${OSG_ROOT}/3rdparty/include/gdal ) # 库目录 link_directories(${OSG_LIB_DIR} ${OSG_ROOT}/3rdparty/lib) add_executable(smoke_test main.cpp) # 链接核心库osg、osgDB、osgViewer、osgEarth、osgEarthUtil target_link_libraries(smoke_test osg osgDB osgViewer osgEarth osgEarthUtil )这段 CMake 的逻辑很直白先根据构建类型切换库路径再把头文件和库目录加进去最后链接五个核心库。参数上你需要注意三点第一OSG_ROOT换成你自己的解压路径路径里不要有中文和空格第二3rdparty/include必须加否则gdal.h找不到第三如果你用的是 Visual Studio 生成器而不是 NinjaCMAKE_BUILD_TYPE不生效需要用--config Debug或--config Release来指定。配套的main.cpp只做一件事加载一个.earth文件并打印是否成功。#include osgViewer/Viewer #include osgEarth/MapNode #include osgEarth/GeoData #include iostream int main(int argc, char** argv) { // 传入一个 .earth 文件路径作为参数 if (argc 2) { std::cerr Usage: smoke_test file.earth std::endl; return -1; } osg::ref_ptrosgViewer::Viewer viewer new osgViewer::Viewer(); osg::ref_ptrosg::Node node osgDB::readNodeFile(argv[1]); if (!node) { std::cerr Failed to load earth file: argv[1] std::endl; return -1; } // 尝试转换为 MapNode确认 OsgEarth 库真正被链接进来 osgEarth::MapNode* mapNode osgEarth::MapNode::findMapNode(node); if (mapNode) { std::cout MapNode loaded successfully. std::endl; } else { std::cout Node loaded but not a MapNode. std::endl; } viewer-setSceneData(node); return viewer-run(); }这段代码的关键在于osgEarth::MapNode::findMapNode它强制你链接osgEarth.lib如果库版本不匹配链接阶段就会报错不会拖到运行时才暴露。编译命令mkdir build cd build cmake .. -G Visual Studio 16 2019 -A x64 cmake --build . --config Release跑通之后你会看到一个窗口里面是加载的地球。如果窗口一闪而过或者报缺少 DLL说明bin目录没加到PATH里。2.3 运行时 DLL 的搜索路径怎么设才不翻车编译通过只是第一步运行时找不到 DLL 是另一个高频问题。Windows 下 DLL 搜索顺序是exe 所在目录 → 系统目录 → PATH 环境变量。最稳妥的做法是把编译库的bin目录加到系统 PATH或者直接把需要的 DLL 拷到 exe 旁边。我一般会在项目里加一个 CMake 的 post-build 步骤自动拷贝 DLLadd_custom_command(TARGET smoke_test POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_directory ${OSG_BIN_DIR} $TARGET_FILE_DIR:smoke_test COMMENT Copying OSG/OsgEarth runtime DLLs... )这样每次编译完exe 旁边就有完整的 DLL不依赖 PATH。注意copy_directory会把整个 bin 目录拷过去如果里面有几十个插件 DLL第一次编译会慢一点但省去了后面手动找 DLL 的麻烦。3. 在 VS2019 里手工配置 OsgEarth 工程包含目录、库目录与调试器环境3.1 不用 CMake 时VS2019 属性页该怎么填有些团队的项目是纯 VS 工程不经过 CMake。这时候你需要在项目属性里手工配置。右键项目 → 属性按下面这张表填配置项Release 值Debug 值C/C → 常规 → 附加包含目录D:\SDK\...\include;D:\SDK\...\3rdparty\include同上链接器 → 常规 → 附加库目录D:\SDK\...\lib\releaseD:\SDK\...\lib\debug链接器 → 输入 → 附加依赖项osg.lib;osgDB.lib;osgViewer.lib;osgEarth.lib;osgEarthUtil.libosgd.lib;osgDBd.lib;osgViewerd.lib;osgEarthd.lib;osgEarthUtild.lib调试 → 环境PATHD:\SDK\...\bin\release;%PATH%PATHD:\SDK\...\bin\debug;%PATH%注意 Debug 配置下附加依赖项里的库名要加d后缀。如果你不确定某个库有没有 Debug 版本去lib/debug目录下看一眼文件名。没有d后缀的库说明这个包只提供了 Release 版那你在 Debug 模式下也得链接 Release 版但这时候要确保 C 运行时库一致都用/MD或/MDd否则会出现LNK2038: mismatch detected for RuntimeLibrary。3.2 调试器环境变量让 F5 直接跑起来VS2019 的调试器环境变量设置是一个容易被忽略但极其省事的功能。在项目属性 → 调试 → 环境里填入PATHD:\SDK\osgEarth-3.1-vs2019\bin\debug;D:\SDK\osgEarth-3.1-vs2019\3rdparty\bin;%PATH%这样按 F5 调试时VS 会临时把这两个目录加到 PATH 最前面DLL 就能被找到。比每次手动拷 DLL 或者改系统环境变量优雅得多。注意 Debug 和 Release 配置要分别设置因为 DLL 目录不同。3.3 验证 Debug 和 Release 是否都能跑通配置完之后不要只测一个配置。按下面的顺序各跑一遍切换到 Debug 配置编译F5 运行确认窗口正常出现、地球能加载。切换到 Release 配置编译CtrlF5 运行确认同样正常。在 Debug 下打开一个.earth文件确认影像和地形都能显示。如果 Debug 能跑但 Release 崩溃大概率是某个第三方库只有 Release 版而你在 Debug 下链接了它运行时 CRT 不匹配。反过来如果 Release 能跑但 Debug 链接报错检查lib/debug目录下是不是缺了某个d后缀的库。4. 避坑与排查OsgEarth 编译库在 Win10 上最容易翻车的 5 个点4.1 现象编译报LNK2038 RuntimeLibrary mismatch原因你的工程用了/MDdDebug 多线程 DLL 运行时但链接的某个库是用/MDRelease 多线程 DLL 运行时编的。OsgEarth 的 Debug 库和 Release 库在 CRT 选择上是固定的混用就会报这个错。解决确认 Debug 配置下链接的是lib/debug目录里的库Release 配置下链接的是lib/release目录里的库。如果某个第三方库只有 Release 版那你的工程在 Debug 下也得用/MD在 C/C → 代码生成 → 运行时库里改成「多线程 DLL (/MD)」。4.2 现象程序启动时报「找不到 osgDB_osg.dll」或类似插件缺失原因bin目录没有加到 PATH或者plugins目录没有被正确识别。OsgEarth 加载.earth文件时需要osgDB插件来读取影像和地形格式插件 DLL 通常在bin/osgPlugins-3.6.5这样的子目录里。解决把bin目录加到 PATH同时确认OSG_LIBRARY_PATH环境变量指向插件目录。如果不想改系统环境变量在代码里加一行osgDB::Registry::instance()-getLibraryFilePathList().push_back( D:/SDK/osgEarth-3.1-vs2019/bin/osgPlugins-3.6.5);这行代码把插件搜索路径直接告诉 osgDB比依赖环境变量更可控。4.3 现象加载.earth文件后地球是黑的没有影像原因GDAL 数据路径没有配置或者 PROJ 的proj.db找不到。OsgEarth 依赖 GDAL 读取 GeoTIFF、JPEG 等影像格式依赖 PROJ 做坐标转换。这两个库都需要运行时数据文件。解决设置GDAL_DATA和PROJ_LIB环境变量指向编译库里的3rdparty/share/gdal和3rdparty/share/proj。在代码里也可以手动指定osgEarth::setGDALDataPath(D:/SDK/osgEarth-3.1-vs2019/3rdparty/share/gdal);如果还是黑的检查.earth文件里的影像路径是不是绝对路径相对路径的基准目录是当前工作目录不是.earth文件所在目录。4.4 现象Debug 下能编译但一运行就崩在osg::ref_ptr析构原因Debug 和 Release 的osg::ref_ptr内部引用计数类型可能不同混用会导致引用计数错乱。常见于你链接了 Release 的osg.lib但用了 Debug 的osgDBd.lib。解决统一。要么全 Debug要么全 Release。检查附加依赖项列表确保没有混入不同配置的库。VS2019 的属性页可以按配置分别设置利用好这一点。4.5 现象CMake 配置时找到的是系统里另一个版本的 OSG原因系统 PATH 里可能有另一个 OSG 安装CMake 的find_package(OpenSceneGraph)优先找到了它而不是你解压的编译库。解决在CMakeLists.txt里显式设置OSG_DIR和osgEarth_DIR或者在 CMake 命令里加-DOSG_DIRD:/SDK/.../lib/cmake/OpenSceneGraph。更彻底的做法是在find_package之前设置CMAKE_PREFIX_PATHset(CMAKE_PREFIX_PATH D:/SDK/osgEarth-3.1-vs2019 ${CMAKE_PREFIX_PATH})这样 CMake 会优先在你指定的目录里找。5. 进阶技巧用这个编译库做多版本共存与快速验证5.1 同一台机器上共存多个 OsgEarth 版本实际项目里你可能同时维护两个产品一个用 OsgEarth 3.1另一个用 3.2 或更高。如果都装到系统 PATH 里必然冲突。我的做法是每个版本解压到独立目录不碰系统环境变量全部通过 CMake 的CMAKE_PREFIX_PATH和运行时PATH来隔离。具体来说在项目的 CMake 里写# 通过缓存变量指定 OsgEarth 根目录方便切换 set(OSGEARTH_ROOT D:/SDK/osgEarth-3.1-vs2019 CACHE PATH OsgEarth SDK root) list(APPEND CMAKE_PREFIX_PATH ${OSGEARTH_ROOT})然后在 VS2019 的调试环境里PATH 只加当前项目对应的bin目录。这样两个项目可以同时打开各自用各自的版本互不干扰。5.2 用最小.earth文件做冒烟测试每次换编译库或者换机器不要拿复杂的项目去试先写一个最小.earth文件map nameminimal options profileglobal-geodetic/profile /options image nameworld drivergdal urlD:/data/world.tif/url /image elevation namesrtm drivergdal urlD:/data/srtm.tif/url /elevation /map这个文件只加载一张全球影像和一份高程能跑通说明 GDAL、PROJ、osgDB 插件、OsgEarth 核心库全部正常。跑不通就按第 4 章的排查顺序逐条查。我一般会把world.tif换成一个很小的、几百 KB 的测试影像加载快出问题也容易定位。5.3 验证 Debug 和 Release 产物的 ABI 兼容性如果你要把这个编译库交给团队里其他人用最好写一个简单的验证脚本让每个人拿到包之后先跑一遍。脚本内容就是编译第 2 章那个smoke_test分别在 Debug 和 Release 下运行输出MapNode loaded successfully就算通过。echo off set SDKD:\SDK\osgEarth-3.1-vs2019 set PATH%SDK%\bin\release;%SDK%\3rdparty\bin;%PATH% smoke_test.exe minimal.earth if %errorlevel% neq 0 ( echo Release smoke test FAILED exit /b 1 ) echo Release smoke test PASSED这个脚本看起来简单但能挡住 80% 的环境问题。团队里新人拿到编译库先跑脚本通过了再开始写业务代码省得后面把环境问题误判成代码 bug。5.4 一个我踩过的坑路径里的空格和中文最后说一个血泪经验。OsgEarth 的某些插件在读取文件路径时对空格和中文的处理并不一致。我曾经把编译库解压到D:\我的项目\osgEarth 3.1\这样的路径下结果 GDAL 能读到影像但 osgDB 的插件加载失败报了一个完全不相干的错误。排查了半天才发现是路径里的空格导致插件 DLL 的搜索路径被截断。从那以后我定了一个规矩所有 SDK、第三方库、测试数据的路径一律用纯英文、无空格、尽量短的目录名比如D:\SDK\osgEarth-3.1-vs2019。这个习惯帮我省了很多莫名其妙的调试时间。希望帮到你。本文还有配套的精品资源点击获取
