1. 为什么地形高程这件事值得单独拿出来讲但凡做过三维地理可视化项目的人迟早都会碰到一个绕不开的问题我手上有一个经纬度坐标怎么知道这个点在地面上到底有多高这个问题听起来简单但在 Cesium 里它牵扯到地形瓦片加载、异步采样、精度取舍、性能开销等一连串细节。我见过不少项目模型飘在半空中、标注点扎进地底、路径贴着山体穿模追根溯源十有八九是地形高程没取对。Cesium 作为三维地球引擎本身提供了地形服务接入能力但“接入地形”和“准确拿到某个坐标点的高程”是两码事。前者只是把地形数据挂上去渲染后者需要你主动去查询、采样、处理异步回调。很多新手以为场景里加载了地形cartographic里的height就自动是地形高度了结果发现拿到的永远是 0 或者一个固定值这就是典型的认知偏差。这篇内容适合三类人一是刚接触 Cesium、正在做点位标注或模型放置的开发者二是项目里已经用了地形但高程数据总是不准、需要排查的工程师三是想搞清楚不同采样方法差异、做技术选型的技术负责人。我会把 Cesium 获取地形高程的几种主流方法、各自的适用场景、参数背后的逻辑、以及我实际踩过的坑尽量讲透。核心关键词就一个——地形高程采样围绕它展开坐标点、异步、精度、性能这几条线。先说结论性的认知Cesium 里获取高程本质上是从地形瓦片数据里做插值查询它是一个异步过程且精度受限于地形数据本身的分辨率。理解这两点后面所有方法的选择和问题的排查都会顺理成章。2. 地形高程采样的核心原理与方案选型2.1 高程到底从哪里来地形瓦片与插值逻辑要搞清楚怎么取高程得先明白高程数据在 Cesium 里是怎么存的。Cesium 的地形不是一张连续的高程图而是被切成一块块瓦片Tile按层级Level组织。每个瓦片里存的是一组规则网格上的高程采样值网格分辨率随层级变化——层级越高瓦片越小网格越密精度越高。当你调用采样接口查询某个经纬度的高程时Cesium 做的是这么几件事先根据坐标和当前相机状态确定需要哪些层级的瓦片然后在这些瓦片的网格数据里找到该坐标落在哪个网格单元内再用双线性插值bilinear interpolation算出这个点的高程。注意是插值不是精确值。也就是说你拿到的永远是网格四个角点高程加权平均后的结果网格越粗误差越大。这就解释了一个常见现象同一个坐标点在不同缩放层级下采样得到的高程可能不一样。因为层级变了参与插值的瓦片网格分辨率变了。所以做高程采样时必须明确你要的是哪个精度层级的结果不能拿到一个数就用。提示地形瓦片有“可用层级”的概念。如果你请求的层级超过了地形服务实际提供的最大层级Cesium 会回退到较低层级此时精度会下降但不会报错。这一点在排查“高程不准”时经常被忽略。2.2 三种主流采样方式的定位与取舍Cesium 里获取地形高程常用的有三条路sampleTerrain、sampleTerrainMostDetailed、以及基于Scene的pickPosition或globe.getHeight。它们不是互相替代的关系而是各有各的适用面。sampleTerrain(terrainProvider, level, positions)是指定层级采样。你告诉它用哪个层级的瓦片它就去那个层级取。优点是可控——你知道自己拿的是哪个精度的数据性能也相对可预期。缺点是你得自己判断该用哪一级层级选低了不准选高了可能瓦片还没加载完或者地形服务根本不支持那么高层级。sampleTerrainMostDetailed(terrainProvider, positions)是最高可用层级采样。它会自动去查地形服务在当前坐标处能提供的最高层级然后用那个层级采样。优点是省心、精度通常最高。缺点是异步耗时更长因为它可能要等更高层级的瓦片加载而且不同坐标点可能落在不同层级上批量采样时耗时不可控。globe.getHeight(cartographic)是同步取当前渲染高度。它返回的是当前场景里该点已经渲染出来的高度速度极快但前提是那个位置的地形瓦片已经加载并渲染完成。如果瓦片没加载它返回 undefined 或者一个不准的值。所以它适合做实时交互比如鼠标移动时显示高程不适合做后台批量计算。选型逻辑可以这样记后台批量、要精度、能等异步用 mostDetailed要可控、知道自己在干嘛用 sampleTerrain 指定层级实时交互、瓦片已加载用 getHeight。方法同步/异步精度性能典型场景sampleTerrain异步取决于指定层级可控批量采样、指定精度sampleTerrainMostDetailed异步最高可用较慢精度优先的批量任务globe.getHeight同步取决于已加载瓦片极快实时交互、鼠标拾取2.3 异步这件事为什么绕不过去很多人第一次用sampleTerrain会懵为什么我调用完返回值是 undefined因为它返回的是一个 Promise。地形数据不在内存里得去请求、去加载、去插值这一套流程必然是异步的。Cesium 把结果通过 Promise 回调给你你必须用.then()或者async/await来接。这个异步特性带来两个实际问题。第一批量采样时你得等所有 Promise 完成才能继续否则拿到的是一堆 pending。第二如果采样点很多一次性发起几百上千个请求可能把地形服务打爆或者触发浏览器的并发限制。所以批量采样一定要做分批处理这个后面实操部分会详细讲。理解了原理和选型接下来进入具体怎么用、怎么调、怎么避坑。3. 核心接口的实操要点与参数拆解3.1 sampleTerrain 的层级参数到底怎么定sampleTerrain的第一个参数是 terrainProvider第二个是 level第三个是 positions 数组。最容易出问题的就是 level。这个 level 对应的是地形瓦片的层级不是地图缩放层级但两者有关联。地形服务的层级范围通常是 0 到某个最大值比如 15 或更高取决于数据源。level 选多少直接决定精度和耗时。我一般的经验是做区域级分析level 取 11 到 13 够用做单体建筑或精细场景取 14 到 16再高就要看地形服务支不支持了。这里有个坑如果你指定的 level 超过了地形服务实际提供的最大层级Cesium 不会报错而是静默回退到可用层级。你以为自己拿的是 16 级精度实际可能是 13 级。排查方法是在采样后检查返回的cartographic.height是否合理或者直接查 terrainProvider 的availability属性看最大层级。// 指定层级采样的标准写法 const terrainProvider viewer.terrainProvider; const positions [ Cesium.Cartographic.fromDegrees(116.39, 39.91), Cesium.Cartographic.fromDegrees(116.40, 39.92) ]; Cesium.sampleTerrain(terrainProvider, 13, positions).then((updatedPositions) { updatedPositions.forEach((pos) { console.log(经度:, Cesium.Math.toDegrees(pos.longitude)); console.log(纬度:, Cesium.Math.toDegrees(pos.latitude)); console.log(高程:, pos.height); }); });注意sampleTerrain是原地修改传入的 positions 数组里的 Cartographic 对象的 height 属性同时 Promise 返回的也是这个数组。所以如果你传进去的对象后续还要用要留意它被改了。3.2 sampleTerrainMostDetailed 的精度诱惑与性能代价sampleTerrainMostDetailed用起来更省心不用管层级。它会自动查询每个坐标点处地形服务的最高可用层级。听起来很美好但代价是耗时。它的内部逻辑是对每个坐标点先问地形服务“你这里最高能到几级”然后去加载那个层级的瓦片再插值。如果地形服务层级很高或者坐标点分布很散加载的瓦片数量会很多耗时可能从几百毫秒到几秒不等。// 最高可用层级采样 Cesium.sampleTerrainMostDetailed(terrainProvider, positions).then((updatedPositions) { updatedPositions.forEach((pos) { console.log(高程:, pos.height); }); });我的实测经验是单点或少量点10 个以内用 mostDetailed 没问题上百个点就要慎重最好分批上千个点基本要考虑预计算或者降级到指定层级采样。因为 mostDetailed 对每个点都可能触发独立的瓦片请求点多了请求数会爆炸。注意mostDetailed 的“最高可用层级”是逐点判断的。也就是说A 点可能用 15 级B 点可能用 12 级最终结果里不同点精度不一致。如果你的业务要求所有点精度统一那还是用 sampleTerrain 指定固定层级更稳妥。3.3 globe.getHeight 的同步陷阱globe.getHeight是同步的返回一个数字或 undefined。它的原理是查当前场景里该点已经渲染的地形高度。所以它快但不可靠——取决于瓦片加载状态。// 同步获取当前渲染高度 const cartographic Cesium.Cartographic.fromDegrees(116.39, 39.91); const height viewer.scene.globe.getHeight(cartographic); if (Cesium.defined(height)) { console.log(当前渲染高程:, height); } else { console.log(该位置地形尚未加载); }它最适合的场景是鼠标移动实时显示高程。你监听ScreenSpaceEventHandler的MOUSE_MOVE把屏幕坐标转成经纬度再调 getHeight就能实时显示。但如果瓦片没加载完它会返回 undefined这时候要么等要么给个默认值。我踩过的坑是在相机快速移动时getHeight 返回的值会跳变因为不同位置的瓦片加载状态不一样。所以做实时显示时最好加个平滑或者容差判断避免数字乱跳影响体验。4. 完整实操流程与批量采样实现4.1 从零搭建一个可复现的高程采样环境要复现后面的实操你需要一个基本的 Cesium 场景。这里不展开 Cesium 的完整搭建只讲和高程采样相关的配置。首先创建 Viewer 时要确保地形已接入。地形服务的接入方式取决于你用的数据源这里用通用的写法示意const viewer new Cesium.Viewer(cesiumContainer, { terrainProvider: await Cesium.createWorldTerrainAsync() });createWorldTerrainAsync是较新版本的异步创建方式老版本用createWorldTerrain。接入后viewer.terrainProvider就是当前的地形提供者采样时要用到它。然后准备坐标数据。实际项目里坐标可能来自 GeoJSON、CSV、数据库这里用数组模拟const lngLats [ [116.391, 39.907], [116.395, 39.910], [116.400, 39.915], // ... 更多点 ]; const positions lngLats.map(([lng, lat]) Cesium.Cartographic.fromDegrees(lng, lat) );到这里环境就绪。接下来是采样。4.2 分批采样的完整实现与参数计算前面说了批量采样不能一次性全发。那分多少批合适我的经验值是每批 20 到 50 个点。太少批次数多总耗时长太多单批请求压力大可能超时。分批的逻辑很简单把 positions 数组按批大小切片逐批 await 采样把结果收集起来。async function sampleTerrainInBatches(terrainProvider, positions, level, batchSize 30) { const results []; for (let i 0; i positions.length; i batchSize) { const batch positions.slice(i, i batchSize); const sampled await Cesium.sampleTerrain(terrainProvider, level, batch); results.push(...sampled); console.log(已完成 ${Math.min(i batchSize, positions.length)} / ${positions.length}); } return results; } // 调用 sampleTerrainInBatches(viewer.terrainProvider, positions, 13, 30).then((results) { results.forEach((pos, idx) { console.log(点 ${idx}: 高程 ${pos.height.toFixed(2)} 米); }); });这段代码的关键点用for循环配合await保证一批完成再发下一批避免并发爆炸。batchSize设成 30 是我在多个项目里试出来的平衡点你可以根据地形服务的响应速度调整。如果你用的是 mostDetailed把Cesium.sampleTerrain换成Cesium.sampleTerrainMostDetailed即可但 batchSize 建议调小到 10 到 20因为它单点耗时更长。4.3 采样结果的处理与可视化验证拿到高程后通常要做两件事一是把高程写回业务数据二是可视化验证采样是否正确。写回业务数据就是遍历 results把 height 存到你的对象里。可视化验证我习惯用点图元PointPrimitive或者小模型把采样点画出来看看是不是贴地。results.forEach((pos) { viewer.entities.add({ position: Cesium.Cartesian3.fromRadians(pos.longitude, pos.latitude, pos.height), point: { pixelSize: 8, color: Cesium.Color.RED } }); });如果点贴在地面上说明采样正确如果飘在空中或扎进地里说明高程有问题要回去查层级、查地形服务、查坐标是否写反了经纬度。经纬度写反是新手最常见的错误症状就是高程完全不对因为采样点跑到地球另一边去了。提示验证时最好选一个有明显地形起伏的区域比如山区。平原地区高程变化小采样错了也不容易看出来。5. 常见问题排查与避坑经验实录5.1 高程返回 undefined 或 0 的排查路径这是最高频的问题。排查顺序我一般是这样第一确认地形服务真的接入了。打印viewer.terrainProvider看是不是EllipsoidTerrainProvider默认的椭球地形没有真实高程。如果是说明地形没接上采样自然全是 0。第二确认坐标对象类型对。sampleTerrain要的是Cartographic数组不是Cartesian3也不是{lng, lat}普通对象。类型不对会直接报错或返回异常值。第三确认层级没超限。前面说过层级超了会静默回退但如果地形服务本身不可用可能返回 undefined。检查 terrainProvider 的availability。第四确认异步处理正确。如果你在 Promise 外面直接读 positions 的 height那肯定是 undefined因为异步还没完成。症状可能原因排查方法全部返回 0地形未接入检查 terrainProvider 类型返回 undefined异步未完成/层级超限检查 await、检查 availability部分点异常坐标越界/经纬度写反打印坐标检查范围高程明显偏大偏小层级过低/插值误差提高层级重试5.2 采样精度不够的几种补救思路精度不够的表现是采样点高程和实际地形对不上模型贴地有缝隙。补救思路有三条。一是提高采样层级。如果原来用 11 级试试 13 或 14 级。但要注意地形服务是否支持以及耗时是否可接受。二是改用 mostDetailed。它会自动用最高层级精度通常最好。代价是慢。三是检查地形数据源本身的分辨率。如果地形数据本身就是低分辨率的你再怎么采样也拿不到高精度。这时候要考虑换数据源而不是在采样方法上折腾。我个人的经验是先确认数据源精度上限再决定采样层级。很多人一上来就调层级结果数据源只到 12 级调再高也没用。5.3 性能优化的几个实操技巧批量采样慢优化方向有几个。第一能预计算就预计算。如果采样点固定不变比如一批基站、一批监测点完全可以在后台用工具预先算好高程存进数据库前端直接读。这样前端零采样开销。第二能降级就降级。不是所有业务都需要最高精度。展示用的点13 级够用分析用的点再上 mostDetailed。第三控制并发。前面讲的分批就是一种并发控制。另外可以用Promise.all配合批次而不是逐点 await这样单批内并行批间串行效率更高。// 批内并行、批间串行的优化写法 async function sampleFast(terrainProvider, positions, level, batchSize 30) { const results []; for (let i 0; i positions.length; i batchSize) { const batch positions.slice(i, i batchSize); const sampled await Promise.all( batch.map((pos) Cesium.sampleTerrain(terrainProvider, level, [pos])) ); results.push(...sampled.flat()); } return results; }不过要注意这种写法对地形服务的瞬时压力更大batchSize 要相应调小。我一般用 10 到 15。第四加缓存。同一个坐标点如果多次采样结果应该缓存起来避免重复请求。用一个 Mapkey 用经纬度字符串value 存高程。5.4 几个我踩过的真实坑坑一在相机还没稳定时采样。如果场景刚初始化地形瓦片还没加载采样可能拿到不准的值。我的做法是等viewer.scene.globe.tileLoadProgressEvent归零或者延迟几百毫秒再采样。坑二坐标精度丢失。用fromDegrees时如果传的是字符串可能出问题。确保传数字。坑三mostDetailed 在点很密集时反而慢。因为密集点可能落在同一瓦片但 mostDetailed 对每个点独立判断层级没有做瓦片级合并。这时候用 sampleTerrain 指定层级反而更快。坑四地形服务跨域或鉴权问题。有些地形服务需要 token 或跨域配置没配好会导致瓦片加载失败采样返回异常。这个要在网络面板里看请求状态。这些坑文档里基本不会写都是实际做项目时一个个撞出来的。希望看到这里的你能少走点弯路。最后分享一个小技巧如果你只是想在鼠标悬停时显示高程别用 sampleTerrain用globe.getHeight配合MOUSE_MOVE事件就够了响应快代码也简单。真正需要精确高程的场景再上异步采样。工具用对地方比用得多更重要。
1. 为什么地形高程这件事值得单独拿出来讲但凡做过三维地理可视化项目的人迟早都会碰到一个绕不开的问题我手上有一个经纬度坐标怎么知道这个点在地面上到底有多高这个问题听起来简单但在 Cesium 里它牵扯到地形瓦片加载、异步采样、精度取舍、性能开销等一连串细节。我见过不少项目模型飘在半空中、标注点扎进地底、路径贴着山体穿模追根溯源十有八九是地形高程没取对。Cesium 作为三维地球引擎本身提供了地形服务接入能力但“接入地形”和“准确拿到某个坐标点的高程”是两码事。前者只是把地形数据挂上去渲染后者需要你主动去查询、采样、处理异步回调。很多新手以为场景里加载了地形cartographic里的height就自动是地形高度了结果发现拿到的永远是 0 或者一个固定值这就是典型的认知偏差。这篇内容适合三类人一是刚接触 Cesium、正在做点位标注或模型放置的开发者二是项目里已经用了地形但高程数据总是不准、需要排查的工程师三是想搞清楚不同采样方法差异、做技术选型的技术负责人。我会把 Cesium 获取地形高程的几种主流方法、各自的适用场景、参数背后的逻辑、以及我实际踩过的坑尽量讲透。核心关键词就一个——地形高程采样围绕它展开坐标点、异步、精度、性能这几条线。先说结论性的认知Cesium 里获取高程本质上是从地形瓦片数据里做插值查询它是一个异步过程且精度受限于地形数据本身的分辨率。理解这两点后面所有方法的选择和问题的排查都会顺理成章。2. 地形高程采样的核心原理与方案选型2.1 高程到底从哪里来地形瓦片与插值逻辑要搞清楚怎么取高程得先明白高程数据在 Cesium 里是怎么存的。Cesium 的地形不是一张连续的高程图而是被切成一块块瓦片Tile按层级Level组织。每个瓦片里存的是一组规则网格上的高程采样值网格分辨率随层级变化——层级越高瓦片越小网格越密精度越高。当你调用采样接口查询某个经纬度的高程时Cesium 做的是这么几件事先根据坐标和当前相机状态确定需要哪些层级的瓦片然后在这些瓦片的网格数据里找到该坐标落在哪个网格单元内再用双线性插值bilinear interpolation算出这个点的高程。注意是插值不是精确值。也就是说你拿到的永远是网格四个角点高程加权平均后的结果网格越粗误差越大。这就解释了一个常见现象同一个坐标点在不同缩放层级下采样得到的高程可能不一样。因为层级变了参与插值的瓦片网格分辨率变了。所以做高程采样时必须明确你要的是哪个精度层级的结果不能拿到一个数就用。提示地形瓦片有“可用层级”的概念。如果你请求的层级超过了地形服务实际提供的最大层级Cesium 会回退到较低层级此时精度会下降但不会报错。这一点在排查“高程不准”时经常被忽略。2.2 三种主流采样方式的定位与取舍Cesium 里获取地形高程常用的有三条路sampleTerrain、sampleTerrainMostDetailed、以及基于Scene的pickPosition或globe.getHeight。它们不是互相替代的关系而是各有各的适用面。sampleTerrain(terrainProvider, level, positions)是指定层级采样。你告诉它用哪个层级的瓦片它就去那个层级取。优点是可控——你知道自己拿的是哪个精度的数据性能也相对可预期。缺点是你得自己判断该用哪一级层级选低了不准选高了可能瓦片还没加载完或者地形服务根本不支持那么高层级。sampleTerrainMostDetailed(terrainProvider, positions)是最高可用层级采样。它会自动去查地形服务在当前坐标处能提供的最高层级然后用那个层级采样。优点是省心、精度通常最高。缺点是异步耗时更长因为它可能要等更高层级的瓦片加载而且不同坐标点可能落在不同层级上批量采样时耗时不可控。globe.getHeight(cartographic)是同步取当前渲染高度。它返回的是当前场景里该点已经渲染出来的高度速度极快但前提是那个位置的地形瓦片已经加载并渲染完成。如果瓦片没加载它返回 undefined 或者一个不准的值。所以它适合做实时交互比如鼠标移动时显示高程不适合做后台批量计算。选型逻辑可以这样记后台批量、要精度、能等异步用 mostDetailed要可控、知道自己在干嘛用 sampleTerrain 指定层级实时交互、瓦片已加载用 getHeight。方法同步/异步精度性能典型场景sampleTerrain异步取决于指定层级可控批量采样、指定精度sampleTerrainMostDetailed异步最高可用较慢精度优先的批量任务globe.getHeight同步取决于已加载瓦片极快实时交互、鼠标拾取2.3 异步这件事为什么绕不过去很多人第一次用sampleTerrain会懵为什么我调用完返回值是 undefined因为它返回的是一个 Promise。地形数据不在内存里得去请求、去加载、去插值这一套流程必然是异步的。Cesium 把结果通过 Promise 回调给你你必须用.then()或者async/await来接。这个异步特性带来两个实际问题。第一批量采样时你得等所有 Promise 完成才能继续否则拿到的是一堆 pending。第二如果采样点很多一次性发起几百上千个请求可能把地形服务打爆或者触发浏览器的并发限制。所以批量采样一定要做分批处理这个后面实操部分会详细讲。理解了原理和选型接下来进入具体怎么用、怎么调、怎么避坑。3. 核心接口的实操要点与参数拆解3.1 sampleTerrain 的层级参数到底怎么定sampleTerrain的第一个参数是 terrainProvider第二个是 level第三个是 positions 数组。最容易出问题的就是 level。这个 level 对应的是地形瓦片的层级不是地图缩放层级但两者有关联。地形服务的层级范围通常是 0 到某个最大值比如 15 或更高取决于数据源。level 选多少直接决定精度和耗时。我一般的经验是做区域级分析level 取 11 到 13 够用做单体建筑或精细场景取 14 到 16再高就要看地形服务支不支持了。这里有个坑如果你指定的 level 超过了地形服务实际提供的最大层级Cesium 不会报错而是静默回退到可用层级。你以为自己拿的是 16 级精度实际可能是 13 级。排查方法是在采样后检查返回的cartographic.height是否合理或者直接查 terrainProvider 的availability属性看最大层级。// 指定层级采样的标准写法 const terrainProvider viewer.terrainProvider; const positions [ Cesium.Cartographic.fromDegrees(116.39, 39.91), Cesium.Cartographic.fromDegrees(116.40, 39.92) ]; Cesium.sampleTerrain(terrainProvider, 13, positions).then((updatedPositions) { updatedPositions.forEach((pos) { console.log(经度:, Cesium.Math.toDegrees(pos.longitude)); console.log(纬度:, Cesium.Math.toDegrees(pos.latitude)); console.log(高程:, pos.height); }); });注意sampleTerrain是原地修改传入的 positions 数组里的 Cartographic 对象的 height 属性同时 Promise 返回的也是这个数组。所以如果你传进去的对象后续还要用要留意它被改了。3.2 sampleTerrainMostDetailed 的精度诱惑与性能代价sampleTerrainMostDetailed用起来更省心不用管层级。它会自动查询每个坐标点处地形服务的最高可用层级。听起来很美好但代价是耗时。它的内部逻辑是对每个坐标点先问地形服务“你这里最高能到几级”然后去加载那个层级的瓦片再插值。如果地形服务层级很高或者坐标点分布很散加载的瓦片数量会很多耗时可能从几百毫秒到几秒不等。// 最高可用层级采样 Cesium.sampleTerrainMostDetailed(terrainProvider, positions).then((updatedPositions) { updatedPositions.forEach((pos) { console.log(高程:, pos.height); }); });我的实测经验是单点或少量点10 个以内用 mostDetailed 没问题上百个点就要慎重最好分批上千个点基本要考虑预计算或者降级到指定层级采样。因为 mostDetailed 对每个点都可能触发独立的瓦片请求点多了请求数会爆炸。注意mostDetailed 的“最高可用层级”是逐点判断的。也就是说A 点可能用 15 级B 点可能用 12 级最终结果里不同点精度不一致。如果你的业务要求所有点精度统一那还是用 sampleTerrain 指定固定层级更稳妥。3.3 globe.getHeight 的同步陷阱globe.getHeight是同步的返回一个数字或 undefined。它的原理是查当前场景里该点已经渲染的地形高度。所以它快但不可靠——取决于瓦片加载状态。// 同步获取当前渲染高度 const cartographic Cesium.Cartographic.fromDegrees(116.39, 39.91); const height viewer.scene.globe.getHeight(cartographic); if (Cesium.defined(height)) { console.log(当前渲染高程:, height); } else { console.log(该位置地形尚未加载); }它最适合的场景是鼠标移动实时显示高程。你监听ScreenSpaceEventHandler的MOUSE_MOVE把屏幕坐标转成经纬度再调 getHeight就能实时显示。但如果瓦片没加载完它会返回 undefined这时候要么等要么给个默认值。我踩过的坑是在相机快速移动时getHeight 返回的值会跳变因为不同位置的瓦片加载状态不一样。所以做实时显示时最好加个平滑或者容差判断避免数字乱跳影响体验。4. 完整实操流程与批量采样实现4.1 从零搭建一个可复现的高程采样环境要复现后面的实操你需要一个基本的 Cesium 场景。这里不展开 Cesium 的完整搭建只讲和高程采样相关的配置。首先创建 Viewer 时要确保地形已接入。地形服务的接入方式取决于你用的数据源这里用通用的写法示意const viewer new Cesium.Viewer(cesiumContainer, { terrainProvider: await Cesium.createWorldTerrainAsync() });createWorldTerrainAsync是较新版本的异步创建方式老版本用createWorldTerrain。接入后viewer.terrainProvider就是当前的地形提供者采样时要用到它。然后准备坐标数据。实际项目里坐标可能来自 GeoJSON、CSV、数据库这里用数组模拟const lngLats [ [116.391, 39.907], [116.395, 39.910], [116.400, 39.915], // ... 更多点 ]; const positions lngLats.map(([lng, lat]) Cesium.Cartographic.fromDegrees(lng, lat) );到这里环境就绪。接下来是采样。4.2 分批采样的完整实现与参数计算前面说了批量采样不能一次性全发。那分多少批合适我的经验值是每批 20 到 50 个点。太少批次数多总耗时长太多单批请求压力大可能超时。分批的逻辑很简单把 positions 数组按批大小切片逐批 await 采样把结果收集起来。async function sampleTerrainInBatches(terrainProvider, positions, level, batchSize 30) { const results []; for (let i 0; i positions.length; i batchSize) { const batch positions.slice(i, i batchSize); const sampled await Cesium.sampleTerrain(terrainProvider, level, batch); results.push(...sampled); console.log(已完成 ${Math.min(i batchSize, positions.length)} / ${positions.length}); } return results; } // 调用 sampleTerrainInBatches(viewer.terrainProvider, positions, 13, 30).then((results) { results.forEach((pos, idx) { console.log(点 ${idx}: 高程 ${pos.height.toFixed(2)} 米); }); });这段代码的关键点用for循环配合await保证一批完成再发下一批避免并发爆炸。batchSize设成 30 是我在多个项目里试出来的平衡点你可以根据地形服务的响应速度调整。如果你用的是 mostDetailed把Cesium.sampleTerrain换成Cesium.sampleTerrainMostDetailed即可但 batchSize 建议调小到 10 到 20因为它单点耗时更长。4.3 采样结果的处理与可视化验证拿到高程后通常要做两件事一是把高程写回业务数据二是可视化验证采样是否正确。写回业务数据就是遍历 results把 height 存到你的对象里。可视化验证我习惯用点图元PointPrimitive或者小模型把采样点画出来看看是不是贴地。results.forEach((pos) { viewer.entities.add({ position: Cesium.Cartesian3.fromRadians(pos.longitude, pos.latitude, pos.height), point: { pixelSize: 8, color: Cesium.Color.RED } }); });如果点贴在地面上说明采样正确如果飘在空中或扎进地里说明高程有问题要回去查层级、查地形服务、查坐标是否写反了经纬度。经纬度写反是新手最常见的错误症状就是高程完全不对因为采样点跑到地球另一边去了。提示验证时最好选一个有明显地形起伏的区域比如山区。平原地区高程变化小采样错了也不容易看出来。5. 常见问题排查与避坑经验实录5.1 高程返回 undefined 或 0 的排查路径这是最高频的问题。排查顺序我一般是这样第一确认地形服务真的接入了。打印viewer.terrainProvider看是不是EllipsoidTerrainProvider默认的椭球地形没有真实高程。如果是说明地形没接上采样自然全是 0。第二确认坐标对象类型对。sampleTerrain要的是Cartographic数组不是Cartesian3也不是{lng, lat}普通对象。类型不对会直接报错或返回异常值。第三确认层级没超限。前面说过层级超了会静默回退但如果地形服务本身不可用可能返回 undefined。检查 terrainProvider 的availability。第四确认异步处理正确。如果你在 Promise 外面直接读 positions 的 height那肯定是 undefined因为异步还没完成。症状可能原因排查方法全部返回 0地形未接入检查 terrainProvider 类型返回 undefined异步未完成/层级超限检查 await、检查 availability部分点异常坐标越界/经纬度写反打印坐标检查范围高程明显偏大偏小层级过低/插值误差提高层级重试5.2 采样精度不够的几种补救思路精度不够的表现是采样点高程和实际地形对不上模型贴地有缝隙。补救思路有三条。一是提高采样层级。如果原来用 11 级试试 13 或 14 级。但要注意地形服务是否支持以及耗时是否可接受。二是改用 mostDetailed。它会自动用最高层级精度通常最好。代价是慢。三是检查地形数据源本身的分辨率。如果地形数据本身就是低分辨率的你再怎么采样也拿不到高精度。这时候要考虑换数据源而不是在采样方法上折腾。我个人的经验是先确认数据源精度上限再决定采样层级。很多人一上来就调层级结果数据源只到 12 级调再高也没用。5.3 性能优化的几个实操技巧批量采样慢优化方向有几个。第一能预计算就预计算。如果采样点固定不变比如一批基站、一批监测点完全可以在后台用工具预先算好高程存进数据库前端直接读。这样前端零采样开销。第二能降级就降级。不是所有业务都需要最高精度。展示用的点13 级够用分析用的点再上 mostDetailed。第三控制并发。前面讲的分批就是一种并发控制。另外可以用Promise.all配合批次而不是逐点 await这样单批内并行批间串行效率更高。// 批内并行、批间串行的优化写法 async function sampleFast(terrainProvider, positions, level, batchSize 30) { const results []; for (let i 0; i positions.length; i batchSize) { const batch positions.slice(i, i batchSize); const sampled await Promise.all( batch.map((pos) Cesium.sampleTerrain(terrainProvider, level, [pos])) ); results.push(...sampled.flat()); } return results; }不过要注意这种写法对地形服务的瞬时压力更大batchSize 要相应调小。我一般用 10 到 15。第四加缓存。同一个坐标点如果多次采样结果应该缓存起来避免重复请求。用一个 Mapkey 用经纬度字符串value 存高程。5.4 几个我踩过的真实坑坑一在相机还没稳定时采样。如果场景刚初始化地形瓦片还没加载采样可能拿到不准的值。我的做法是等viewer.scene.globe.tileLoadProgressEvent归零或者延迟几百毫秒再采样。坑二坐标精度丢失。用fromDegrees时如果传的是字符串可能出问题。确保传数字。坑三mostDetailed 在点很密集时反而慢。因为密集点可能落在同一瓦片但 mostDetailed 对每个点独立判断层级没有做瓦片级合并。这时候用 sampleTerrain 指定层级反而更快。坑四地形服务跨域或鉴权问题。有些地形服务需要 token 或跨域配置没配好会导致瓦片加载失败采样返回异常。这个要在网络面板里看请求状态。这些坑文档里基本不会写都是实际做项目时一个个撞出来的。希望看到这里的你能少走点弯路。最后分享一个小技巧如果你只是想在鼠标悬停时显示高程别用 sampleTerrain用globe.getHeight配合MOUSE_MOVE事件就够了响应快代码也简单。真正需要精确高程的场景再上异步采样。工具用对地方比用得多更重要。
