简介这是一份基于Cesium的三维水淹分析示例面向WebGIS开发者与地理信息学习者。项目依托Cesium与WebGL利用高程数据模拟不同水位下的淹没范围可用于环境评估、洪灾预测与城市规划等场景。压缩包共1个文件为单个HTML页面大小仅1KB源码结构简洁适合直接打开浏览器运行并对照学习。页面内集成了Cesium地形加载、水位与地形叠加、淹没区域渲染及交互调节等核心逻辑便于理解3D淹没分析从数据到可视化的完整流程。资源已有1020人学习对于想快速上手Cesium空间分析、掌握淹没模拟实现思路的开发者是一份轻量实用的参考案例。 做GIS三维开发这些年“淹没分析”四个字听得多真正动手做的时候才发现坑比想象中多。最近一个水利可视化项目里甲方直接扔了个“cesium淹没分析.zip”过来压缩包不大但解压、跑通、改到能用的过程差不多花了两个晚上。今天就把这套完整过程拆开聊聊从核心原理到代码实现再到我在实际项目里踩过的坑全部整理出来给同样被淹没分析折磨过的朋友做个参考。这个demo包解决的问题很直接在Cesium三维场景里模拟水位上涨把低洼区域变成动态水面用来辅助洪水风险研判、水库调度展示、城市内涝模拟这类场景。适合水利行业做可视化汇报的工程师也适合刚接触Cesium、想找一套完整功能练手的初学者。1. 淹没分析的核心逻辑与方案选型1.1 淹没分析到底在算什么很多朋友第一次接触淹没分析以为就是个“给地形上色”的活实际上核心问题要复杂一些。本质上是把地形高度场和水位面做对比地形上每一个顶点只要高程低于当前水位就判定为被淹没。把所有被淹没的顶点连起来就得到了淹没区域的边界。这里要注意工程上会区分“有源淹没”和“无源淹没”。有源淹没是洪水从某个溢流点向外扩散需要考虑水流连通性不仅看高程还要考虑地形走向和障碍物阻挡。无源淹没就简单得多只要高程低于水位的点都算淹没适合做静态的风险区划图。甲方给的这种可视化演示绝大多数场景下做无源淹没就够了先把视觉效果跑出来再谈水文模型精度。1.2 三种常见实现方案对比我在写这套功能前特意梳理过目前社区里常用的几种实现方式每种方案都有各自适合的场景。方案实现思路优点缺点适用场景GeoJSON Polygon预先用分析工具算好淹没多边形前端加载展示简单直接性能好无法动态调整水位静态成果展示Primitive Geometry前端实时根据水位面高度裁剪地形动态生成水面Mesh可动态调节交互感强代码量大算法复杂交互式分析系统Entity Material用Entity创建水面多边形通过材质模拟水体效果配合Camera视角开发效率高视觉效果好顶点量大时性能下降快速原型、可视化汇报那个zip包里用的是第三种方案Entity加自定义Material材质配合CallbackProperty动态更新水位高度。这个组合在演示项目里最实用因为需求方永远不满足于“给你一张图”一定会问“水位能调吗”“能加点波纹吗”这套方案刚好都接得住。1.3 为什么选Cesium作为底座当前主流的WebGIS三维引擎里Cesium在淹没分析这个场景有天然优势。它原生支持地形服务加载全球范围的DEM数据可以直接用省去了自己拼地形数据的麻烦。再加上Cesium本身内置了完善的相机系统、拾取机制、坐标系转换工具这些基础能力虽然不起眼但做分析功能时全是刚需。另外一个细节是Cesium的CallbackProperty机制可以做到高度动态变化而不重建Geometry这让水位的流畅上升动画成为了可能。换成Three.js做虽然PBR水体材质更漂亮但要处理全球地形渲染、坐标系投影这些问题工程量翻倍工期不允许。2. zip包解压与工程环境准备2.1 拿到压缩包后的第一件事大部分开发者的习惯是双击解压、打开源码、npm install、跑起来但我建议第一步先看一眼压缩包大小和文件版本信息。我做项目时习惯用7-Zip看一下压缩包内容确认里面有README、文档目录还是纯源码不同的包结构决定了接下来的处理方式。那个“cesium淹没分析.zip”解出来大概170MB结构很典型Build/放的是Cesium的静态资源Source/是业务代码public/放的是terrain地形数据和示例数据。如果是这种结构基本可以直接用Vite或者静态服务器起服务不需要折腾编译。2.2 解压工具选择与中文乱码问题解压Cesium相关资源包时最容易翻车的点有两个一个是文件路径过长导致解压失败另一个是中文文件名乱码。Windows自带的资源管理器在解压深层目录时经常报“文件不存在”或者“无法完成操作”其实就是路径长度超了260字符限制。我个人的建议是用7-Zip解压然后勾选“使用Unicode文件名”可以处理大部分乱码问题。如果解压后遇到HTML文件引用的JS文件缺失先检查路径里有没有中文和空格Cesium的worker脚本对路径比较敏感这类问题排查起来耗时很长。2.3 本地启动环境的正确姿势这个demo包解压后不能直接双击HTML文件运行。Cesium加载本地地形和影像瓦片时浏览器的安全策略会拦截file://协议下对本地资源的访问请求所以必须要起一个本地HTTP服务。我常用的方式是直接用npx serve在项目根目录执行一句话搞定。如果是Vue或React版本直接用npm run dev更简单。这里有个容易被忽略的细节如果页面里用了scene.globe.terrainProvider加载本地地形本地服务的跨域头要配好否则会看到地形加载失败的白屏问题。3. 核心功能拆解与代码实现3.1 动态水面实体的创建淹没分析最核心的就是那一片随水位变化的水面。我解包后看到的实现思路是先读取DEM数据里的最小和最大高程作为水位滑杆的上下限然后创建一个覆盖整个分析区域的动态水面多边形。// 创建动态水面 const waterPolygon viewer.entities.add({ id: flood-water, polygon: { hierarchy: new Cesium.CallbackProperty(() { return new Cesium.PolygonHierarchy(floodBoundary); }, false), material: new Cesium.WaterMaterialProperty({ waterColor: new Cesium.Color(0.2, 0.4, 0.8, 0.8), specularMap: new Cesium.CallbackProperty(() waterLevel, false), normalMap: new Cesium.CallbackProperty(() waterLevel, false) }), height: new Cesium.CallbackProperty(() currentWaterLevel, false), outline: false } });关键就在height这里。水位高度本身不需要做成Geometry重绘而是通过CallbackProperty动态返回这样拖动滑杆时Cesium只更新这一个属性的值不会触发整个多边形的重建性能开销小很多帧率能稳定在50以上。3.2 淹没范围的计算逻辑水面只是视觉效果真正支撑分析的还是淹没范围计算。这套代码里用的是逐顶点高程对比法遍历地形格网把地形高程和当前水位高度做比较高差小于一定阈值的点判定为边界点再把这些边界点连成多边形。实际计算时要注意如果直接用经纬度坐标连多边形在高纬度地区会出现形状扭曲问题。这个demo里的处理方式是把经纬度先转成Web墨卡托投影坐标在平面坐标系里做对比计算算完之后再映射回经纬度。逻辑很清晰代码里加一个isPointUnderwater函数判断每个顶点是否低于水位即可。function isPointUnderwater(point, waterLevel) { // 地形高度通过sampleTerrain获取实际项目中建议预取缓存 const terrainHeight getTerrainHeight(point.latitude, point.longitude); return terrainHeight waterLevel; }3.3 水位拉升动画的实现细节演示场景里一般需要一个自动拉升动画这个包里的做法是控制一个tick变量在viewer.clock.onTick监听器里循环更新水位高度。为了让变化更平滑用了简单的线性插值加上缓动函数整个过程控制在8秒左右看起来比较流畅。3.4 动态材质与光照联动读源码的时候发现这个包还接了Cesium的动态光照系统。它是通过viewer.scene.light拿到当前的光照方向在自定义材质球里把水面高光的方向和太阳方向对齐。这样转场景时水面的高光会随着太阳角度变化比固定高光效果好很多汇报演示时特别出彩。material里用到的specularMap是动态生成的噪声纹理用于模拟水面闪烁。这块我后来在另一个项目里改成预生成的噪点图性能比实时生成好一截加载时间缩短了大概30%。4. 实战过程中的坑与排错记录4.1 水面漂在半空中的问题第一次把整个功能跑通后发现水面没有贴在地形上而是固定悬在某个高度上。排查后发现是height和heightReference的区别没搞清楚。height直接把多边形放到指定海拔高度和地形没有任何关系heightReference: Cesium.HeightReference.CLAMP_TO_GROUND才会让多边形自动贴合地形表面。但这个坑还有另一层如果设置了CLAMP_TO_GROUND就无法用height控制水位了因为高度被地形吸附了。正确的做法是不设置heightReference通过设置height来模拟水位但需要把地形的高程数据采样出来做叠加计算确保水面高度和地形高程在同一个基准面上。这个基准面问题特别隐蔽容易出现海南岛和大陆的图对不齐要和甲方确认用的是同一个高程基准。4.2 压缩包导入失败的EOCD错误开发过程中同事发来更新版压缩包说解压报“invalid zip archive: could not find EOCD”。这个提示一般说明zip文件损坏或者不完整不是解压工具的锅。我和同事在群里来回确认他重新压缩又重传还是报一样的错。后来发现是公司内部通讯软件对大文件做了截断传输文件传了一半就结束。这类问题别在自己电脑上反复折腾第一时间让对方用SHA256校验一下文件完整性能省很多排查时间。另外如果遇到压缩包里的文件解压后乱码尤其是有韩文、日文文件名的情况可以在7-Zip里把默认代码页改成UTF-8。某些压缩工具打包时用了系统本地编码跨语言环境解压就会乱码这个不是文件损坏调整一下配置就能正常显示。4.3 大量边界顶点导致页面卡顿默认的淹没分析区域边界精度很高边界的顶点数量动辄上万个。如果不做抽稀直接把顶点全塞进多边形里页面上滚动鼠标、转动相机时会明显掉帧。后面我是按“每10米一个点”的规则做抽稀视觉误差不大但帧率从15直接飙到55。抽稀的粒度要根据实际地形区域的坡度来调整。地形平坦的区域边界点可以更稀疏地形崎岖的山地区域保留的点要多一些否则淹没边界会看出明显的锯齿感。5. 从淹没分析到三维GIS场景的扩展5.1 同场景下的其他分析功能组合淹没分析做完之后我又陆陆续续在这个Cesium工程里加了雷达扫描效果、可视域分析、天际线分析。这些都是C系三维里常被点名的扩展功能其实底层套路都差不多要么是Geometry叠加材质要么是Shader后处理。雷达扫描效果的实现和淹没分析的水面渲染同源无非是把水面多边形换成以雷达站点为圆心、扫过角度不断变化的扇形区域。可视域分析则需要把视线方向上的地形起伏做射线检测判断哪些区域在视线范围内。5.2 离线地形与本地瓦片的加载很多项目部署在内网环境没法用Cesium官方的在线地形服务和影像服务。这个demo里用的是切好的离线terrain数据用Cesium.createWorldTerrain换成Cesium.TerrainProvider的本地配置就能加载。如果项目里还要叠加MVT格式的矢量数据需要在Cesium里做一层格式转换先用mvt解析库把矢量瓦片解析成GeoJSON再转成Cesium的Entity或Primitive渲染否则浏览器不认识MVT这种二进制格式。5.3 与Three.js共享渲染上下文做高逼真效果做动态水面时如果觉得Cesium自带水材质不够真实可以用Cesium和Three.js共享GL上下文的方式在Cesium场景里叠加Three.js渲染的高精度水面Mesh。但这个方案有个需要注意的地方两个渲染引擎都必须正确设置alpha和depthTest否则会出现水面把地形完全遮挡或者透明穿透的奇怪效果。从实际操作来看如果不是特别追求PBR级别的物理水面效果Cesium自带的WaterMaterialProperty已经足够应付视觉演示和业务交流的需求没有必要为这个引入额外的渲染上下文复杂度。6. 从实际项目中总结的一些经验做完这套淹没分析功能我最大的体会是三维分析功能的门槛不在编写API代码而在于对地形数据、坐标系、渲染时机的理解。比如heightReference那个问题只要搞懂了Cesium里物体到底是一个贴在模型表面的世界坐标点还是一个飞在空中的WGS84坐标点类似的问题都能举一反三。另外在给客户演示之前一定要把地形数据预加载好。Cesium默认是边滚动边加载地形的如果没提前规划飞行路径演示时就会看到地形一片模糊然后逐渐清晰观感不太专业。我的做法是用camera.flyTo先飞一圈让浏览器把沿途地形数据缓存下来再正式进入淹没分析的演示流程。还有一个小技巧值得分享如果需求方想在一个界面里同时看多个水位方案不用做多个Cesium场景可以利用viewer.scene.layers分多个图层管理每个图层承载一个水位方案用layer.show控制显隐。这样切方案不用重新加载数据体验很流畅。做GIS可视化这些年接触的demo包无数能真正用于线上项目的其实不多。但淹没分析这个场景只要把地形数据、水位计算、动态材质这三个核心点吃透是完全可以自己从零写一套的。希望这篇拆解能帮后来者少走点弯路把更多时间花在业务逻辑本身而不是和浏览器渲染性能较劲。本文还有配套的精品资源点击获取