从事三维GIS开发的朋友肯定对osgEarth不陌生。这个开源渲染引擎基于OpenSceneGraph打造厉害的地方在于它把地形、影像、矢量数据全部揉进一个XML格式的earth文件里你只需要写几行配置就能拉起一个带真实地形起伏的三维场景。我自己第一次接触它的时候被那种“写配置文件就能出图”的爽感震住了——对比之前用纯OpenSceneGraph手动建地形、贴纹理、加图元的痛苦经历osgEarth相当于把你从泥潭里拽了出来。这篇文章就围绕一个实战需求展开用osgearth配置earth文件同时加载高程数据、影像数据和SHP矢量数据并提供一个可直接复用的完整工程示例。我假设你已经有基本的C工程能力对OpenSceneGraph有粗浅了解就行。如果你连osgEarth是什么都不清楚那正好我会从环境搭建、数据准备、earth文件语法到代码实现逐层展开争取让新手照着做也能跑起来。核心目标是你拿到我这份配置和代码改改数据路径就能看到自己的地形、影像、SHP正确叠加在三维场景里。1. 项目方案设计与数据组织思路1.1 为什么用earth文件而非纯代码驱动很多刚接触osgEarth的人会习惯性地在C代码里逐条调用API来添加图层比如这样osgEarth::Map* map new osgEarth::Map(); osgEarth::Drivers::GDALOptions elevateOpt; elevateOpt.url() elev.tif; map-addElevationLayer(new osgEarth::ElevationLayer(elevateOpt));这种写法不是不行但维护成本极高。你每改一次数据源、每调一次渲染参数都要重新编译整个工程这谁顶得住earth文件的好处在于它是osgEarth的场景描述语言用XML语法把数据源、缓存策略、图层顺序、渲染参数全部外部化。你写好一个earth文件后续换数据、调参数直接改文本文件就行连编译都不用。而且分享给同事、部署到服务器只需要拷贝earth文件和对应数据即可。从我个人的工程经验来说用earth文件还有一个隐蔽的好处它天然就是项目文档。三个月后你回头看这个项目打开earth文件一看数据源在哪、坐标系是什么、高程怎么处理的、矢量用的什么样式一目了然。你写几十行注释都未必有这么清楚。1.2 方案整体架构我们这个项目要达成三层数据在同一三维场景中叠加整个架构可以拆解为四个部分数据层准备高程GeoTIFF、影像GeoTIFF、SHP矢量三个数据文件。配置层编写earth文件声明数据源、坐标参考系CRS、缓存目录、LOD策略。代码层用osgEarth的osgViewer API加载earth文件配置相机漫游器。调试层通过日志输出、截图比对等方式验证数据是否对齐、是否出现空洞。这个分层的好处是每一层都可以独立替换。你后面想换卫星影像只替换数据文件、改一行url不用动代码想调整场景初始视点直接改代码里的相机位置参数也不影响earth文件。1.3 坐标系和投影问题——最容易栽跟头的地方搞GIS的数据处理最崩溃的事情就是坐标对不上。影像和高程明明看起来是同一块地方加载进去却一个在天上一个在地下偏差几十公里甚至几百公里。这个问题的根源在于高程GeoTIFF、影像GeoTIFF和SHP三个数据的坐标系可能都不一样。比如高程数据用的是WGS84经纬度浮点型影像数据是Web墨卡托投影EPSG:3857整数型SHP是西安80高斯克吕格投影这三者放在同一个场景里如果没有统一坐标系那结果必然是灾难。osgEarth的做法是在earth文件的map节点中声明一个全局坐标系再用每个图层自己的profile或者数据自带的投影信息来做动态重投影。如果你在earth文件里没有显式指定全局坐标系osgEarth会默认使用EPSG:4326WGS84经纬度。注意默认的EPSG:4326虽然在大多数情况下没有问题但如果你影像数据是Web墨卡托高程数据是经纬度那么影像在场景边缘会出现拉伸畸变看起来就像被强行糊在地球上一样。这种情况建议把全局坐标系设为EPSG:3857。我在实际项目中遇到过某客户提供的SHP数据是地方坐标系没有明确的EPSG代号这种情况下你需要先用QGIS或者ArcGIS把SHP转成WGS84否则osgEarth按WGS84去解释这种情况的SHP坐标位置绝对是错的。2. 环境准备与数据整理2.1 osgEarth编译环境搭建要点先讲环境因为这一步卡住后面全部是空的。osgEarth的编译依赖OpenSceneGraphOSG而OSG又依赖一堆第三方库。在Windows上的常见组合是VS2019/2022我用的VS2019后面没踩什么坑CMake 3.16OpenSceneGraph 3.6.5osgEarth 2.10.2如果你想用较新的osgEarth 3.x建议直接看官方GitHub仓库的README那边有更细的构建说明。我这边以2.10.x为例因为目前很多公司内部项目都还停留在这个版本稳定、坑少、教程多。在Ubuntu/Debian系系统上如果只是开发调试我推荐直接用apt安装预编译包sudo apt-get install openscenegraph libopenscenegraph-dev sudo apt-get install libosgearth-dev osgearth预编译包的好处是你不用自己去编译GDAL、GEOS、curl那一堆依赖库省掉很多精力。如果你想自己编译你至少得先装好GDAL读写GeoTIFF、SHP的底层库GEOS几何拓扑计算Curl网络数据源支持SQLite3地形/影像缓存还有个小坑osgEarth对OpenSceneGraph的版本比较挑剔。比如2.10.2版本它要求OSG版本不能太高3.6.5是最稳妥的选择。如果你直接拉OSG最新的3.6.x开发版有可能在编译osgEarth时报一堆接口不兼容的错误。2.2 高程数据准备高程数据是这个场景的地形骨架没有它场景就是平的加载SHP也没意义。我们常用的高程数据格式有这么几种格式特点适用场景GeoTIFF带地理坐标信息的TIFF单波段浮点/整型通用性最强推荐DTED军事标准格式分层级航天项目、军事仿真HGTSRTM原始高程格式小范围测试、免费数据来源ASCIIGrid文本格式科研数据大文件读取慢我建议统一转成GeoTIFF。用GDAL命令行工具转格式很方便gdal_translate -of GTiff input.asc output_elev.tif高程数据的核心参数是位深bit depth和NoData值。位深决定存储精度一般用UInt16就够了地形高程值最大到几千上万米16位无符号整形最大能表示65535够用。如果你需要厘米级的精细地形再用Float32。NoData值一定要处理好。每个GeoTIFF都可能带NoData标记比如海洋区域的-32767。如果NoData不处理osgEarth加载时会把这些区域当正常高程处理在场景里产生突兀的尖刺或深坑。用GDAL命令可以快速处理gdal_translate -a_nodata -32767 input.tif output_nodata.tif2.3 影像数据准备影像数据用于给地形贴纹理通常是RGB三通道的GeoTIFF或者JPEG2000。一定要确保它的地理范围和高程数据对得上。这里我强调一个容易被忽视的点影像分辨率不是越高越好。你有一张0.3米分辨率的村域无人机影像直接丢给osgEarth加载速度会非常感人。因为osgEarth渲染时会动态请求多个层级的瓦片影像过大且没有建金字塔的话每个瓦片请求都要读取原始大文件——这在数据量上去后非常容易卡成PPT。我建议在项目中使用GDAL的gdaladdo命令建立影像金字塔gdaladdo -r average input_imagery.tif 2 4 8 16 32这条命令会生成input_imagery.tif.ovr文件osgEarth读取影像时可以直接跳转到合适的金字塔层级性能提升非常明显。另外影像数据的波段顺序也要检查。GeoTIFF常见的是RGB三波段排列但有些源数据是BGR直接加载会导致影像颜色发蓝发红。用QGIS打开看一眼如果颜色不对用GDAL重新排列波段即可。2.4 SHP数据准备与属性表检查SHPShapefile是ESRI设计的矢量数据格式一个完整的SHP文件通常包含.shp几何数据、.dbf属性表、.shx索引文件三个必要文件。拷贝数据时这三个必须同时拷贝缺一个都无法加载。拿到一个SHP文件第一件事是打开它的属性表看看字段名和数据内容。因为在earth文件里配置SHP样式时你需要根据具体字段来确定文字标注、颜色分级等。比如有的SHP是土地利用类型字段里有类型代码有的是道路线字段里可能有道路等级。这些信息决定了你怎么设计显示样式。SHP的种类也要分清楚点状SHP比如乡镇点位、监控点位。标注、图标显示。线状SHP比如道路、河流、管线。设置线宽、颜色。面状SHP比如行政区、土地利用、建筑轮廓。设置填充色、边界线样式。如果你手里的SHP坐标范围明显不对比如一个本应该在杭州的数据却出现在非洲那大概率是坐标系没定义或者定义错了。用QGIS加载时看右下角坐标显示如果坐标值非常大比如六位数、七位数多半是投影坐标系如果是负值到正值的小范围纬度经度比如118.0-120.0, 29.0-31.0那就是经纬度。跨坐标系的数据务必先统一再倒入osgEarth。3. earth文件配置深度拆解3.1 earth文件的基本骨架earth文件的本质是XML文档根节点通常是map也可以加options节点配置全局参数。先看一个最简骨架把结构先立起来map nameMyMap typegeocentric version2 options cache typefilesystem path./cache / /options elevation drivergdal url./data/elev.tif/url /elevation image drivergdal url./data/imagery.tif/url /image model driverfeature_geom url./data/regions.shp/url features nameregions geometry polygon fill color#FFAA00 / stroke color#FF0000 line-width2 / /polygon /geometry /features /model /map这个骨架里map节点有个type属性可选geocentric全球地心坐标系模拟地球或projected平面投影模拟局部平面。做全球场景选geocentric做一个城市或园区级别的精细场景projected反而更直观也更快因为不用担心地球曲率带来的视觉拉伸。我这次项目选的是geocentric因为用到的高程数据范围较小但我想演示完整的全球场景叠加方式。3.2 影像图层配置的进阶参数影像图层不只是给一个url那么简单。你可以对影像做透明度、颜色校正、LOD策略控制。在实际项目中我经常把同一区域的多期影像叠加在一起用透明度过渡来实现“历史影像对比”功能。配置方式是在image节点里加opacity属性image drivergdal opacity0.7 url./data/historical_imagery.tif/url /imageopacity范围是0.0~1.00为全透明1为完全不透明。如果你有几张影像想让最新的影像在最上面旧影像作为底图就需要调整图层的priority。注意osgEarth渲染图层时是严格按照节点顺序自上而下执行的。下面的图层先绘制上面的图层后绘制。如果上面的影像不透明底下的自然被盖住。我建议把底图影像放在第一个最底部然后把矢量标注类内容放在最上面。3.3 高程图层配置的注意事项高程的数据源和影像数据源类似使用gdal驱动就能读取GeoTIFF。在高程图层里有两个参数比较关键vertical-scale竖直比例默认1.0。如果你加载的高程数据是真实地形比如山区高差几百米vertical-scale保持默认即可。但如果你加载的等高线生成的DEM高差比较柔和想突出地形起伏感可以设置vertical-scale为2.0甚至5.0。我演示项目里用的是真实高程保持1.0。height-offset高程偏移量单位通常与数据的垂直单位一致。如果你当前数据的高程基准面与场景不匹配可以用这个参数做整体抬升或下沉。不过这个参数用得少容易把人绕晕建议谨慎使用。高程图层对性能的影响最大。如果高程数据分辨率高但机器性能一般建议在earth文件里限制地形细节级别比如elevation drivergdal url./data/elev.tif/url min_level2/min_level max_level15/max_level /elevation注意高程的最小层级如果设得太大远端地形会很模糊设得太小加载数据量大近处地形边缘会撕裂。我建议min_level设为0或者1max_level控制在15左右这样既能保证远端地形平滑又不会把机器的显存和内存耗尽。3.4 SHP矢量图层的配置核心SHP矢量图层通过model节点加载核心驱动是feature_geom它把矢量数据转换为场景中的几何体来渲染。在SHP样式配置上osgEarth提供了非常灵活的样式语言。以下是我常用的几种配置场景面状数据比如行政区边界填充并描边model driverfeature_geom url./data/county.shp/url features namecounty geometry polygon fill color#66AADD opacity0.5 / stroke color#FFFFFF line-width2 / /polygon /geometry /features /model关键是polygon节点里的fill子节点它设置填充颜色、透明度stroke设置边框线的颜色和宽度。opacity0.5是半透明效果可以透过行政区域看到下面的影像和高程。线状数据比如道路model driverfeature_geom url./data/road.shp/url features nameroads geometry line stroke color#FFD700 line-width3 / /line /geometry /features /model线状数据用line节点支持的样式有颜色、线宽还可以配置虚线效果。比如stroke propertiesstroke-dasharray: 5 3 /可以画虚线。点状数据比如地标model driverfeature_geom url./data/landmark.shp/url features namelandmark geometry point symbol codeH size20 fill#FF0000 / /point /geometry /features /model点状数据可以用symbol定义点的形状和颜色code可以是字体图标编码。SHP数据的显示图层顺序也很重要。如果你想在三维场景中让道路压在行政区域上面就把道路的model节点放在行政区域的model节点之后。osgEarth渲染模型图层时后面的节点会覆盖在前面的节点上面。4. 完整工程代码与运行调试4.1 完整earth文件示例先给出完整的earth文件我在注释里写清楚了每个节点的作用map nameosgEarth_Demo typegeocentric version2 options !-- 使用缓存避免每次加载重复读取原始数据 -- cache typefilesystem path./cache / log filenameosgearth.log / !-- 全局坐标系统一到WGS84经纬度 -- profile srsEPSG:4326 / /options !-- 第一个图层底图影像放在最底层 -- image drivergdal priority100 url./data/world_imagery.tif/url /image !-- 第二个图层高程数据 -- elevation drivergdal url./data/dem_elevation.tif/url /elevation !-- 第三个图层行政面SHP -- model driverfeature_geom url./data/gadm36_CHN_1.shp/url features nameprovinces geometry polygon fill color#00FF00 opacity0.3 / stroke color#FFFFFF line-width2 / /polygon /geometry /features /model !-- 第四个图层道路线SHP -- model driverfeature_geom url./data/roads.shp/url features nameroads geometry line stroke color#FFD700 line-width3 / /line /geometry /features /model /map这里我特意把底图影像放在最前面的图层位置这样后续的透明SHP填充可以盖在它上面。priority属性在图层叠加逻辑里用来仲裁平级数据源的顺序数值大的优先级高会显示在更上层。这个和XML文档顺序有一些细微的用法区别如果你对图层顺序严格要求建议两层都设置priority并用文档顺序双重确认。需要注意我这里的SHP数据格式是面类型的行政边界如果你用的是点或者线要根据数据实际类型调整geometry节点。4.2 C代码加载earth文件环境配置好、earth文件写好现在写C代码来加载它。代码的核心逻辑比较简单创建一个LoadsDataCallback读取earth文件然后把它传递给一个osgViewer::Viewer设置一个漫游器来支持鼠标键盘控制视角。#include osgViewer/Viewer #include osgEarth/MapNode #include osgEarth/Viewpoint #include osgEarthUtil/Controls #include osgGA/OrbitManipulator int main(int argc, char** argv) { if (argc 2) { std::cout Usage: osgEarthDemo earth_file std::endl; return -1; } // 加载earth文件 osg::ref_ptrosgEarth::MapNode mapNode osgEarth::MapNode::load(argv[1]); if (!mapNode.valid()) { std::cerr Failed to load earth file: argv[1] std::endl; return -1; } // 创建场景根节点加入MapNode osg::ref_ptrosg::Group root new osg::Group(); root-addChild(mapNode.get()); // 创建Viewer osgViewer::Viewer viewer; viewer.setSceneData(root.get()); // 设置漫游器鼠标左键旋转右键缩放中键平移 osg::ref_ptrosgGA::OrbitManipulator manipulator new osgGA::OrbitManipulator(); viewer.setCameraManipulator(manipulator.get()); // 设置初始视角经纬度高度朝向 osgEarth::Viewpoint viewpoint; viewpoint.focalPoint() osgEarth::GeoPoint(mapNode-getMapSRS(), 120.0, 30.0, 1000.0); viewpoint.heading() 0.0; viewpoint.pitch() -89.0; // 接近俯视 viewer.getCameraManipulator()-setViewpoint(viewpoint); // 初始化并运行 viewer.realize(); return viewer.run(); }这段代码里有几个关键细节需要注意。MapNode::load(argv[1])是osgEarth封装好的函数内部解析earth文件并创建地图节点。如果你的earth文件引用的数据路径不对这里会加载失败返回空指针程序直接退出。osgEarth::Viewpoint设置初始视角时它的三个参数分别是经度、纬度、高度。它的坐标系由mapNode-getMapSRS()决定也就是你在earth文件里配置的全局坐标系。如果你earth文件的profile是EPSG:3857那这里传经纬度会偏得离谱。建议保持全局坐标系为EPSG:4326这样视角设置符合直觉。还有一个细节viewer.run()进入主循环后会一直运行直到窗口关闭。如果你需要在自己的框架里嵌入osgEarth渲染就不能用run()而是手动调用frame()函数循环渲染。4.3 使用osgEarth自带工具快速验证如果你的工程还没有搭好C编译环境但又想快速验证earth文件和数据是否匹配osgEarth提供了一个自带的可执行程序osgearth_viewer可以直接加载earth文件并显示三维场景。在Ubuntu下安装osgearth包之后执行osgearth_viewer mymap.earthWindows下如果你是自己编译的osgEarth在bin目录下同样能找到osgearth_viewer.exe。这个工具在调试阶段特别好用。你写earth文件时不用每次修改都重新编译自己的程序直接启动它加载earth文件看效果。如果SHP没显示、影像偏了都是earth文件配置问题如果数据都正常那再回到自己的工程里跑问题就出在代码侧。5. 踩坑实录常见问题与排查方法5.1 场景黑屏或白屏啥都不显示这是最让人抓狂的问题。数据路径没问题、earth文件语法看起来没问题但一启动就是黑屏白屏。我的排查顺序是这样的看控制台输出有没有报错信息。osgEarth在加载图层失败时会打印红色错误日志比如[osgEarth] FAILED to open image layer.检查earth文件里的相对路径。注意相对路径是相对于哪个目录——如果你是在VS里运行程序工作目录默认是$(ProjectDir)和earth文件所在目录不一定是同一个。最简单的办法是把路径全部改成绝对路径来排除问题。检查数据文件本身能不能正常打开。用QGIS打开tif和shp如果QGIS都打不开那osgEarth也够呛。还有一次我遇到一个奇怪的现象数据文件都在但就是白屏。后来发现是tif的波段数不对影像文件带了透明度波段RGBA四波段而osgEarth的gdal驱动在读取这种文件时要额外处理透明度如果驱动没正确识别alpha波段就会显示异常。5.2 数据加载了但位置偏移几十公里如果看到场景里有东西但位置明显在空中或地底下大概率是坐标系没有统一。最常见的情况是高程数据和影像数据的坐标系不一致。比如高程是WGS84经纬度影像却是Web墨卡托。osgEarth虽然会自动重投影但如果你全局坐标系设置不明确重投影就可能出偏差。我的建议是在earth文件的profile节点里强制指定全局坐标系profile srsEPSG:4326 /另外如果你的SHP数据是投影坐标系比如EPSG:32650除了在earth文件里设置全局坐标系还要确保SHP数据自身是带投影定义的。有时候你用别人给的SHP里面没有.prj文件这会导致osgEarth无法正确解释坐标。遇到这种情况用QGIS手动指定投影后再另存为带.prj的版本。5.3 加载速度极慢拖动视角卡成PPT三维场景卡顿是性能优化的大坑我总结三个实用的优化方向第一启用缓存。earth文件中配置文件系统缓存cache typefilesystem path./cache /osgEarth会把处理过的瓦片存在这个目录里第一次遍历需要时间之后加载明显加快。第二控制图层细节层级上限。在影像和高程图层上设置max_level比如15。超过这个级别osgEarth不再请求更高分辨率的瓦片。对于叠加大范围低分辨率的应用场景这个参数非常有效。第三减少SHP要素数量。如果SHP有几万个面直接加载会让渲染线程崩溃。用QGIS做一次简化Simplify或者按条件筛选把要素量降到几千个以内。5.4 影像有缝隙或者条带在地形起伏较大的地方影像贴图偶尔会出现明显的接缝或条纹。这通常是因为影像的覆盖范围和高程数据覆盖范围不完全一致经常发生在数据边界附近。osgEarth在边界处会尝试采样相邻瓦片但如果没有相邻瓦片就留白。解决方式是在earth文件中设置影像图层的fallthrough为false默认就是false并给影像范围外设置一个全局背景色image drivergdal url./data/imagery.tif/url fallthroughfalse/fallthrough /image options background color#000000 / /options另外如果你的影像数据覆盖范围比高程数据小建议先用GDAL把影像范围伸张到和高程范围一致背景用黑色填充加载后就不会出现缝隙了。5.5 SHP要素在场景中不显示或显示很小还有一个我踩过好几次的坑SHP加载后要素要么直接不显示要么只有一个超小的点。这个问题的根源在于SHP的坐标单位与场景坐标系不匹配。如果SHP是经纬度坐标系但你在earth文件里把它当作平面坐标来渲染它就会缩到场景里的某个角落看起来根本不在预期位置。遇到这种情况我的做法是用QGIS打开SHP文件查看图层属性里的坐标参考系CRS。如果是投影坐标系先转成WGS84经纬度QGIS菜单图层 → 另存为 → 设置CRS为EPSG:4326。另存后的结果替换原数据文件重新加载earth文件测试。5.6 调试技巧开启日志输出osgEarth内置的日志输出非常强大你可以在earth文件的options节点中设置options log filenameosgearth.log / /options运行之后同目录下会生成osgearth.log文件。里面记录了各图层的初始化过程、瓦片请求情况、每个图层的状态。排查问题时重点看其中有没有failed、warning、no data等关键词。我记得有一次SHP一直不显示最后看日志发现是feature_geom驱动在处理某个特定要素时出错导致整层被跳过。这种情况用日志定位比人工排查快十倍。6. 性能优化建议与扩展思路6.1 earth文件配置层面的优化技巧除前面提到的缓存和LOD限制之外还有几个参数值得留意options节点里设置lightingfalse/lighting如果你不需要地表光照效果可以关掉灯光这样能明显减少GPU负载。tile_size节点默认是256如果显存充足可以考虑设置为512能减少绘制调用次数。concurrency节点设置多线程并行加载瓦片默认是1多核机器可以设为CPU核心数。6.2 动态切换图层——扩展应用场景earth配置文件不变的情况下你也可以通过代码动态地开关图层。比如你想做不同年代影像切换// 获取图层 osgEarth::ImageLayer* layer mapNode-getMap()-getLayerByNameosgEarth::ImageLayer(historical); layer-setVisible(true);但需要注意必须在earth文件中给图层设置唯一名称image drivergdal namehistorical url./data/old_imagery.tif/url /image这个功能在做历史影像对比、灾前灾后对比时很实用。6.3 扩展至网络数据源如果你不想总是准备本地数据还可以把数据源改为WMS、TMS等在线服务image driverwms urlhttp://your-wms-server.com/wms/url layersyour_layer/layers formatpng/format /image这样就不依赖本地大文件而且可以实时获取最新数据。不过要注意网络带宽和跨域等问题。6.4 从单机到集群的扩展如果追求更高级的场景分发可以考虑osgEarth的TileServer功能它可以把你的earth数据服务化让多个客户端同时连接共享同一份数据。这样可以实现在Web浏览器或者移动端上查看同一场景而不必各自拷贝数据。7. 写在最后一些真心建议我把这个项目的完整配置和代码分享出来以后很多人私信问我“为什么我这里跑不起来”“哪里设置错了”。坦白讲90%的问题出在数据本身而不是代码。数据质量决定了最终效果的上限。你把一个只有几百米高程差的低分辨率DEM和一个几GB的8K影像叠在一起渲染效果一定极其不协调——地形和影像的纹理无法对齐视觉体验很差。所以花时间去找高质量、坐标系统一的数据比纠结earth文件里某个参数设置是否有意义得多。还有建议就是初学者一定要善用osgearth_viewer这个调试工具。我自己写earth文件时几乎每改一次配置都会用它检查一遍效果。这样在项目早期就能发现坐标、图层顺序等问题比把整个工程编译出来再调试要高效得多。最后说一下代码架构。如果你想在自己的业务系统里长期使用osgEarth不要把所有东西都写在一个main函数里。把earth文件的加载、场景节点构建、相机控制参数管理分别封装成独立的模块方便以后做功能扩展。比如我自己的项目里就封装了SceneManager类负责加载earth文件、切换图层、管理视点、监听鼠标事件后续加新的功能模块就很顺手。希望这篇实战笔记能帮到你。如果你在配置过程中遇到了别的问题欢迎在评论区交流我看到了会尽量回复。