1. 为什么地形高程这件事值得单独拎出来讲但凡做过三维地理可视化的朋友大概率都经历过这样一个场景项目里要在山顶上放一个标注或者在河谷里画一条路线结果标注飘在半空中路线一头扎进地底下。用户一看就炸了说你这做的什么玩意儿一点都不准。问题出在哪十有八九就是高程没取对。Cesium 作为三维地球引擎里的老大哥它本身提供了相当完整的地形支持但“支持地形”和“你能拿到准确的高程值”之间隔着好几道坎。地形数据要加载、瓦片要请求、异步要处理、不同坐标参考系要转换任何一个环节没注意到拿到的数字就是错的。更麻烦的是Cesium 的 API 在不同版本之间有过调整网上搜到的代码片段可能来自五六年前直接抄过来跑不通。这篇内容就是把我自己在实际项目里反复折腾出来的经验整理一下围绕“在 Cesium 里怎么拿到某个经纬度坐标点的地形高程”这个核心问题把几种主流方法、各自的适用场景、踩过的坑和排查思路都讲清楚。不管你是刚接触 Cesium 的新手还是已经用过一段时间但总觉得高程取不准的老手应该都能从里面找到有用的东西。先明确一下问题边界我们说的是已知一个经纬度坐标比如从 GPS 设备读到的、从数据库里查到的、用户在地图上点击得到的要获取该位置对应的地形表面高度值单位通常是米。这个高度值可能用于放置三维模型、生成贴地线条、做通视分析、计算土方量等等。不同用途对精度的要求不一样对实时性的要求也不一样所以方法的选择会有差异。2. 理解 Cesium 地形体系的基本运作方式2.1 地形数据在 Cesium 里是怎么组织的Cesium 的地形不是一张完整的全球高程图而是按照四叉树结构切成的瓦片。每个瓦片覆盖一定的经纬度范围内部存储了规则网格上的高程采样值。当你把相机移动到某个区域时Cesium 会根据当前视野动态请求对应层级的地形瓦片。层级越高瓦片覆盖的范围越小网格越密高程精度也越高。这个机制带来一个很关键的后果高程数据是异步加载的。你调用 API 的那一刻目标位置的地形瓦片可能还没请求回来也可能只加载了低精度的层级。如果代码没有正确处理这个异步过程拿到的结果要么是 undefined要么是一个精度很差的近似值。理解这一点之后后面所有的“坑”基本都能找到根源。很多新手写代码的时候习惯性地认为“我调了函数就应该立刻返回结果”但在 Cesium 的地形体系里这个假设是不成立的。2.2 两种地形提供方式对高程获取的影响Cesium 支持两种地形数据来源一种是需要额外配置的地形服务通过CesiumTerrainProvider加载另一种是不配置任何地形时的默认椭球体表面。这两种情况下获取高程的方式和结果完全不同。不配置地形的时候viewer.terrainProvider是一个EllipsoidTerrainProvider它返回的高程永远是零相对于椭球体表面。这时候你去请求高程得到的就是零或者接近零的值看起来“能用”但实际上完全没有地形起伏的信息。很多新手就是因为忘了配置地形折腾半天以为代码有问题其实是数据源就没对。配置了地形服务之后terrainProvider变成了CesiumTerrainProvider或者CesiumTerrainProvider的子类它才能真正返回有起伏的高程数据。但这时候又涉及到服务地址是否可达、token 是否有效、瓦片格式是否匹配等一系列问题。实操心得每次开始一个新项目先确认viewer.terrainProvider的类型。如果它的构造函数名里带Ellipsoid说明你根本没加载地形数据后面所有高程获取都是白费功夫。3. 获取地形高程的几种主流方法及选型逻辑3.1 方法一sampleTerrain —— 最常用但有门槛Cesium.sampleTerrain是 Cesium 提供的一个静态方法用于在指定层级上对地形进行采样。它的基本用法是传入 terrainProvider、level 和一个 Cartesian3 数组返回一个 Promiseresolve 之后数组里的每个点就带上了高程值。这个方法的优点是精度可控——你可以指定采样层级层级越高越精确。缺点是它是异步的而且需要你手动指定层级。层级选低了精度不够选高了请求量大、耗时长。在实际项目里我一般会根据用途来定层级做宏观展示用 11 到 13 级就够了做工程级的土方计算至少要到 15 级以上。还有一个容易忽略的点sampleTerrain返回的高程是相对于地形数据的基准面的不一定是你想要的“海拔高度”。如果地形数据本身有偏移或者你用的不是标准的地形服务这个值可能需要额外校正。3.2 方法二sampleTerrainMostDetailed —— 省心但费性能如果你不想手动指定层级可以用Cesium.sampleTerrainMostDetailed。它会自动使用当前 terrainProvider 支持的最高层级来采样。听起来很美好但实际用起来要小心最高层级可能非常高导致请求大量瓦片页面卡顿甚至崩溃。我在一个项目里曾经对一个点调用了这个方法结果因为那个位置的地形服务支持到 18 级Cesium 一口气请求了几十个瓦片页面直接假死了好几秒。后来改成先判断用途如果只是放个标注用sampleTerrain指定 13 级就够了完全没必要用 MostDetailed。3.3 方法三globe.getHeight —— 同步但精度有限viewer.scene.globe.getHeight(cartographic)是一个同步方法返回指定经纬度处的地形高度。它的优点是调用简单、立即返回不需要处理 Promise。但它的精度取决于当前已经加载的地形瓦片如果目标位置的瓦片还没加载或者只加载了低层级返回值就不准确。这个方法适合什么场景呢适合做实时交互的粗略判断。比如用户鼠标在地图上移动时你想实时显示鼠标位置的大致高程用getHeight就很合适因为它的同步特性不会造成界面卡顿。但如果是要写入数据库或者做精确计算就不能依赖它。3.4 方法四相机拾取射线与地形求交还有一种思路是通过相机发射射线与地形求交来获取高程。这种方法在需要从屏幕坐标反推世界坐标时特别有用比如用户点击了屏幕上的某个像素你想知道那个像素对应的地形表面位置。Cesium 提供了scene.pickPosition和scene.globe.pick等 API 来实现这个功能。但这种方法的前提是地形瓦片已经加载完成否则射线打不到任何东西返回 undefined。而且它获取的是“射线与当前已加载地形的交点”如果地形加载不完整交点位置也会有偏差。3.5 方法选型对照表方法同步/异步精度控制适用场景主要风险sampleTerrain异步手动指定层级批量采样、精度可控层级选择不当导致精度或性能问题sampleTerrainMostDetailed异步自动最高层级单点高精度需求性能开销大可能卡顿globe.getHeight同步依赖已加载瓦片实时交互粗略显示瓦片未加载时结果不准射线求交同步依赖已加载瓦片屏幕坐标反推地形位置地形未加载时返回空选型的时候核心就两个问题你要多准你能等多久想清楚这两个问题方法自然就定了。4. 完整实操流程从零到拿到准确高程值4.1 环境准备与地形服务配置假设你已经有一个基本的 Cesium 项目在跑不管是用的原生 JS 还是 Vue、React 封装第一步都是确认地形服务已经正确配置。以常见的做法为例在初始化 Viewer 的时候传入 terrainProviderconst viewer new Cesium.Viewer(cesiumContainer, { terrainProvider: await Cesium.createWorldTerrainAsync({ requestWaterMask: true, requestVertexNormals: true }) });这里用的是createWorldTerrainAsync它是较新版本 Cesium 推荐的异步创建方式。老版本里可能是直接new Cesium.CesiumTerrainProvider({url: ...})但那个方式在新版本里已经标记为过时了。如果你用的是老版本代码升级的时候这里要特别注意。配置完成之后建议加一个检查console.log(viewer.terrainProvider.constructor.name);如果输出的是EllipsoidTerrainProvider说明地形没加载成功后面不用往下走了先排查服务地址和网络请求。4.2 用 sampleTerrain 获取单点高程的完整代码假设我们要获取某个经纬度点的高程比如东经 116.39 度、北纬 39.9 度附近的一个位置。完整流程如下// 第一步把经纬度转成 Cesium 的 Cartographic 对象 const cartographic Cesium.Cartographic.fromDegrees(116.39, 39.9); // 第二步调用 sampleTerrain指定层级为 13 const terrainProvider viewer.terrainProvider; const updatedPositions await Cesium.sampleTerrain(terrainProvider, 13, [cartographic]); // 第三步读取结果 const height updatedPositions[0].height; console.log(该点的高程为, height, 米);这段代码看起来简单但里面有几个关键点值得展开说。第一Cartographic.fromDegrees接收的是经度、纬度、高度三个参数高度可以省略默认是零。这里传入的零高度只是一个占位实际高程会被sampleTerrain覆盖。第二sampleTerrain的第二个参数是层级。这个层级不是随便选的它必须是你使用的 terrainProvider 支持的层级范围内的值。如果你传了一个超出范围的层级Cesium 可能会报错或者返回不准确的结果。第三sampleTerrain返回的是一个新的数组不会修改传入的原始对象。这一点在批量处理的时候要特别注意别搞混了引用关系。4.3 批量获取多个点的高程实际项目里更常见的是批量获取比如你有一组 GPS 轨迹点想一次性拿到所有点的高程。这时候直接把数组传进去就行const coordinates [ Cesium.Cartographic.fromDegrees(116.39, 39.9), Cesium.Cartographic.fromDegrees(116.40, 39.91), Cesium.Cartographic.fromDegrees(116.41, 39.92) ]; const results await Cesium.sampleTerrain(viewer.terrainProvider, 13, coordinates); results.forEach((carto, index) { console.log(第 ${index 1} 个点的高程${carto.height} 米); });批量处理的时候有一个性能上的注意事项如果点的数量很大比如几千个一次性传给sampleTerrain可能会导致请求的瓦片数量过多页面卡顿。我的做法是分批处理每批 50 到 100 个点批与批之间加一个小的延迟让浏览器有时间喘口气。4.4 层级选择的计算依据层级到底选多少合适这个问题没有标准答案但可以根据精度需求来估算。Cesium 的地形瓦片在层级 n 下的地面分辨率大致可以用下面的公式估算地面分辨率 ≈ 地球周长 / (2^n × 瓦片网格数)以常见的 65×65 网格为例在层级 13 时每个采样点之间的地面距离大约是几十米层级 15 时降到十几米层级 17 时只有几米。所以如果你的应用需要米级精度至少要用 15 级以上。但层级越高需要请求的瓦片越多耗时越长。我在一个需要 15 级精度的项目里实测过单点采样大约需要 1 到 2 秒批量 100 个点大约需要 5 到 8 秒。这个时间在后台处理任务里可以接受但在前端实时交互里就太慢了。实操心得如果项目对精度要求高但又不想让用户等可以考虑在后台预计算好高程数据存到数据库里前端直接查表。这样既保证了精度又避免了实时采样的性能问题。5. 常见问题与排查技巧实录5.1 返回的高程值始终为零或 undefined这是最常见的问题没有之一。排查思路按以下顺序来先确认viewer.terrainProvider是不是EllipsoidTerrainProvider。如果是说明地形服务根本没加载检查创建 Viewer 时的配置以及网络请求里有没有地形瓦片的请求记录。如果地形服务配置了但返回还是零检查目标位置的经纬度是否在服务覆盖范围内。有些地形服务只覆盖特定区域超出范围的位置会返回默认值。如果返回的是 undefined大概率是异步处理出了问题。确认你用了await或者.then()来等待 Promise 完成而不是直接读取结果。5.2 高程值明显偏大或偏小这种情况通常是层级选择不当导致的。低层级的地形瓦片网格稀疏采样值可能偏离真实地形很多。尤其是在山区低层级采样可能把山峰和山谷平均掉了导致高程值严重失真。解决办法就是提高采样层级或者改用sampleTerrainMostDetailed。但要注意性能开销别为了精度把页面搞崩了。还有一种可能是地形数据的基准面和你预期的基准面不一致。比如某些地形服务的高程是相对于当地平均海平面的而你的应用预期的是相对于 WGS84 椭球体的。这种情况下需要做基准面转换具体转换参数要查地形服务的文档。5.3 批量采样时页面卡死前面提到过批量采样大量点时容易卡死。除了分批处理之外还有一个技巧是先用低层级快速获取一遍然后再对关键点用高层级精修。这样可以在保证整体效率的同时对重点区域提供足够的精度。另外如果采样任务不需要实时完成可以考虑放到 Web Worker 里去做避免阻塞主线程。不过 Cesium 的 terrainProvider 在 Worker 里的使用有一些限制需要额外处理。5.4 不同版本 Cesium 的 API 差异Cesium 从 1.100 版本开始对地形相关的 API 做了不少调整。比如createWorldTerrain变成了createWorldTerrainAsyncsampleTerrain的返回类型也有细微变化。如果你从网上抄的代码跑不通先检查一下版本号。我的建议是不管用什么版本都先去看对应版本的官方文档而不是依赖搜索引擎里的代码片段。搜索引擎里的内容时效性参差不齐很容易踩坑。5.5 问题排查速查表现象可能原因排查动作高程始终为零未配置地形服务检查 terrainProvider 类型高程为 undefined异步未等待确认使用了 await 或 then高程明显偏差采样层级过低提高层级或改用 MostDetailed批量采样卡死请求瓦片过多分批处理或降低层级API 报错不存在版本不匹配查阅对应版本官方文档部分点无高程超出服务覆盖范围检查地形服务覆盖区域6. 几个容易被忽略的细节和经验6.1 坐标系的隐式转换Cesium 内部使用笛卡尔坐标Cartesian3来表示位置而我们通常拿到的经纬度是地理坐标。Cartographic.fromDegrees做的是地理坐标到弧度的转换但不会自动处理高程。如果你从其他系统拿到的坐标已经带了高程要注意那个高程的基准面是否和 Cesium 的一致。另外Cartographic的经度和纬度单位是弧度不是度。虽然fromDegrees帮你做了转换但如果你直接构造Cartographic对象记得传弧度值。这个细节在调试的时候很容易搞混。6.2 地形瓦片的缓存机制Cesium 会缓存已经加载过的地形瓦片。这意味着如果你对同一个区域反复采样第一次可能比较慢后面就会快很多。利用这个特性可以在应用启动时预加载关键区域的地形瓦片后续采样就会很流畅。预加载的方法很简单把相机飞到目标区域等地形加载完成后再开始采样。或者直接用Cesium.sampleTerrain对目标区域的几个角点做一次采样触发瓦片加载。6.3 高程值的单位问题Cesium 返回的高程单位是米这一点是明确的。但如果你从其他数据源获取的高程是英尺或者其他单位记得做转换。我见过一个项目因为把英尺当米用导致所有标注都飘到了半空中排查了半天才发现是单位问题。6.4 地形服务的可用性监控在生产环境里地形服务可能会因为网络波动或者服务端问题而不可用。建议在代码里加一个降级逻辑如果地形服务请求失败自动切换到椭球体模式并给用户一个提示。这样至少保证应用不会完全崩溃。try { const terrainProvider await Cesium.createWorldTerrainAsync(); viewer.terrainProvider terrainProvider; } catch (error) { console.warn(地形服务加载失败使用默认椭球体, error); // 保持默认的 EllipsoidTerrainProvider }6.5 精度与性能的平衡策略最后再聊一下精度和性能的平衡。我的经验是不要追求“最高精度”而是追求“够用的精度”。大部分可视化场景13 级到 15 级的精度已经足够了。只有涉及到工程计算、土方量估算这类场景才需要 17 级以上的精度。而且高精度采样不一定要实时做。可以在数据准备阶段离线计算好存到数据库或者缓存里。前端只需要读取结果不需要每次都去请求地形瓦片。这样既保证了精度又保证了性能。我在最近一个项目里就是这么做的后台用 Node.js 跑了一个脚本把所有需要高程的点批量采样好存到 PostgreSQL 里。前端直接查数据库响应时间从原来的几秒降到了几十毫秒。这个思路对于数据量不大但精度要求高的场景特别适用。实操心得如果你的项目里高程数据是固定的比如设备安装点、监测站位置强烈建议离线计算好存起来。实时采样只适合那些位置动态变化的场景比如用户在地图上随意点击。