前阵子接了个活儿在 Cesium 三维地球里展示一块真实地形。需求看着不复杂但有一个硬条件——地形数据不能走公网必须本地生成、本地托底。这就意味着不能靠 Cesium 内置的在线地形也不能直接丢到云端平台一传了之。我花了两天把整条链路跑通从 DEM数字高程模型裸数据到切出来能被 CesiumTerrainProvider 直接消费的地形瓦片中间踩了不少坑。这篇就完整记一下我的处理过程、参数选择和避坑方法给后面要自建地形数据的同学一个可复制的参考。适合有 Cesium 基础但没碰过地形生成的人也适合要离线化部署三维地图的项目组。1. 先想清楚技术链路自建地形数据到底在解决什么问题1.1 Cesium 地形渲染的本质流式 LOD 瓦片很多人第一次用 Cesium 就发现new Cesium.Viewer(...)之后场景里默认带了一块椭球表面但是上面没有山川起伏。Cesium 的“地形”本质不是贴图而是一张精细的三角网高度场。它按照四叉树结构把全球划分成密密麻麻的瓦片每个瓦片又是一个小网格网格顶点上带有高程值。浏览器拿到这些顶点坐标和高程再结合法线、光照和相机视距才渲染出能看到的起伏地表。这里最关键的一点是Cesium 的地形瓦片是流式加载的相机离哪里近哪里就加载更精细的子瓦片离远了就统一合并成粗糙的父瓦片。这种 LOD细节层次机制决定了地形文件的组织方式必须严格遵循固定的目录结构和元数据约定。Cesium 支持的离线地形格式主要有两种一种叫 Heightmap高度图一种叫 Quantized-Mesh量化网格后者是当前主流后面我会展开说。很多人会把“地形瓦片”和“影像瓦片”混为一谈。影像瓦片是一张张 256x256 的 JPEG/PNG 图片而地形瓦片是包含顶点坐标、高程索引、法线信息甚至水纹信息的二进制文件。这个区别直接决定了自建地形的处理方式和存储结构千万别用做影像切片的心态去套。1.2 为什么必须自建地形数据如果只是在公网演示直接用默认地形当然最简单。但我遇到的场景里项目必须断网运行地形数据不能经过第三方服务器。即使允许联网默认地形在部分网络环境的加载速度也相当不稳定用户的真实体验是“影像都加载出来了地形还是白板”。还有一类需求更直接客户手里有一份自己采集的高精度 DEM比如 2 米、5 米的无人机航测数据默认地形分辨率太低根本没法拿来展现真实地貌。这时唯一靠谱的方式就是自己把 DEM 切成 Cesium 需要的地形瓦片再部署到内网静态服务器上。自建地形还有另一个隐性收益可以对业务范围做裁剪和加密只发布项目涉及的区域。比如只切某片山区范围数据量会从全球级缩到十几万个瓦片以内本地加载性能反而比默认全球地形快得多。更重要的是离线环境下所有地形数据都在自己手里版本、精度、更新时间都可控不会因为第三方服务变化而影响项目交付。1.3 从 DEM 到 Terrain 瓦片的一条主链路整条链路捋清楚其实就四步搞到原始高程数据DEM一般是一个 GeoTIFF 文件用 GDAL 做格式、坐标系、范围的预处理用地形切片工具把 DEM 切成 quantized-mesh 瓦片形成layer.json{z}/{x}/{y}.terrain的目录结构把瓦片目录挂到任意静态服务器上在 Cesium 里配置CesiumTerrainProvider指向它。看着不多但每一步都有几个容易翻车的细节。下面我把我实操里最影响结果的参数和判断写清楚避免大家后面走弯路。2. 关键概念与方案选型动手之前先避开这几个坑2.1 第一手材料DEM 数据的选择与检查地形数据生成的地基就是 DEM。DEM 本身是一个栅格每个像素记录一个地面海拔值。不同来源的 DEM 分辨率差异很大直接影响最终地形的精细度。我这次用的是常见的 30 米分辨率开源高程模型肉眼看一下山体形态完全够用如果项目要展示更精细的冲沟、田坎、道路断面就得用 5 米甚至更高精度的航测 DEM。选数据源时我建议先确认四件事下面这个表格就是我的检查清单数据属性检查标准对切片结果的影响坐标系是 WGS84 经纬度还是投影坐标系Cesium 地形瓦片需要 WGS84 地理坐标投影坐标必须重投影高程基准海拔高还是椭球高相差一个大地水准面起伏山区可能差几十米像元位深16 位整型或 Float328 位只有 256 级高度山区会被量化成台阶无效值NoData是否有明确的 NoData 标记不处理会在区域边界生成深坑或黑洞我这次的数据源是客户提供的一块 GeoTIFF范围大概覆盖一片 20km×20km 的山区。拿到手第一件事就是跑gdalinfo先看它的坐标系、像素尺寸、波段类型和无效值。这一步没做扎实后面切出来全是问题。提示如果 DEM 的无效值没有被正确标记切片工具会把无效像素当普通高程参与插值最终在数据边缘产生一个向下的漏斗形凹坑。这个坑在切完瓦片后很难从目录结构上发现只有加载到 Cesium 里才能看到非常隐蔽。2.2 理解瓦片格式为什么 Quantized-Mesh 是主线Cesium 在早期版本里大量使用 heightmap 地形它本质上是每瓦片固定尺寸的高度数组生成简单但有两个短板一是顶点位置完全按等间隔排布无法根据地形起伏智能细化网格二是每片瓦片的 LOD 切换全靠客户端容易在陡峭区域露出明显的锯齿。Quantized-Mesh 是 Cesium 后来主推的格式每个瓦片是一个真正的不规则三角网顶点坐标经过量化高度和法线信息都打包在.terrain文件里加载时直接按索引渲染。用起来最直观的差别是quantized-mesh 地形在陡坡和沟壑处线条更贴合真实地貌同一级别下文件体积也更小。而且它原生支持requestVertexNormals和requestWaterMask这意味着你可以给地形加真实的斜坡光照效果还能在水体部分生成水面涟漪。所以我的建议很直接新项目无脑选 quantized-mesh除非你要兼容很老的 Cesium 版本或者只想快速出个粗糙预览。还有一个细节值得注意Quantized-Mesh 瓦片的顶点数通常是 65x65而不是影像瓦片那种 256x256。也就是说每个地形瓦片在屏幕上最多渲染 4225 个网格顶点再配合 LOD 层级形成一个兼顾渲染效率和细节的三角网。这个 65 就是切片工具里常见的--tile-size参数。2.3 工具链与坐标系动手前必须认的两件事生成 quantized-mesh 瓦片常见路线有两种一种是把 DEM 上传到云平台让它帮你切好瓦片再配置 token 访问另一种是用开源工具在本地切。我这个项目因为必须离线直接走了本地开源工具。工具选型时主要看三点是否支持 GeoTIFF 直接输入、切出来的瓦片是否带layer.json、是否支持指定最大层级和采样范围。大多数本地切片工具都能满足关键是要先验证输出格式是不是 Cesium 的 quantized-mesh而不是通用 3D Tiles。坐标系这块是最容易出错的环节。Cesium 的地形瓦片默认使用 WGS84 经纬度坐标而这个坐标系下经纬度是角度不是米。如果你的原始 DEM 是 UTM 投影或者高斯投影里面每个像素的宽高是米必须先用gdalwarp重投影成 EPSG:4326。重投影之后栅格像素不再是规则的方形米格而是规则的角度格Cesium 切片的 LOD 才符合预期。3. 实操记录从 DEM 到 Cesium 地形的完整过程3.1 动手第一步gdalinfo 检查数据底子我拿到 GeoTIFF 后先跑了一条命令gdalinfo input_dem.tif看几个关键字段Size is表示宽高像元数Coordinate System is显示坐标系Pixel Size表示地面分辨率Band 1下的Type表示像元类型NoData Value表示无效值。我这次的数据是 WGS84 经纬度坐标30 米分辨率16 位整型。如果你看到的是 UTM 投影或者没有 NoData 值后续就必须先处理。另一个要确认的是数据范围和业务范围是否匹配。我拿到数据时范围比业务区大了一圈而且周边是无效的黑色区域。Cesium 地形切片工具遇到边缘无效值可能生成异常地形所以动手前我先把 DEM 裁剪到实际需要的地块。这一步其实还减少了后面瓦片的数量属于一举两得。如果有人给你的是多块碎 DEM千万别直接切片。多块 DEM 之间可能存在重叠、缝隙和高程不一致切出来的瓦片接缝处会非常难看。我的习惯是先看每块数据的gdalinfo确认四至范围和坐标系完全一致再决定要不要合并。3.2 预处理重投影、合并与裁剪如果 DEM 坐标系不是 WGS84先重投影。我用了双线性插值因为地形是连续表面这种插值不会像最近邻那样产生生硬的台阶又比三次卷积速度快gdalwarp -t_srs EPSG:4326 -r bilinear -of GTiff input_dem.tif wgs84_dem.tif如果业务区跨多块 DEM先用gdal_merge.py合并python3 gdal_merge.py -o merged_dem.tif -init 0 -n 0 tile1.tif tile2.tif tile3.tif参数-n 0表示把 0 当作 NoData这样可以排除无效区-init 0指定背景值。合并完再按目标范围裁剪gdalwarp -te 12.00 56.00 12.20 56.20 -tr 0.00027777778 0.00027777778 -r bilinear -of GTiff merged_dem.tif clip_dem.tif-te后面依次是最小经度、最小纬度、最大经度、最大纬度-tr表示目标分辨率30 米换算成度大概是1/3600也就是0.0002777778。这样输出栅格的每像素就是规整的 30 米采样后面切片工具计算层级时会很清爽。预处理做完再用gdalinfo clip_dem.tif看一遍确认范围、分辨率、NoData 都符合预期。我踩过的坑是裁剪之后忘记确认 NoData 值切出来的瓦片在区域边界出现一大块凹陷的黑洞。后来我在切片参数里显式声明 NoData 值才解决。3.3 切片生成 quantized-mesh 瓦片预处理完成后进入核心环节。我这里用的工具命令大致如下terrain-tiler \ --input clip_dem.tif \ --output ./cesium_terrain \ --max-level 15 \ --format cesium \ --tile-size 65 \ --no-data -32768不同工具的参数名有差异但核心逻辑一致读入 GeoTIFF从 level 0 开始逐级切分每个瓦片固定为 65x65 个顶点生成layer.json和一堆.terrain文件。--max-level 15并不是随便拍的我估算了这个级别下的瓦片分辨率已经接近原始 DEM 的分辨率再往上切不会产生更多真实细节只会白白增加瓦片数量。最大层级可以按这个思路估算Cesium 地形瓦片第z层全球大约有2^z个瓦片一块瓦片对应地面的尺寸大约是地球周长除以2^z。当这个尺寸接近原始 DEM 的两倍像素大小时说明这个层级已经能还原出 DEM 的细节再往下走就属于重复劳动。30 米分辨率 DEM 我通常给max-level 14到15如果是航测的 1 米分辨率max-level 17起也正常。有些切片工具会默认给瓦片加 skirt裙边也就是在瓦片边缘向下延伸一小圈三角网用来避免不同层级瓦片拼接时出现裂缝。如果你的工具默认没有记得手动开启这是保证 LOD 切换平滑的关键。生成完检查一下目录find ./cesium_terrain -type f | wc -l我这次切出来大概 8 万个.terrain文件和一个layer.json。文件数量有点多但不影响静态部署Nginx 处理静态小文件的能力足够。3.4 接入环节本地起服务并配置 CesiumTerrainProvider瓦片目录本质上只要求静态文件服务不需要后端处理。我在本地直接用 Python 起了一个静态服务cd cesium_terrain python3 -m http.server 8080然后写一个最简单的 Cesium 页面。如果你用的是老版本 API是这样配置的const viewer new Cesium.Viewer(cesiumContainer, { terrainProvider: new Cesium.CesiumTerrainProvider({ url: http://localhost:8080, requestVertexNormals: true, requestWaterMask: false }) });如果你用的是新版 Cesium更推荐异步方式const terrain await Cesium.Terrain.fromUrl(http://localhost:8080, { requestVertexNormals: true }); const viewer new Cesium.Viewer(cesiumContainer, { terrain });把相机飞到业务区验证地形是否生效viewer.camera.flyTo({ destination: Cesium.Cartesian3.fromDegrees(12.10, 56.10, 12000), orientation: { heading: 0, pitch: Cesium.Math.toRadians(-45), roll: 0 } });如果页面加载后能看到明显的山体起伏和坡度阴影说明瓦片格式和通信链路都通了。这里有个常见误区URL 不要拼到某个具体瓦片文件只要指到包含layer.json的根目录即可。CesiumTerrainProvider会自己请求layer.json然后按规则去请求{z}/{x}/{y}.terrain。3.5 部署后的性能与显示调优本地验证通过后我把它迁到了内网一台 Nginx 静态目录上。Nginx 配置很简单server { listen 8080; location /terrain/ { alias /data/cesium_terrain/; add_header Access-Control-Allow-Origin *; expires 1h; } }Access-Control-Allow-Origin这一行很多人会漏掉。如果你的 Cesium 页面和地形瓦片在不同端口或不同域名浏览器会因为跨域直接拦掉地形请求表现就是地形死活不显示但 F12 里能看到一堆 403。我这次本地http.server默认带了 CORS 头所以本地没踩到部署到 Nginx 时漏了排查了一会儿才定位。性能调优重点看三个参数maximumScreenSpaceErrorCesium 认为屏幕空间误差小于该值时不再细分瓦片默认 2。如果地形加载慢调高到 4 到 8会明显减少细腻瓦片的请求量。maximumLevel设置瓦片服务的最大层级防止客户端请求不存在的层级。enableLighting开启后地形会根据法线产生光影效果视觉立体感强但对性能有一点消耗。我最终把maximumScreenSpaceError设成了 4配合requestVertexNormals开启光照观感不错加载速度也比默认快了一截。4. 常见问题与排查技巧实录4.1 地形不显示从 403 到 provider 初始化失败最典型的症状页面能显示地球但地形区域要么是平的一大块要么黑乎乎一片。优先排查顺序如下跨域问题看浏览器控制台有没有 CORS 报错。有的话先在后端加响应头。URL 配错确认CesiumTerrainProvider的 URL 指向包含layer.json的目录而不是某个具体的瓦片路径。layer.json 缺失或格式错误切片工具没生成或者手动改动过内部字段Cesium 会直接抛出 Provider 初始化失败。瓦片请求 404如果请求的级别超出了max-level或maximumLevel说明最大层级配置和实际生成层级对不上。我遇到过一次诡异情况切完瓦片后把目录从服务器 A 拷贝到服务器 B 时layer.json和.terrain文件同级目录变成了layer.json加上一个子文件夹串。原因是压缩包解压时多了一层目录。后来我写了个小脚本在目录启动时检查路径结构发现问题立刻报错。下面是一张速查表基本覆盖我遇到过的地形不显示问题现象可能原因处理建议网络请求报 403跨域头缺失后端加Access-Control-Allow-OriginProvider 初始化失败layer.json非法或 URL 未指向根目录重新生成核对 URL瓦片 404最大层级配置不一致同步max-level与maximumLevel地球变白或黑屏相机位置未设到瓦片范围飞到业务区中心或设置imageryProvider4.2 高程数值不对坐标系、高程基准与无效值这个坑最隐藏。看现象是山体基本变形整体被压扁或者拔高甚至出现一片负数深坑。通常是两类原因高程基准不一致或者 NoData 值被当成了真实高程。Cesium 的地形高度是相对 WGS84 椭球面的很多 DEM 的高程是相对平均海平面的。两者之间差一个大地水准面起伏在山区可以达到十几米甚至几十米。这在宏观山体上视觉看不出太大差别但你要是做水平面交汇核算就会发现水库、道路的高程对不上。解决办法是拿到数据时先问清楚高程基准如果是海拔高处理层加一个 geoid 改正 DEM或者在 Cesium 端把所有地形高度做统一平移但后者不够精确。NoData 值的问题更隐蔽。如果 DEM 在岸边和河谷区域是无效值 0切片工具可能把 0 当作海平面高度于是原本应是断面的地方生成一个深坑。检查办法是在预处理后用gdalinfo -hist看高程直方图确认无效值占比切片参数里显式声明 NoData就能让工具跳过无效像素。4.3 瓦片接缝与 LOD 跳变skirt 和数据边界的双重排查相邻两个不同层级的瓦片渲染时如果边缘顶点对不齐会出现一条细小的白色或者地形断裂线。数字孪生项目里这种裂缝特别扎眼。Cesium 对 quantized-mesh 的边缘顶点有裙边机制在每个瓦片底部向下多延伸一小圈三角这样不同层级瓦片拼合时高度差异会被裙边遮挡住。如果裂缝很严重先看工具生成参数里有没有启用 skirt。有的工具参数叫--skirt-height一般给 1 到 5 米即可太大反而会造成山体边缘悬空。另外还要检查原始 DEM 是不是瓦片接缝处存在拼接断层这种是数据本身的问题skirt 救不回来要用gdal_merge时做边界羽化或者重新插值。还有一个容易被忽略的点瓦片层级的跳变不能跨级。Cesium 要求父子层级连续加载如果客户端从 level 10 直接跳到 level 12中间 level 11 的数据缺失就会看到“闪跳”或者一片空白。检查切片目录里是否有完整的跨层级索引必要时重新生成。4.4 瓦片加载性能问题缓存、SSE 与静态服务器优化地形瓦片动辄几万个浏览器不可能全部加载进来。Cesium 本身有 LRU 缓存但默认值可能不适合你的场景。我能直接落地的小技巧限制瓦片缓存数量如果出现纹理内存不足的报错可以调整viewer.scene.context.cacheBytes或者按机器内存反向调优。降低屏幕空间误差不是越低越好默认 2 已经不错调成 1 会疯狂请求瓦片页面卡成幻灯片。预置相机位置把相机初始视角设在业务区中心而不是默认全球视角避免前期加载大量无关瓦片。关闭水纹、法线插件如果场景不需要水体效果requestWaterMask: false能省掉相当一部分数据解析和 GPU 开销。还有一点部署环境是虚拟机或低配服务器时瓦片读取路径的磁盘 IO 很容易到瓶颈。建议把瓦片目录放到 SSD 上并用 Nginxexpires开启浏览器缓存。实测下来瓦片请求数量可以减少 60% 以上加载时间肉眼可见缩短。5. 地形数据生成后的长期维护经验5.1 数据更新不改整体只刷局部自建瓦片不是一锤子买卖。如果业务区 DEM 后续有更新比如房屋拆除、填方造地、道路改线你就得重新生成对应区域的瓦片。这个时候全量重切不现实我的建议是保持原始 DEM 预处理阶段的数据组织不变只在业务区新增或替换的小块 GeoTIFF 上重新执行同样的预处理和切片命令然后把新瓦片覆盖回原目录。有一点要提醒覆盖前先备份layer.json并确认新老瓦片的层级范围和坐标系完全一致。我遇到过一次新瓦片是投影坐标系老瓦片是 WGS84两者在业务区边缘直接错位了两三百米。后来我养成了每次重新切片之后先用 Cesium 飞到业务区边缘看一圈的习惯虽然土但非常可靠。5.2 视觉与功能扩展地形数据的下一步地形数据生成成功后视觉进一步升级的方向主要有这些叠加影像图真实地表色调加真实地形起伏效果直接提升一个档次。开启地形光照配置requestVertexNormals后再加上viewer.scene.globe.enableLighting true山体阴影会随相机视角变化比扁平颜色真实得多。加水体遮罩如果业务区有水库、湖泊且 DEM 高程准确设置requestWaterMask: true后可以看到动态水面效果。动态地形分析这类能力适合科研类项目比如模拟洪水淹没线、填方挖方分析普通展示项目用不到知道有这层能力即可。给后面要做类似项目的同学一个最终建议先花十分钟gdalinfo看清原始 DEM 的坐标系、位深、无效值再决定后面怎么切切片参数里max-level宁可低一点也别因为高而产生海量无用的细碎瓦片加载到 Cesium 之后先用maximumScreenSpaceError 4做性能验证再决定要不要开更高精度。我个人最终把整套流程固化成了一个脚本输入原始 DEM 区域范围自动完成重投影、裁剪、切片、静态部署最后跑一个 curl 模拟 Cesium 请求layer.json和任意一层瓦片确认 HTTP 返回正常。这个脚本在之后几次数据更新中帮我省了大量重复劳动。如果你也在做 Cesium 离线项目建议尽早建立起自己的“预处理 切片 校验”闭环这比每次手动操作要稳得多。