简介面向基于Visual Studio 2019构建64位OSG3.6.5与OSGEarth2.10项目的开发者这份预编译三方库直击第三方依赖缺失、编译配置繁琐的痛点。压缩包约137.76MB内含2000个文件以头文件、静态库、CMake配置、inc文件、C源文件、proto文件与DLL动态库为主要类型其中头文件为编译提供函数声明与接口定义静态库和动态库负责链接与运行时加载CMake配置帮助构建系统自动查找依赖时区数据文件则保证地理渲染时时间信息准确。目前已有619人学习下载。实际使用这一依赖包时无需再在网络上逐一下载和编译数十个第三方库所有库文件均针对VS2019 64位环境预编译目录结构划分清晰合理可直接引用或集成到现有工程显著缩短环境搭建时间。对刚接触OSG或希望减少配置成本的中高级C开发者尤为实用无论编译OSG还是OSGEarth都能直接复用减少重复配置。 坦白说在Windows上折腾OSG 3.6.5和OSGEarth的人十有八九不是被OSG本身难住的而是被一堆第三方库逼疯的。源码能下下来CMake一跑满屏红色的“某某库找不到”接下来就是无限循环的下载依赖、编译依赖、配置依赖。GDAL、GEOS、CURL、SQLite3、zlib、libpng、libjpeg、tiff任何一个版本和你当前的VS工具集不匹配最后都是白干一下午。我手上这套预编译好的3rdParty.zip就是围绕OSG 3.6.5 OSGEarth这套组合整理的解压后include/lib/bin三件套齐全专门用来终结“三方库从哪来、怎么配、为什么跑不起来”这三大问题。这篇不是单纯丢个下载地址就跑我会把这套3rdParty.zip从目录结构、环境配置、CMake接入、版本搭配一直延伸到真实开发里最常见的“判断点是否落在FeatureNode内”这个空间查询需求整条链路都过一遍。适合刚接触OSGEarth的图形和GIS开发者也适合那些已经在用、但每次换电脑都要重配一遍环境的同学。1. 为什么OSG/OSGEarth非要一份“预编译三方库”1.1 三方库的“三”到底指什么很多人第一次看到“3rdParty.zip”这个文件名以为里面只是OSG自带的几个辅助库实际拆开后才发现事情没那么简单。OSG本体其实核心库不算多它依赖的是下面的插件而插件几乎都挂在第三方库上。比如你导入一张jpg贴图osgDB是交给libjpeg处理的你导入一个GeoJSONOSGEarth是交给GDAL和GEOS处理的你加载一个在线瓦片服务又是通过CURL拉数据再经SQLite3缓存到本地。每一个第三方库都有自己的构建系统和一个数不清的编译选项。zlib还算友好用CMake几分钟就完事。GDAL在Windows上用CMake编译选项多到让人头大而且它自己还依赖GEOS、libtiff、libpng这些库编起来有严格的先后顺序。GEOS相对好一点但如果你拿到的是老版本nmake那套流程更是折磨。这些库单独编一个都不算难难的是它们要同时满足以下所有条件才算“可用”编译器版本一致VS2015、VS2017、VS2019之间不能随便混用架构一致x64和Win32不能混运行库方式一致/MD和/MT混了会直接LNK2038Debug和Release都有对应版本这四个条件一叠加情况就变成了就算你已经成功编好了另外17个库第18个库也会因为一个小配置不对把前面所有成果都拖下水。1.2 从源码手动编一遍要花多久我拿自己第一次在Windows上编这些依赖库的经历算笔时间账。zlib很快10分钟解决。libpng、libjpeg、libtiff这三个图像库每个20到30分钟前提是过程中不出问题。freetype需要先处理harfbuzz和brotli又是额外时间。curl建议用CMake编但要注意是否带SSL支持30分钟起步。sqlite3不需要编译直接拿源码也凑合用但为了统一管理还是得编。GEOS比较麻烦Windows上的配置步骤很多运气好一个小时运气不好一个下午。GDAL更是重头戏编译时间基本两小时起步过程中还要反复处理各种依赖查找失败。加起来一个白天就没了而且这是在每个库都顺利的前提下。更尴尬的是这种纯手工编译得到的库只能保证“能编译”不保证“能运行”。运行期DLL加载顺序、Debug和Release的切换、插件路径查找任何一环出问题还是要继续排查。所以从那以后我坚定认为OSG 3.6.5和OSGEarth这个组合就应该用预编译好的3rdParty.zip把时间和精力留给业务逻辑而不是浪费在编译依赖上。1.3 预编译包真正锁死的是一套稳定组合社区里能找到的三方库压缩包其实不少但版本往往对不上。有的是针对OSG 3.4时代的GDAL版本老旧编译OSGEarth时一堆接口报错有的是纯Release版Debug下没法用于调试还有的忘了带bin目录运行时各种DLL缺失。一份合格的预编译3rdParty.zip应该直接锁定一条可用组合链OSG 3.6.5 OSGEarth 2.10.x VS2017 x64工具集 Debug/Release双版本。这套组合是经过大量项目验证过的最稳定搭配之一GDAL、GEOS、CURL这些库的版本都适配过不会出现“头文件能找到链接也过了但运行时崩溃”的情况。2. 压缩包里的每个依赖库都不是白给你的2.1 依赖库清单与各自用途打开3rdParty.zip之后include、lib、bin三个目录里文件很多如果只是用CMake一股脑让它自己找你未必清楚每个库是干什么的。只有知道它们各自的价值出了问题才知道去哪查而不是瞎猜。依赖库谁需要它缺失时会怎样zliblibpng、libtiff、CURL、部分OSG插件图像插件编译失败解压纹理或网络数据异常libpng / libjpeg / libtiffosgDB图像插件无法读取常见图片格式纹理加载黑屏freetypeosgText文字渲染中文和复杂字体显示异常甚至编译失败CURLOSGEarth网络瓦片驱动WMTS、TMS、在线影像服务全部失效GDALOSGEarth地理数据读写无法读取shp、tif、img等栅格矢量数据GEOSOSGEarth空间几何计算点线面空间关系判断相关功能无法编译SQLite3OSGEarth MBTiles和缓存驱动离线瓦片数据库打不开protobufOSGEarth部分序列化驱动特定数据格式的驱动无法启用这里要特别提一下GEOS很多人不知道OSGEarth为什么需要它。OSGEarth里的FeatureNode、Feature、空间过滤器在底层大量依赖GEOS做几何拓扑计算比如“点是否落在多边形里”“线与面是否相交”“缓冲区分析”。如果你的3rdParty.zip里没有GEOS那么就算你把OSGEarth编过了到了写代码阶段要用空间查询一样会碰壁。2.2 include、lib、bin三个目录各管什么预处理好的压缩包结构上有一个非常标准的三段式include目录存放头文件lib目录存放静态库和导入库bin目录存放DLL动态库。这三个目录分别对应编译的三个阶段include编译器在预处理阶段来这里找头文件比如gdal_priv.h、geos_c.hlib链接器在链接阶段来这里找导入库比如gdal.lib、geos_c.libbin操作系统在程序运行阶段来这里加载DLL比如gdal.dll、geos_c.dll很多人只做对前两步第三步漏了于是程序编译链接全部通过双击exe却报“找不到gdal.dll”或者0xc000007b。原因就是运行时没有把3rdParty的bin目录告诉操作系统。Windows查找DLL有一套固定顺序应用程序所在目录、系统目录、PATH环境变量目录。你不把bin加进PATH系统就只能去别的地方找找到版本不对的DLL后又会出现更诡异的问题。2.3 Debug和Release为什么给了两份只要仔细看lib和bin目录就会发现里面有一堆带“d”后缀的文件。zlib.lib和zlibd.lib就是这么一组对照。带“d”的是Debug版不带的是Release版。二者不能混用也不能为了图方便用Release库去编译Debug程序。混用之后最常见的症状是编译期报LNK2038: mismatch detected for RuntimeLibrary或者编译期不报错、运行期在某个内存操作函数里崩溃。这属于比较难排查的问题因为报错点往往不在你自己的代码里而在某个库的内部。好在预编译包本身把两套都准备好了CMake会根据当前的配置类型自动选择你不需要手动指定文件名。唯一要做的是别去改库文件名别把zlibd.lib手动改成zlib.lib否则就是你自己给自己挖坑。3. 把3rdParty.zip变成自己的开发环境从解压到编译通过3.1 解压目录规划拿到压缩包的第一件事不是双击解压而是先想好放哪。我的习惯是解压到D:\3rdParty这样简单、无空格、无中文的路径。Visual Studio和CMake在纯英文路径下最稳定中文路径虽然现在大多数情况也能用但一旦出现某个第三方库内部用旧式字符编码处理路径报错信息会非常难懂。解压之后确认目录结构大致如下D:\3rdParty ├── include ├── lib └── bin还有一种常见布局是D:\3rdParty\include、D:\3rdParty\lib、D:\3rdParty\bin但有些压缩包会在中间多套一层VC15或者x64目录比如D:\3rdParty\VC15_x64\include。这也没问题只要记住你最终指向的路径配置时别搞混就行。3.2 环境变量配置步骤下一步是配置环境变量。需要配置的变量主要有两个作用完全不同PATH追加D:\3rdParty\bin解决运行期DLL搜索问题ACTUAL_3RDPARTY_DIR指向D:\3rdParty让OSG和OSGEarth的CMake脚本能自动定位三方库以Windows 10为例在“系统属性”里打开“环境变量”先编辑PATH在末尾追加D:\3rdParty\bin注意前面要用分号隔开。然后新建一个系统变量变量名ACTUAL_3RDPARTY_DIR变量值D:\3rdParty。需要提醒的是改完环境变量后已经打开的IDE和终端不会立刻生效要全部关掉重新打开。3.3 CMake配置与编译目标选择如果你用CMake GUI编译OSG源码直接设置ACTUAL_3RDPARTY_DIR为D:\3rdParty然后点Configure。正常情况下GDAL_INCLUDE_DIR、GEOS_LIBRARY、CURL_INCLUDE_DIR这些变量会自动填充到正确位置。如果个别变量没有自动识别再手动指定到对应目录这种情况通常是因为压缩包内的目录结构和脚本预期的不完全一致。命令行编译的话以VS2017 x64为例配置命令大致是这样cmake -G Visual Studio 15 2017 Win64 ^ -DACTUAL_3RDPARTY_DIRD:/3rdParty ^ -DCMAKE_PREFIX_PATHD:/3rdParty ^ -DCMAKE_BUILD_TYPERelease ^ ../OSG_SourceOSGEarth的源码用同样的方式配置一遍只是源码目录换成OSGEarth的。配置完成后生成解决方案先单独编译ALL_BUILD项目。这里有个经验别一开始就全量生成所有示例程序编译目标里有很多example工程全都编一遍非常耗时而且还可能出现示例代码与当前依赖库版本不完全兼容的小问题干扰你判断主项目是否正常。第一轮建议只编核心库本身也就是把ALL_BUILD里的OSG核心库和OSGEarth主库编出来确认没问题后再去编示例。编译时间取决于机器通常OSG核心加OSGEarth在20到40分钟之间属于正常。编译结束后建议执行一下INSTALL把产物安装到统一目录比如C:\OSG。然后把C:\OSG\bin也加进PATH这样任意终端里都能直接用osgversion和osgearth_version验证环境。4. OSG 3.6.5与OSGEarth版本搭配及排错对照4.1 版本绑定逻辑预编译3rdParty.zip之所以要强调“OSG 3.6.5和OSGEarth”这一组合是因为这两者之间版本匹配是硬性的。OSGEarth 2.10.x系列是按照OSG 3.6系列的接口做的适配用OSG 3.6.5配OSGEarth 2.10.x编译和运行都很稳定。但如果拿OSG 3.6.5去配OSGEarth 3.x就会出现一堆接口签名不匹配的情况因为OSGEarth 3.x要求OSG至少3.6.6以上而且用到了更现代的CMake特性。反过来也一样如果你的OSGEarth是老的2.8版本配上OSG 3.6.5不一定马上爆错但运行期可能出现一些莫名其妙的崩溃。所以看到“3rdParty.zip”时先确认里面GDAL、GEOS等库的版本处于哪个时代不要拿一个为OSG 3.6.5准备的预编译包去编译OSGEarth 3.2那只会浪费你的时间。4.2 编译期错误速查表预编译包整体流程跑下来最常见的编译期错误也就那么几类这里直接整理成表错误信息真正原因解决办法LNK2038: RuntimeLibrary mismatchDebug和Release库混用检查CMake的CMAKE_BUILD_TYPE保证Debug编Debug、Release编ReleaseLNK1104: cannot open file gdal.libCMake没有找到GDAL导入库手动检查GDAL_LIBRARY变量是否正确指向D:\3rdParty\lib下对应文件C1083: Cannot open include file geos_c.hinclude路径没配置确认GEOS_INCLUDE_DIR已设置且指向包含geos_c.h的目录无法定位程序输入点 sqlite3_wal_checkpoint_v2 于 sqlite3.dll运行时加载了错误版本的SQLite3检查PATH顺序确保D:\3rdParty\bin排在系统目录之前或者删除旧版DLL这里要着重说明LNK2038这个问题。我见过很多人在Debug模式下编译链接器却报了RuntimeLibrary mismatch一查发现CMake缓存里CMAKE_BUILD_TYPE还停留在Release。因为之前配置过一次Release后来切到Debug没有清空构建目录。遇到这种问题干净做法是删除build目录重新配置而不是在现有解决方案里硬切配置类型。4.3 运行期插件加载排查逻辑OSG运行时要加载插件插件形态是osgPlugins-3.6.5目录下的DLL。这个目录的搜索逻辑和普通DLL不一样OSG会按以下顺序查找插件可执行文件当前目录下的osgPlugins-3.6.5环境变量OSG_LIBRARY_PATH指向的目录OSG安装目录下的bin目录如果你用的是解压版没有特意设置OSG_LIBRARY_PATH那么提示“Unable to load plugin”时先检查exe旁边有没有插件目录。另外插件DLL本身又依赖3rdParty的DLL所以就算插件位置对了3rdParty的bin目录不在PATH里一样会失败。排查运行期问题有个简单有效的步骤先命令行执行osgversion确认OSG核心能起来再执行osgearth_version确认OSGEarth能起来接着用osgviewer打开一张带地理信息的tif看能不能正常显示。哪一步报错就定位到对应的依赖基本就能锁死问题范围。这一套流程下来多数环境问题都能在10分钟内定位。5. 环境跑通后的进阶查询如何判断点是否落在FeatureNode内5.1 FeatureNode里到底存了什么等编译环境完全跑通接下来就进入真正写业务逻辑的阶段。在OSGEarth里FeatureNode是一个很常用的节点类型它把一个Feature对象和渲染状态封装在一起。Feature里包含了两层关键内容一是几何数据本身面状要素就是多边形顶点数组线状要素就是一条路径点数组二是空间参考系SRS也就是这些顶点坐标是基于WGS84经纬度还是某个投影坐标系。很多人在判断“点是否在FeatureNode内”时直接用经纬度坐标和Feature的坐标比较得到错误结果。原因就是忽略了SRS这层概念。Feature的几何坐标可能不是经纬度而是经过投影后的平面坐标比如墨卡托投影或者UTM分区坐标。你必须把查询点坐标和Feature几何坐标统一到同一个空间参考系下空间关系判断才有意义。5.2 坐标转换与几何判断两步走完整的判断流程分两步第一步把查询点转换到Feature的SRS第二步做点在多边形内的判断。查询点通常来自鼠标拾取或GPS设备常见格式是WGS84经纬度。射线法算法适合处理“单环多边形”代码也很短bool IsPointInPolygon(const std::vectorosg::Vec3d ring, double x, double y) { bool inside false; size_t n ring.size(); for (size_t i 0, j n - 1; i n; j i) { double xi ring[i].x(), yi ring[i].y(); double xj ring[j].x(), yj ring[j].y(); if (((yi y) ! (yj y)) (x (xj - xi) * (y - yi) / (yj - yi) xi)) { inside !inside; } } return inside; }配合坐标转换在OSGEarth中调用的方式大致是osg::ref_ptrosgEarth::SpatialReference wgs84 osgEarth::SpatialReference::get(wgs84); osgEarth::GeoPoint queryPt(wgs84, 116.391, 39.905); osgEarth::GeoPoint localPt; queryPt.transform(feature-getSRS(), localPt); const osgEarth::Symbology::Geometry* geom feature-getGeometry(); if (geom geom-getType() osgEarth::Symbology::Geometry::POLYGON) { const osgEarth::Symbology::Polygon* poly dynamic_castconst osgEarth::Symbology::Polygon*(geom); if (poly) { bool hit IsPointInPolygon(poly-getVertices(), localPt.x(), localPt.y()); // hit 就是最终结果 } }上面代码以单个Polygon为例实际工程里Feature的几何可能是MultiGeometry也就是一个Feature同时包含多个多边形需要遍历子几何逐个判断。如果你的数据里有带“洞”的多边形比如一块地块中央有一个湖泊区域这种内环结构用简单射线法会误判需要区分外环和内环做排除。面对这种复杂场景我建议直接用GEOS它提供了完整的空间关系函数。3rdParty.zip里已经带好了GEOS连头文件和库都不用额外找这也是预编译包带来的一个隐藏便利。5.3 实战中容易踩的翻车点第一不要直接拿经纬度算几何。经纬度单位是度不经过投影直接参与距离判断会出大问题尤其在纬度比较高的地方一度的经度距离和一度的纬度距离差得非常多。判断点是否在多边形内时如果两个SRS不一致哪怕多边形离点只有一百米算法也会得出“不在内部”的错误结论。第二注意FeatureNode的坐标可能经过局部偏移。在某些飞行仿真或小范围场景里为了保证浮点精度会用一个本地坐标系把几何平移过。这种情况下Feature的SRS可能是一个自定义的本地参考系点查询前要搞清楚这个参考系的基准点在哪。第三性能问题。一个FeatureNode如果承载了成千上万个Feature对象每帧都遍历查询显然不现实。这时候要考虑用瓦片、空间索引或者把几何体拆分成更小的FeatureNode来管理。判断点是否在FeatureNode内看上去是一个很基础的问题但一旦数据量上来简单的遍历就会变成性能瓶颈。5.4 这个能力在业务里能做什么“点是否落在FeatureNode内”的实际应用非常广。最典型的就是地块点击查询鼠标点在地图上程序判断点落在哪个行政区、哪个地块里然后通过Feature拿到属性字段比如地块编号、面积、权属人信息接着弹窗显示。还有车辆围栏功能车辆实时GPS坐标传到服务器后台判断是否已经驶出某个FeatureNode围成的区域一旦越界触发告警。再比如农作物补贴核查、林业资源调查这类GIS业务里很多数据都以FeatureNode的形式组织空间关系判断是绕不开的底层能力。一个和版本配套有关的最终建议依赖库这套东西最怕的就是动其中一个。我现在的做法是把OSG源码、OSGEarth源码和这份3rdParty.zip固定成一套组合打包归档换机器或者带新人时直接整套拉下来半天内就能把完整开发环境搭起来再也不会出现“我用的是GDAL 3.4你的是2.4为什么你的代码在我这不跑”这种扯皮问题。最后等环境稳定后建议自己做一个最小可运行的OSGEarth测试程序加载一个本地shp把FeatureNode遍历、点选判断这整套代码写进去。这样以后新项目直接把这一段拿过来当模板。三方库的坑是有限的但业务代码会一直长早点把底层环境从脑子里卸载掉才能把精力放在真正有产出的事情上。本文还有配套的精品资源点击获取
OSG/OSGEarth预编译三方库配置指南：从环境搭建到空间查询
简介面向基于Visual Studio 2019构建64位OSG3.6.5与OSGEarth2.10项目的开发者这份预编译三方库直击第三方依赖缺失、编译配置繁琐的痛点。压缩包约137.76MB内含2000个文件以头文件、静态库、CMake配置、inc文件、C源文件、proto文件与DLL动态库为主要类型其中头文件为编译提供函数声明与接口定义静态库和动态库负责链接与运行时加载CMake配置帮助构建系统自动查找依赖时区数据文件则保证地理渲染时时间信息准确。目前已有619人学习下载。实际使用这一依赖包时无需再在网络上逐一下载和编译数十个第三方库所有库文件均针对VS2019 64位环境预编译目录结构划分清晰合理可直接引用或集成到现有工程显著缩短环境搭建时间。对刚接触OSG或希望减少配置成本的中高级C开发者尤为实用无论编译OSG还是OSGEarth都能直接复用减少重复配置。 坦白说在Windows上折腾OSG 3.6.5和OSGEarth的人十有八九不是被OSG本身难住的而是被一堆第三方库逼疯的。源码能下下来CMake一跑满屏红色的“某某库找不到”接下来就是无限循环的下载依赖、编译依赖、配置依赖。GDAL、GEOS、CURL、SQLite3、zlib、libpng、libjpeg、tiff任何一个版本和你当前的VS工具集不匹配最后都是白干一下午。我手上这套预编译好的3rdParty.zip就是围绕OSG 3.6.5 OSGEarth这套组合整理的解压后include/lib/bin三件套齐全专门用来终结“三方库从哪来、怎么配、为什么跑不起来”这三大问题。这篇不是单纯丢个下载地址就跑我会把这套3rdParty.zip从目录结构、环境配置、CMake接入、版本搭配一直延伸到真实开发里最常见的“判断点是否落在FeatureNode内”这个空间查询需求整条链路都过一遍。适合刚接触OSGEarth的图形和GIS开发者也适合那些已经在用、但每次换电脑都要重配一遍环境的同学。1. 为什么OSG/OSGEarth非要一份“预编译三方库”1.1 三方库的“三”到底指什么很多人第一次看到“3rdParty.zip”这个文件名以为里面只是OSG自带的几个辅助库实际拆开后才发现事情没那么简单。OSG本体其实核心库不算多它依赖的是下面的插件而插件几乎都挂在第三方库上。比如你导入一张jpg贴图osgDB是交给libjpeg处理的你导入一个GeoJSONOSGEarth是交给GDAL和GEOS处理的你加载一个在线瓦片服务又是通过CURL拉数据再经SQLite3缓存到本地。每一个第三方库都有自己的构建系统和一个数不清的编译选项。zlib还算友好用CMake几分钟就完事。GDAL在Windows上用CMake编译选项多到让人头大而且它自己还依赖GEOS、libtiff、libpng这些库编起来有严格的先后顺序。GEOS相对好一点但如果你拿到的是老版本nmake那套流程更是折磨。这些库单独编一个都不算难难的是它们要同时满足以下所有条件才算“可用”编译器版本一致VS2015、VS2017、VS2019之间不能随便混用架构一致x64和Win32不能混运行库方式一致/MD和/MT混了会直接LNK2038Debug和Release都有对应版本这四个条件一叠加情况就变成了就算你已经成功编好了另外17个库第18个库也会因为一个小配置不对把前面所有成果都拖下水。1.2 从源码手动编一遍要花多久我拿自己第一次在Windows上编这些依赖库的经历算笔时间账。zlib很快10分钟解决。libpng、libjpeg、libtiff这三个图像库每个20到30分钟前提是过程中不出问题。freetype需要先处理harfbuzz和brotli又是额外时间。curl建议用CMake编但要注意是否带SSL支持30分钟起步。sqlite3不需要编译直接拿源码也凑合用但为了统一管理还是得编。GEOS比较麻烦Windows上的配置步骤很多运气好一个小时运气不好一个下午。GDAL更是重头戏编译时间基本两小时起步过程中还要反复处理各种依赖查找失败。加起来一个白天就没了而且这是在每个库都顺利的前提下。更尴尬的是这种纯手工编译得到的库只能保证“能编译”不保证“能运行”。运行期DLL加载顺序、Debug和Release的切换、插件路径查找任何一环出问题还是要继续排查。所以从那以后我坚定认为OSG 3.6.5和OSGEarth这个组合就应该用预编译好的3rdParty.zip把时间和精力留给业务逻辑而不是浪费在编译依赖上。1.3 预编译包真正锁死的是一套稳定组合社区里能找到的三方库压缩包其实不少但版本往往对不上。有的是针对OSG 3.4时代的GDAL版本老旧编译OSGEarth时一堆接口报错有的是纯Release版Debug下没法用于调试还有的忘了带bin目录运行时各种DLL缺失。一份合格的预编译3rdParty.zip应该直接锁定一条可用组合链OSG 3.6.5 OSGEarth 2.10.x VS2017 x64工具集 Debug/Release双版本。这套组合是经过大量项目验证过的最稳定搭配之一GDAL、GEOS、CURL这些库的版本都适配过不会出现“头文件能找到链接也过了但运行时崩溃”的情况。2. 压缩包里的每个依赖库都不是白给你的2.1 依赖库清单与各自用途打开3rdParty.zip之后include、lib、bin三个目录里文件很多如果只是用CMake一股脑让它自己找你未必清楚每个库是干什么的。只有知道它们各自的价值出了问题才知道去哪查而不是瞎猜。依赖库谁需要它缺失时会怎样zliblibpng、libtiff、CURL、部分OSG插件图像插件编译失败解压纹理或网络数据异常libpng / libjpeg / libtiffosgDB图像插件无法读取常见图片格式纹理加载黑屏freetypeosgText文字渲染中文和复杂字体显示异常甚至编译失败CURLOSGEarth网络瓦片驱动WMTS、TMS、在线影像服务全部失效GDALOSGEarth地理数据读写无法读取shp、tif、img等栅格矢量数据GEOSOSGEarth空间几何计算点线面空间关系判断相关功能无法编译SQLite3OSGEarth MBTiles和缓存驱动离线瓦片数据库打不开protobufOSGEarth部分序列化驱动特定数据格式的驱动无法启用这里要特别提一下GEOS很多人不知道OSGEarth为什么需要它。OSGEarth里的FeatureNode、Feature、空间过滤器在底层大量依赖GEOS做几何拓扑计算比如“点是否落在多边形里”“线与面是否相交”“缓冲区分析”。如果你的3rdParty.zip里没有GEOS那么就算你把OSGEarth编过了到了写代码阶段要用空间查询一样会碰壁。2.2 include、lib、bin三个目录各管什么预处理好的压缩包结构上有一个非常标准的三段式include目录存放头文件lib目录存放静态库和导入库bin目录存放DLL动态库。这三个目录分别对应编译的三个阶段include编译器在预处理阶段来这里找头文件比如gdal_priv.h、geos_c.hlib链接器在链接阶段来这里找导入库比如gdal.lib、geos_c.libbin操作系统在程序运行阶段来这里加载DLL比如gdal.dll、geos_c.dll很多人只做对前两步第三步漏了于是程序编译链接全部通过双击exe却报“找不到gdal.dll”或者0xc000007b。原因就是运行时没有把3rdParty的bin目录告诉操作系统。Windows查找DLL有一套固定顺序应用程序所在目录、系统目录、PATH环境变量目录。你不把bin加进PATH系统就只能去别的地方找找到版本不对的DLL后又会出现更诡异的问题。2.3 Debug和Release为什么给了两份只要仔细看lib和bin目录就会发现里面有一堆带“d”后缀的文件。zlib.lib和zlibd.lib就是这么一组对照。带“d”的是Debug版不带的是Release版。二者不能混用也不能为了图方便用Release库去编译Debug程序。混用之后最常见的症状是编译期报LNK2038: mismatch detected for RuntimeLibrary或者编译期不报错、运行期在某个内存操作函数里崩溃。这属于比较难排查的问题因为报错点往往不在你自己的代码里而在某个库的内部。好在预编译包本身把两套都准备好了CMake会根据当前的配置类型自动选择你不需要手动指定文件名。唯一要做的是别去改库文件名别把zlibd.lib手动改成zlib.lib否则就是你自己给自己挖坑。3. 把3rdParty.zip变成自己的开发环境从解压到编译通过3.1 解压目录规划拿到压缩包的第一件事不是双击解压而是先想好放哪。我的习惯是解压到D:\3rdParty这样简单、无空格、无中文的路径。Visual Studio和CMake在纯英文路径下最稳定中文路径虽然现在大多数情况也能用但一旦出现某个第三方库内部用旧式字符编码处理路径报错信息会非常难懂。解压之后确认目录结构大致如下D:\3rdParty ├── include ├── lib └── bin还有一种常见布局是D:\3rdParty\include、D:\3rdParty\lib、D:\3rdParty\bin但有些压缩包会在中间多套一层VC15或者x64目录比如D:\3rdParty\VC15_x64\include。这也没问题只要记住你最终指向的路径配置时别搞混就行。3.2 环境变量配置步骤下一步是配置环境变量。需要配置的变量主要有两个作用完全不同PATH追加D:\3rdParty\bin解决运行期DLL搜索问题ACTUAL_3RDPARTY_DIR指向D:\3rdParty让OSG和OSGEarth的CMake脚本能自动定位三方库以Windows 10为例在“系统属性”里打开“环境变量”先编辑PATH在末尾追加D:\3rdParty\bin注意前面要用分号隔开。然后新建一个系统变量变量名ACTUAL_3RDPARTY_DIR变量值D:\3rdParty。需要提醒的是改完环境变量后已经打开的IDE和终端不会立刻生效要全部关掉重新打开。3.3 CMake配置与编译目标选择如果你用CMake GUI编译OSG源码直接设置ACTUAL_3RDPARTY_DIR为D:\3rdParty然后点Configure。正常情况下GDAL_INCLUDE_DIR、GEOS_LIBRARY、CURL_INCLUDE_DIR这些变量会自动填充到正确位置。如果个别变量没有自动识别再手动指定到对应目录这种情况通常是因为压缩包内的目录结构和脚本预期的不完全一致。命令行编译的话以VS2017 x64为例配置命令大致是这样cmake -G Visual Studio 15 2017 Win64 ^ -DACTUAL_3RDPARTY_DIRD:/3rdParty ^ -DCMAKE_PREFIX_PATHD:/3rdParty ^ -DCMAKE_BUILD_TYPERelease ^ ../OSG_SourceOSGEarth的源码用同样的方式配置一遍只是源码目录换成OSGEarth的。配置完成后生成解决方案先单独编译ALL_BUILD项目。这里有个经验别一开始就全量生成所有示例程序编译目标里有很多example工程全都编一遍非常耗时而且还可能出现示例代码与当前依赖库版本不完全兼容的小问题干扰你判断主项目是否正常。第一轮建议只编核心库本身也就是把ALL_BUILD里的OSG核心库和OSGEarth主库编出来确认没问题后再去编示例。编译时间取决于机器通常OSG核心加OSGEarth在20到40分钟之间属于正常。编译结束后建议执行一下INSTALL把产物安装到统一目录比如C:\OSG。然后把C:\OSG\bin也加进PATH这样任意终端里都能直接用osgversion和osgearth_version验证环境。4. OSG 3.6.5与OSGEarth版本搭配及排错对照4.1 版本绑定逻辑预编译3rdParty.zip之所以要强调“OSG 3.6.5和OSGEarth”这一组合是因为这两者之间版本匹配是硬性的。OSGEarth 2.10.x系列是按照OSG 3.6系列的接口做的适配用OSG 3.6.5配OSGEarth 2.10.x编译和运行都很稳定。但如果拿OSG 3.6.5去配OSGEarth 3.x就会出现一堆接口签名不匹配的情况因为OSGEarth 3.x要求OSG至少3.6.6以上而且用到了更现代的CMake特性。反过来也一样如果你的OSGEarth是老的2.8版本配上OSG 3.6.5不一定马上爆错但运行期可能出现一些莫名其妙的崩溃。所以看到“3rdParty.zip”时先确认里面GDAL、GEOS等库的版本处于哪个时代不要拿一个为OSG 3.6.5准备的预编译包去编译OSGEarth 3.2那只会浪费你的时间。4.2 编译期错误速查表预编译包整体流程跑下来最常见的编译期错误也就那么几类这里直接整理成表错误信息真正原因解决办法LNK2038: RuntimeLibrary mismatchDebug和Release库混用检查CMake的CMAKE_BUILD_TYPE保证Debug编Debug、Release编ReleaseLNK1104: cannot open file gdal.libCMake没有找到GDAL导入库手动检查GDAL_LIBRARY变量是否正确指向D:\3rdParty\lib下对应文件C1083: Cannot open include file geos_c.hinclude路径没配置确认GEOS_INCLUDE_DIR已设置且指向包含geos_c.h的目录无法定位程序输入点 sqlite3_wal_checkpoint_v2 于 sqlite3.dll运行时加载了错误版本的SQLite3检查PATH顺序确保D:\3rdParty\bin排在系统目录之前或者删除旧版DLL这里要着重说明LNK2038这个问题。我见过很多人在Debug模式下编译链接器却报了RuntimeLibrary mismatch一查发现CMake缓存里CMAKE_BUILD_TYPE还停留在Release。因为之前配置过一次Release后来切到Debug没有清空构建目录。遇到这种问题干净做法是删除build目录重新配置而不是在现有解决方案里硬切配置类型。4.3 运行期插件加载排查逻辑OSG运行时要加载插件插件形态是osgPlugins-3.6.5目录下的DLL。这个目录的搜索逻辑和普通DLL不一样OSG会按以下顺序查找插件可执行文件当前目录下的osgPlugins-3.6.5环境变量OSG_LIBRARY_PATH指向的目录OSG安装目录下的bin目录如果你用的是解压版没有特意设置OSG_LIBRARY_PATH那么提示“Unable to load plugin”时先检查exe旁边有没有插件目录。另外插件DLL本身又依赖3rdParty的DLL所以就算插件位置对了3rdParty的bin目录不在PATH里一样会失败。排查运行期问题有个简单有效的步骤先命令行执行osgversion确认OSG核心能起来再执行osgearth_version确认OSGEarth能起来接着用osgviewer打开一张带地理信息的tif看能不能正常显示。哪一步报错就定位到对应的依赖基本就能锁死问题范围。这一套流程下来多数环境问题都能在10分钟内定位。5. 环境跑通后的进阶查询如何判断点是否落在FeatureNode内5.1 FeatureNode里到底存了什么等编译环境完全跑通接下来就进入真正写业务逻辑的阶段。在OSGEarth里FeatureNode是一个很常用的节点类型它把一个Feature对象和渲染状态封装在一起。Feature里包含了两层关键内容一是几何数据本身面状要素就是多边形顶点数组线状要素就是一条路径点数组二是空间参考系SRS也就是这些顶点坐标是基于WGS84经纬度还是某个投影坐标系。很多人在判断“点是否在FeatureNode内”时直接用经纬度坐标和Feature的坐标比较得到错误结果。原因就是忽略了SRS这层概念。Feature的几何坐标可能不是经纬度而是经过投影后的平面坐标比如墨卡托投影或者UTM分区坐标。你必须把查询点坐标和Feature几何坐标统一到同一个空间参考系下空间关系判断才有意义。5.2 坐标转换与几何判断两步走完整的判断流程分两步第一步把查询点转换到Feature的SRS第二步做点在多边形内的判断。查询点通常来自鼠标拾取或GPS设备常见格式是WGS84经纬度。射线法算法适合处理“单环多边形”代码也很短bool IsPointInPolygon(const std::vectorosg::Vec3d ring, double x, double y) { bool inside false; size_t n ring.size(); for (size_t i 0, j n - 1; i n; j i) { double xi ring[i].x(), yi ring[i].y(); double xj ring[j].x(), yj ring[j].y(); if (((yi y) ! (yj y)) (x (xj - xi) * (y - yi) / (yj - yi) xi)) { inside !inside; } } return inside; }配合坐标转换在OSGEarth中调用的方式大致是osg::ref_ptrosgEarth::SpatialReference wgs84 osgEarth::SpatialReference::get(wgs84); osgEarth::GeoPoint queryPt(wgs84, 116.391, 39.905); osgEarth::GeoPoint localPt; queryPt.transform(feature-getSRS(), localPt); const osgEarth::Symbology::Geometry* geom feature-getGeometry(); if (geom geom-getType() osgEarth::Symbology::Geometry::POLYGON) { const osgEarth::Symbology::Polygon* poly dynamic_castconst osgEarth::Symbology::Polygon*(geom); if (poly) { bool hit IsPointInPolygon(poly-getVertices(), localPt.x(), localPt.y()); // hit 就是最终结果 } }上面代码以单个Polygon为例实际工程里Feature的几何可能是MultiGeometry也就是一个Feature同时包含多个多边形需要遍历子几何逐个判断。如果你的数据里有带“洞”的多边形比如一块地块中央有一个湖泊区域这种内环结构用简单射线法会误判需要区分外环和内环做排除。面对这种复杂场景我建议直接用GEOS它提供了完整的空间关系函数。3rdParty.zip里已经带好了GEOS连头文件和库都不用额外找这也是预编译包带来的一个隐藏便利。5.3 实战中容易踩的翻车点第一不要直接拿经纬度算几何。经纬度单位是度不经过投影直接参与距离判断会出大问题尤其在纬度比较高的地方一度的经度距离和一度的纬度距离差得非常多。判断点是否在多边形内时如果两个SRS不一致哪怕多边形离点只有一百米算法也会得出“不在内部”的错误结论。第二注意FeatureNode的坐标可能经过局部偏移。在某些飞行仿真或小范围场景里为了保证浮点精度会用一个本地坐标系把几何平移过。这种情况下Feature的SRS可能是一个自定义的本地参考系点查询前要搞清楚这个参考系的基准点在哪。第三性能问题。一个FeatureNode如果承载了成千上万个Feature对象每帧都遍历查询显然不现实。这时候要考虑用瓦片、空间索引或者把几何体拆分成更小的FeatureNode来管理。判断点是否在FeatureNode内看上去是一个很基础的问题但一旦数据量上来简单的遍历就会变成性能瓶颈。5.4 这个能力在业务里能做什么“点是否落在FeatureNode内”的实际应用非常广。最典型的就是地块点击查询鼠标点在地图上程序判断点落在哪个行政区、哪个地块里然后通过Feature拿到属性字段比如地块编号、面积、权属人信息接着弹窗显示。还有车辆围栏功能车辆实时GPS坐标传到服务器后台判断是否已经驶出某个FeatureNode围成的区域一旦越界触发告警。再比如农作物补贴核查、林业资源调查这类GIS业务里很多数据都以FeatureNode的形式组织空间关系判断是绕不开的底层能力。一个和版本配套有关的最终建议依赖库这套东西最怕的就是动其中一个。我现在的做法是把OSG源码、OSGEarth源码和这份3rdParty.zip固定成一套组合打包归档换机器或者带新人时直接整套拉下来半天内就能把完整开发环境搭起来再也不会出现“我用的是GDAL 3.4你的是2.4为什么你的代码在我这不跑”这种扯皮问题。最后等环境稳定后建议自己做一个最小可运行的OSGEarth测试程序加载一个本地shp把FeatureNode遍历、点选判断这整套代码写进去。这样以后新项目直接把这一段拿过来当模板。三方库的坑是有限的但业务代码会一直长早点把底层环境从脑子里卸载掉才能把精力放在真正有产出的事情上。本文还有配套的精品资源点击获取
