做Cesium开发这几年凡是涉及地形的项目几乎都要先在高程数据这个问题上绕几圈。很多刚入坑的同事第一反应是“new一个Viewer地形不就出来了”确实默认的Cesium Ion世界里有一份全球地形但关键是这份地形精度够不够、单位是什么、能不能固化到离线环境、采样出来的高度到底是不是真实海拔。不把这些底层逻辑弄清楚后面做淹没分析、填挖方计算、可视域分析结果一定会让你怀疑人生。这篇文章把我自己在项目里反复使用的Cesium高程数据方案整理了一遍覆盖数据源选型、地形加载配置、高程采样、几种常见业务玩法以及排查地形相关Bug的经验适合Web GIS开发者、数字孪生实施人员和Cesium入门者参考。内容里没有绕弯子都是可以直接落地的东西。1. 高程数据选型数据不对后面全白干1.1 先搞清楚Cesium里到底吃哪种“高程数据”在Cesium里说“高程数据”多数时候指的就是地形数据英文文档里叫Terrain。它本质上是DEMDigital Elevation Model经过切片处理后生成的瓦片数据。原始DEM常见来源有SRTM、ASTER、ALOS AW3D30、机载LiDAR等格式通常是GeoTIFF或者DTED但这些原始文件不能直接给Cesium用必须先处理成Cesium能识别的地形瓦片格式。目前Cesium最推荐的地形格式是Quantized-Mesh它把地形表面表示成一棵四叉树瓦片结构每个瓦片内是一个经过量化的三角网格。这种格式的好处是WebGL渲染效率高、LOD调度成熟还支持水遮罩和顶点法线。另一个老格式是Heightmap原理是每个瓦片存一张高度图灰度值但这种格式现在已经逐步边缘化除非你维护的是老系统否则新项目不建议再用。我在实际项目里遇到过有人在问“为什么我加载了DEM却不显示地形”多半是直接把GeoTIFF丢给了前端。无论数据源头是什么Cesium前端的TerrainProvider只能消费两种东西一种是自带解析器的在线地形瓦片服务另一种是Cesium Ion托管的terrain数据集。所以数据源选型本质上是在回答“原始DEM怎么变成Cesium吃得到的terrain瓦片”。1.2 常见地形数据源对比与选型建议先给一张表把我用过的几种数据源按精度和适用场景列清楚数据源 / 格式典型精度使用方式适用场景备注Cesium Ion World Terrain约30米局部更高createWorldTerrainAsync联网项目快速起步自带水遮罩、法线SRTM30米 / 90米转Quantized-Mesh后自建服务大范围地形底图免费全球覆盖ASTER GDEM30米转Quantized-Mesh局部细节补充城市区域有一定精度ALOS AW3D3030米转Quantized-Mesh亚洲区域项目精度较SRTM稳定机载LiDAR1米到5米按需切片电力巡检、水利项目数据量通常很大专业航线倾斜模型厘米级到分米级Cesium 3DTiles精细数字孪生一般不作为地形源如果项目允许联网我建议优先用Cesium Ion上的World Terrain省事、稳定而且免费额度对大多数原型项目够用。如果做政企内网项目离线环境十有八九需要自建地形服务这时候一般流程是准备好原始DEM GeoTIFF注意坐标系先统一到EPSG:4326高程单位统一到米使用Cesium Terrain Builder这类工具把它切片成Quantized-Mesh瓦片用Nginx或者其他静态文件服务器发布瓦片目录前端通过CesiumTerrainProvider.fromUrl加载。这样一套流程下来地形数据就完全掌握在自己手里了不用再依赖外网。1.3 高程基准问题椭球高和正高别混着用这是容易被忽略又最容易出大问题的地方。Cesium默认使用WGS84椭球高height是相对于WGS84椭球面的而很多测绘数据里的高程是海拔高也叫正高或水准高两者的基准差着一个大地水准面差距。在国内大部分区域这个差值一般在二三十米到四五十米之间不同位置不一样。我举个真实例子某次做水库淹没分析甲方给的水位数据是海拔高程地形DEM也是海拔高程看着都没问题。但我们加载到Cesium后发现水位把大片不该淹的区域淹了一查发现是中间某个环节把DEM的高程基准转错了——前端拿到的高度是椭球高和水位数据差了三十多米。排查了整整一个下午最后把基准统一后结果一下就正常了。所以在你把数据喂给Cesium之前务必确认所有高程数据使用的基准统一。如果在Cesium里只是做视觉展示那差异不一定看得出来但只要你把高度值用于计算比如淹没分析、填挖方、飞行漫游离地高度就必须把基准搞对。2. Cesium加载地形的正确姿势与细节2.1 基础配置TerrainProvider和setTerrain怎么用现在Cesium版本已经迭代得比较快建议直接用新版API。老写法是viewer.terrainProvider xxx新版更推荐用viewer.scene.setTerrain。下面给出最常用的两种加载方式。离线Quantized-Mesh地形const viewer new Cesium.Viewer(cesiumContainer, { animation: false, baseLayerPicker: false, geocoder: false, timeline: false, sceneMode: Cesium.SceneMode.SCENE3D }); const terrainProvider await Cesium.CesiumTerrainProvider.fromUrl( https://your-domain.com/terrain/{z}/{x}/{y}.terrain, { requestWaterMask: true, requestVertexNormals: true } ); viewer.scene.setTerrain(new Cesium.Terrain(terrainProvider));如果你用的是Cesium Ion在线地形Cesium.Ion.defaultAccessToken 你的Ion Token; const worldTerrain await Cesium.createWorldTerrainAsync({ requestWaterMask: true, requestVertexNormals: true }); viewer.scene.setTerrain(new Cesium.Terrain(worldTerrain));这里有个细节值得注意requestWaterMask和requestVertexNormals不是所有地形源都支持。如果你的自建地形瓦片里没有水遮罩和法线数据设置了也没用。好在Quantized-Mesh格式可以包含这些扩展切片的时候建议带上因为顶点法线对地形光影效果影响很大。2.2 地形显示效果夸张、光照和贴地很多人加载完地形后觉得“太平了”尤其是平原地带的项目。这时候可以用地形夸张来放大起伏感viewer.scene.globe.terrainExaggeration 2.5; viewer.scene.globe.terrainExaggerationRelativeHeight 0.0;第二个参数terrainExaggerationRelativeHeight表示相对哪个高度做夸张0表示相对海平面。如果你的项目区域海拔很高比如在云贵高原整体海拔两千米那么夸张后山体起伏会显得很别扭。这时候建议把RelativeHeight设置为区域平均海拔让低海拔区域基本不变高海拔的山体被拉高。如果想让地形看起来有光影立体感打开光照viewer.scene.globe.enableLighting true; viewer.scene.globe.dynamicAtmosphereLighting true;配合requestVertexNormals: true地形表面就会有明暗变化而不再是灰白一片。做数字孪生项目时这个效果对“真实感”的提升非常明显尤其是动态太阳光照随着时间变化的时候。还有一个高频选项是depthTestAgainstTerrainviewer.scene.globe.depthTestAgainstTerrain true;这个默认是false。如果设为true模型和地形之间会做深度测试模型压到地下就会被地形遮挡住。做贴地测量或楼层选中时这个选项会影响拾取准确性所以它不是无脑开的要根据业务判断。2.3 高程采样与高度查询sampleTerrain和sampleTerrainMostDetailed除了看地形效果很多时候我们需要在代码里动态获取某个经纬度对应的高度。比如无人机航线规划、车辆偏移校正、水位分析都要用高程采样接口。Cesium提供两个核心接口Cesium.sampleTerrain和Cesium.sampleTerrainMostDetailed。前者接受一个level参数指定从某个LOD级别采样后者会自动请求最高级别的细节精度更高但开销也更大。const positions [ Cesium.Cartographic.fromDegrees(116.391, 39.907), Cesium.Cartographic.fromDegrees(116.401, 39.917), Cesium.Cartographic.fromDegrees(121.473, 31.230) ]; // 在线地形请求最高精度 const updatedPositions await Cesium.sampleTerrainMostDetailed(worldTerrain, positions); updatedPositions.forEach((position) { console.log(Lon: ${Cesium.Math.toDegrees(position.longitude)}, Lat: ${Cesium.Math.toDegrees(position.latitude)}, Height: ${position.height}); });注意sampleTerrainMostDetailed只能用于在线地形数据集比如Ion的Terrain或CesiumTerrainProvider自带的URL。它对坐标数量比较敏感如果是几千上万个点的大范围采样建议不要在前端跑而是服务端定时批处理生成结果。我在某个河道项目里对一百多万个点做过采样纯前端直接卡死最后改成后端用C解析DEM文件批量计算几秒钟就出结果。如果一定要前端做很多点采样可以把点分批比如每批200个异步串行处理并且设置合理的Camera距离避免LRU缓存频繁淘汰否则采样请求会反复重新加载地形的上级瓦片性能会很差。3. 把高程数据变成业务价值几个高频场景拆解3.1 数字孪生项目里的“贴地”与“单体化”在数字孪生项目里3DTiles倾斜摄影、BIM模型和地形数据经常需要叠加显示。很多人会遇到一个现象模型加载出来了但它和地形之间要么“穿模”要么“浮空”。简单做法是对Entity设置heightReference: Cesium.HeightReference.CLAMP_TO_GROUND这样点、标注、广告牌会自动贴合地表。但3DTiles数据集本身比较复杂直接设置heightReference并不可靠。更常见的做法是在数据生产阶段就把模型底部校准到当地高程导出时可以带上地面原点高度这样3DTiles在Cesium里加载出来就是正好贴地的。如果项目里必须动态放置带模型节点的构件比如复杂glTF/GLB结构建议用Cesium.Model.fromGltfAsync加载后再遍历节点用model.modelMatrix配合采样高度做整体位移。这里牵扯到“模型节点”的层级关系操作时注意子节点坐标是相对父节点的直接改世界矩阵容易造成节点错位。“单体化”也是数字孪生里的热门词。所谓单体化简单说就是让倾斜摄影模型能按楼层、户室、道路单独选中。地形在这个场景里通常作为背景底图但它会影响点击拾取。如果depthTestAgainstTerrain开着射线可能先打在地形上导致建筑物根部选不中。我的经验是做单体化拾取时临时把depthTestAgainstTerrain设为false或者用scene.pickPosition这种支持地形深度判断的接口再把拾取结果和建筑轮廓数据做空间过滤。另外如果项目里要加载矢量切片MVT比如道路、河流、行政区边界这些矢量要素也可以配合地形贴地显示。MVT本身只是矢量数据不直接带高度但你可以把要素的坐标转成点序列逐个采样地形高度后生成贴地的GeoJSON或Polygon配合GroundPrimitive来渲染效果很不错。3.2 淹没分析、填挖方和可视域把DEM变成决策依据这几个功能是GIS项目的高频需求也是面试官喜欢问的地方。先说淹没分析。它的核心逻辑并不复杂找到一个水位高度把地形高度低于水位线的区域渲染成水面。难点在于怎么高效地判断“低于水位线的区域”。我的做法是先把分析区域的多边形按一定间距打网格比如间距50米每个格点采样地形高度然后用二分法不断逼近目标水位。每次试算统计格点中低于水位的数量占比直到满足淹没面积或水位停止变化。这样找出来的水位高度可以用来生成水面Polygonconst waterPolygon viewer.entities.add({ polygon: { hierarchy: analysisPolygon, height: waterHeight, material: Cesium.Color.BLUE.withAlpha(0.5), classificationType: Cesium.ClassificationType.TERRAIN } });注意水面不能用height: 0去贴地否则水面会被地形完全盖住根本看不出淹没效果。正确做法是用绝对高度做平面并开启classificationType: TERRAIN让水面只显示在地形表面以上。另外如果精度要求高比如水利工程验收级别上游到下游的水位不是平的而是有坡降的这时要引入水面线函数而不是用一个固定高程。3.3 填挖方计算的实践思路填挖方计算本质上是一个体积积分问题。设计标高确定后对场地按固定网格划分每个网格的中心点采一次原始地形高程然后用“设计标高 - 实测高程”乘上网格面积累加得到填方或挖方量。V填 Σ max(设计标高 - 实测高程, 0) × 网格面积 V挖 Σ max(实测高程 - 设计标高, 0) × 网格面积这个公式看着简单但我在项目里踩过一个大坑如果前端开了terrainExaggeration采样出来的高度是夸张后的高度不是真实高程。填挖方计算必须把地形夸张系数设为1或者直接用服务端原版DEM算否则最后算出来的土方量能差出一倍还多。另外网格间距的选择直接影响计算精度。间距越密越准确但采样次数会指数上升。我的经验是平整场地用10米到20米间距足够公园地形造型这类项目5米间距勉强够再密的话建议做剖分或TIN三角网计算效率远高于均匀网格。3.4 雷达扫描、热力图和动态光照让地形“活”起来这些功能虽然不直接“使用高程数据”但它们都以地形场景为承载。比如雷达扫描效果本质上是一个扇形区域随时间扫过地形扇形本身用Polygon实现但如果要精确显示雷达波被地形遮挡的阴影区就需要对地形做射线求交判断每个方位角上哪些区域被山体挡住。这个和可视域分析是同一个底层原理。热力图叠加在地形上时最稳妥的做法是把业务数据点投射到地形表面生成一个半透明的覆盖层。用GroundPrimitive加自定义Shader或者用Heatmap.js先画成图片再贴到一个矩形或Polygon上。要注意温度、污染等热力数据是按经纬度分布的不能简单地在2D平面投影后贴上去否则在山地地区会明显错位。动态光照和地形结合的效果很有感染力。打开enableLighting后配合Cesium的时钟设置太阳在不同时间的位置可以看到地形阴影随着“一天”变化。这个在方案汇报里特别加分。要注意的是动态光照对性能有一定影响如果场景里还有大范围倾斜摄影模型建议降低屏幕空间误差或者用瓦片层级控制否则帧率掉得很厉害。3.5 在地形上绘制矩形并测量面积和“cesium绘制矩形”这个热词相关的需求也很常见在地形上框选一块区域测量实际面积。难点在于地形表面不是平面直接用椭球面面积会偏小。我用的方法是先在地形上确定矩形的四个角点再用ellipsoidGeodesic计算相邻点间的大地线长度最后按四边形面积近似计算。如果区域很大最好把边界细分对每个小三角形做地形修正面积累加。画矩形的交互可以用ScreenSpaceEventHandler监听左键点击然后用viewer.entities.add创建一个带轮廓的地面矩形让它的classificationType为TERRAIN并设置相对于地表的偏移这样矩形会贴合地形起伏不会悬浮飘着。测量结果的展示可以加一个Label实时显示面积数值。4. 常见问题与排查技巧实录4.1 地形加载不出来、发白或者颜色不对这是遇到次数最多的一类问题我把典型场景和解决方法整理成了一张速查表现象可能原因排查与解决地形完全不显示地球是一片蓝色Ion Token未配置或过期检查Cesium.Ion.defaultAccessToken地形显示了但是发白、没有凹凸感地形瓦片没有顶点法线切片时开启VertexNormals加载时设requestVertexNormals: true自建地形服务加载后报CORS错误静态服务没有允许跨域Nginx增加Access-Control-Allow-Origin配置地形加载慢瓦片一直转圈服务端瓦片不存在或路径不对检查URL模板{z}/{x}/{y}.terrain是否正确海拔明显异常比如城市中心显示负几百米高程基准不一致检查DEM是椭球高还是正高统一基准有一种特别容易误判的情况Ion的地形服务在开发环境里能加载但打包上生产环境就挂了。原因是生产环境域名和你申请Ion Token时填写的域名不一致Ion会拒绝请求。解决办法是在Ion控制台重新生成Token并把你所有可能用到的域名都加进允许列表。4.2 3D地球滚动或缩放时出现“崩溃”怎么办“cesium 3d地球滚动出现崩溃”这个热词我猜很多开发者都搜过。这里说的崩溃通常不是浏览器整个崩掉而是出现白屏、黑屏、WebGL上下文丢失或者页面假死。最常见的原因有三个一是显存和内存被地形瓦片占满尤其是连续快速缩放时Cesium会疯狂加载各个层级的瓦片低配机器很容易扛不住二是某些显卡驱动对WebGL支持不稳定在连续重绘时触发Context Lost三是代码里有非法坐标比如纬度超出范围或者经纬度字段混用导致渲染阶段计算异常。我的排查步骤是打开浏览器的chrome://gpu确认WebGL状态和GPU进程是否正常把requestRenderMode打开避免一直重绘viewer.scene.requestRenderMode true; viewer.scene.maximumRenderTimeChange 1.0 / 30.0;限制地形缓存和误差viewer.scene.globe.tileCacheSize 100; viewer.scene.globe.maximumScreenSpaceError 2.0;检查代码里的所有经纬度输入尤其是后端接口返回的数据逐个打印出来看有没有NaN或非法值。如果问题只在低端设备上出现那大概率是资源占用过高。可以把maximumScreenSpaceError从默认的2调到4或6这样瓦片层级会浅一些渲染压力小很多。代价是拉近时地形会稍模糊但对大多数业务场景影响不大。4.3 Cesium高程相关的高频面试题与简答思路把“cesium 面试题”这个热词也一起融进来结合高程这个主题面试官最常问的点基本集中在这几个方向。面试题简答思路Cesium支持哪几种地形格式主流是Quantized-Mesh老版本支持HeightmapCesium Ion也接受GeoTIFF转地形Quantized-Mesh和普通3D网格有什么区别Quantized-Mesh针对海量地形做四叉树调度顶点坐标用16位量化压缩支持扩展水遮罩和法线sampleTerrain和sampleTerrainMostDetailed区别前者指定LOD级别后者自动请求最细级别精度更高但开销更大地形夸张会影响采样高度吗会影响采样返回的是夸张后的显示高度做计算时要关掉夸张或用原始DEM离线项目里怎么加载地形将DEM切片成Quantized-MeshNginx发布前端用CesiumTerrainProvider加载怎么避免倾斜摄影模型和地形穿模数据生产阶段校准底高加载后可整体平移模型必要时关闭深度测试地形在水面之下的部分怎么处理水生效果相关需求可使用水遮罩或SurfaceShader让地形和水面贴合这几个问题背后考察的其实不只是API记忆而是你有没有真正理解“高程数据从原始DEM到前端渲染”的完整链路。我在面试别人时喜欢让候选人解释一下terrainProvider和globe的关系能把这个讲清楚的基本都对Cesium的核心机制有概念。5. 关于Cesium高程数据使用我最后想说的几句实在话如果给新手一个最实用的建议那就是先别急着把地形效果做得花里胡哨先把“任意一个点采样出来的高度值”验证正确确认数据源和基准没问题再往上叠加功能。这个基础不稳后面所有分析都是空中楼阁。再分享一个小技巧调试的时候不要只靠人眼看地球可以用viewer.camera.positionCartographic打印相机当前经纬度和高度再手动飞到某个已知高程地物附近做对比。比如我知道某个城市广场的大地高是42米就把相机飞到那附近采样看是不是42米左右。误差超过两三米就说明数据源或基准有问题需要回到数据源头去查。高程数据的坑大多不在Cesium本身而在数据链路。只要记住“格式转对、基准统一、精度匹配、性能可控”这四句话绝大多数地形项目都能顺顺利利做完。希望这篇总结能帮你少走点弯路。