1. 项目概述从“水漫金山”到精准预测最近在做一个智慧城市相关的三维可视化项目客户指着大屏上的数字孪生城市模型提了一个听起来很直观但实现起来颇有门道的要求“能不能模拟一下如果这里下特大暴雨或者水库泄洪水会淹到哪儿水位每涨一米淹没范围怎么变” 这个需求在三维GIS领域就是我们常说的“淹没分析”。而Cesium作为当前Web端三维地球可视化的标杆库自然是实现这个功能的首选平台。简单来说淹没分析的核心就是给定一个区域比如一个山谷、一座城市和一个水位高度动态计算出并可视化所有低于该水位的区域。这听起来像是把地面“切”一刀但实际在三维空间中操作需要考虑地形数据精度、水面效果、性能开销等一系列问题。它不仅是防汛减灾的“数字哨兵”在虚拟仿真、城市规划、环境影响评估等领域都有广泛应用。比如评估新建水库的淹没范围模拟海平面上升对沿海城市的影响或者只是在游戏里做一个洪水特效。Cesium本身并没有提供一个叫Cesium.floodAnalysis()的现成函数这意味着我们需要利用其强大的底层API自己动手“搭积木”。这个过程就像在数字沙盘上玩水你需要一张高精度的地形“沙盘”地形数据一个可以随意升降的“水盆”水面几何体以及一套判断哪里该被“浸湿”的逻辑着色器或几何计算。接下来我就结合自己踩过的坑和最终跑通的方案把这套“玩水”的流程拆解清楚。2. 核心思路与方案选型着色器还是几何体接到需求后我首先思考的是技术路线。在Cesium里实现淹没效果主流思路有两条它们各有优劣直接决定了后续开发的复杂度和最终效果。2.1 方案一基于着色器Shader的像素级模拟这是目前我认为最优雅、性能也相对较好的方案。其核心思想是不真正修改或创建新的几何体而是在渲染阶段通过Cesium的材质Material系统在片元着色器Fragment Shader中对每一个像素进行实时判断。实现原理我们为需要进行分析的区域创建一个实体Primitive比如一个矩形或多边形。然后为这个实体赋予一个自定义的材质。在这个材质的着色器代码中我们获取当前像素在世界坐标系中的高程值通过采样地形纹理或深度计算同时传入一个由JavaScript控制的“水位高度”全局变量。在片元着色器里只需一个简单的判断if (pixelElevation waterLevel) { gl_FragColor waterColor; } else { gl_FragColor originalColor; }。这样低于水位的区域就会显示为水的颜色高于水位的区域则保持原貌。优势动态高效水位高度的变化只需更新一个Uniform变量渲染引擎会自动重绘动态效果极其流畅。效果丰富可以在着色器里轻松添加水面波纹、镜面反射、边缘渐变等高级特效视觉效果出众。无几何体负担不创建新的三角面对内存和CPU几何计算的压力小特别适合大范围分析。劣势精度依赖渲染分析精度与地形渲染的精度直接挂钩在相机拉得很远时可能会因为地形LOD多细节层次导致边缘不够锐利。着色器门槛需要一定的WebGL和GLSL知识对初学者不友好。难以获取精确数据它主要服务于可视化要精确获取淹没面积、体积等量化数据需要额外的计算模块。2.2 方案二基于几何体的动态裁剪与生成这是一种更“实在”的方法。核心是使用Cesium的ClippingPlane裁剪平面或者动态生成一个代表水面的平面几何体。ClippingPlane方案可以为地形瓦片或3D Tiles模型设置一个水平的裁剪平面。平面以下的部分被裁剪隐藏平面以上的部分保留。通过不断调整裁剪平面的高度就能模拟水位上涨露出被“淹没”的地形断面。这个断面通常颜色较深可以模拟水下效果。动态几何体方案根据水位高度动态生成一个覆盖分析区域的、处于同一水平高度的多边形水面并将其作为Primitive添加到场景中。同时为了看到水面下的地形可能需要调整地形或模型的透明度。优势概念直观裁剪平面非常符合“水位线”的物理直觉。易于量化结合Cesium的SampledPositionProperty等工具可以相对容易地计算出被裁剪或覆盖区域的面积。兼容性好对3D Tiles建筑模型等也能进行裁剪实现建筑下半部分被淹没的效果。劣势性能开销动态创建几何体或频繁更新裁剪参数在数据量大时可能引起卡顿。效果单一水面通常是一个纯色或简单贴图的平面想要实现逼真的水波动态效果比较困难。边缘处理裁剪边缘可能显得生硬水面与地形交界处的融合需要额外处理。我的选择与考量经过权衡我最终选择了**方案一着色器方案**作为主线进行讲解。原因在于当前项目更强调实时、交互式的动态可视化效果并且分析范围可能很大。着色器方案在性能和视觉效果上取得了更好的平衡。当然我也会在后续适当补充方案二中的关键技巧因为在实际项目中根据具体需求混合使用这两种技术也是常事。例如用着色器做主要的地形淹没可视化同时用几何体方案在特定位置生成一个高质量的水面反射平面。3. 关键技术与环境准备选定了主攻方向接下来就要准备“施工材料”和“工具”。淹没分析不是无源之水它的准确性严重依赖输入数据的质量。3.1 地形数据源分析的基石Cesium支持多种地形数据源你的选择直接影响分析精度和效果。Cesium Ion在线地形最快捷的方式。Cesium Ion提供了全球范围的多种精度地形如Cesium World Terrain。使用它你几乎不需要操心数据托管。在代码中只需创建CesiumTerrainProvider并指定Ion资产ID即可。这对于快速原型开发和全球范围的低精度分析非常友好。viewer.terrainProvider new Cesium.CesiumTerrainProvider({ url: Cesium.IonResource.fromAssetId(1), // 1是Cesium World Terrain的默认ID requestWaterMask: true, // 请求水掩膜对真实感很重要 requestVertexNormals: true // 请求顶点法线用于光照 });自定义高程切片Quantized-Mesh当需要分析特定高精度区域如某个水利工程周边时你必须使用本地或自托管的地形切片。常用的工具如Cesium Terrain Builder、GDAL可以将DEM数字高程模型数据转换为Cesium支持的.terrain格式。这一步的关键在于投影转换确保你的DEM数据坐标系统一通常转换为WGS84地理坐标系。精度控制切片时的层级Level决定了地形细节。层级越高数据量越大但精度也越高。需要权衡。边界处理确保地形服务的范围完全覆盖你的分析区域。实操心得起步阶段强烈建议先用Cesium Ion的地形把核心分析逻辑跑通。等到需要部署到内网或对精度有特殊要求时再啃自定义地形这块“硬骨头”。因为地形服务的搭建和调试本身就是一个不小的项目。3.2 构建着色器材质核心引擎这是实现方案一的“心脏”。我们需要创建一个自定义的Material。下面是一个最基础的淹没分析着色器材质实现1. 材质定义// 定义着色器源码 const floodAnalysisFS uniform vec4 waterColor; // 水面颜色如 vec4(0.0, 0.3, 0.6, 0.8) uniform float waterLevel; // 水位高度米 uniform float glowWidth; // 淹没边缘发光宽度 czm_material czm_getMaterial(czm_materialInput materialInput) { czm_material material czm_getDefaultMaterial(materialInput); // 获取当前片元的世界坐标高度。这是关键 // 注意这里的高度是椭球高度ellipsoid height。 float fragmentHeight materialInput.position.z; // 在3D Tiles或Primitive的模型坐标系中可能需要转换 // 核心判断逻辑 if (fragmentHeight waterLevel) { // 被淹没区域显示水色 material.diffuse waterColor.rgb; material.alpha waterColor.a; // 可选添加边缘发光效果水位线附近 float distanceToWaterLevel waterLevel - fragmentHeight; if (distanceToWaterLevel glowWidth) { float glowFactor distanceToWaterLevel / glowWidth; material.emission vec3(0.5, 0.7, 1.0) * (1.0 - glowFactor); // 模拟浅水发光 } } else { // 未被淹没区域可以显示为其他颜色或保持地形本身纹理 // 这里我们简单设置为灰色半透明以便看清底下地形 material.diffuse vec3(0.7, 0.7, 0.7); material.alpha 0.3; } return material; } ; // 创建自定义材质 const floodMaterial new Cesium.Material({ fabric: { type: FloodAnalysis, uniforms: { waterColor: new Cesium.Color(0.0, 0.3, 0.6, 0.7), waterLevel: 50.0, // 初始水位50米 glowWidth: 5.0 // 边缘发光宽度5米 }, source: floodAnalysisFS }, translucent: true // 材质是半透明的 });2. 关键点解析materialInput.position这个变量包含了当前片元在 primitive 局部坐标系中的位置。其z值通常对应高度。但这里有一个巨大的坑这个高度是相对于你创建的Primitive的坐标系原点而不是绝对的世界高程。如果你的Primitive放置的位置和地形不完全匹配分析就会错位。高度转换为了进行准确的世界坐标判断更可靠的做法是在着色器中利用czm_inverseModelView等矩阵将片元位置转换到世界坐标然后通过czm_ellipsoid获取精确的椭球面高度。但这部分计算较复杂对性能有影响。一个折中的实践是在JavaScript端将你的分析区域Primitive的position设置为分析区域中心点并确保其height属性为0贴地。这样Primitive的局部坐标系z轴就大致对应于该点的相对高程变化。对于小范围分析这通常可以接受。3.3 创建分析区域实体有了材质我们需要一个“画布”来应用它。通常我们会用一个多边形PolygonGeometry来圈定分析范围。// 假设分析区域是上海浦东的一片矩形区域 const rectangle Cesium.Rectangle.fromDegrees(121.4, 31.1, 121.6, 31.3); // 创建多边形几何实例 const polygonInstance new Cesium.GeometryInstance({ geometry: new Cesium.PolygonGeometry({ polygonHierarchy: new Cesium.PolygonHierarchy( Cesium.Rectangle.toCartesianArray(rectangle) ), height: 0, // 几何体高度设为0使其贴在地形上 extrudedHeight: 1000, // 挤压一个很高的高度确保覆盖整个分析深度范围 vertexFormat: Cesium.PerInstanceColorAppearance.VERTEX_FORMAT }), id: floodAnalysisArea // 赋予ID便于后续操作 }); // 创建Primitive并应用我们的自定义材质 const floodAnalysisPrimitive viewer.scene.primitives.add(new Cesium.Primitive({ geometryInstances: polygonInstance, appearance: new Cesium.PerInstanceColorAppearance({ flat: true, // 平坦着色避免地形起伏影响颜色插值 translucent: true }), asynchronous: false // 同步加载确保立即显示 })); // 关键一步将自定义材质赋给Primitive floodAnalysisPrimitive.appearance.material floodMaterial;注意事项这里将多边形extrudedHeight设得很大1000米是为了确保在着色器里无论水位多高我们创建的这个“柱子”都能覆盖到。着色器会在每个像素上判断其在这个“柱子”内的实际高度是否低于水位。4. 动态交互与水位控制静态的淹没显示意义不大我们需要让水位“动”起来实现交互式模拟。4.1 水位参数动态更新通过修改材质uniform变量可以实时更新水位。我们可以将其绑定到一个滑块Slider上。// HTML中有一个id为waterLevelSlider的range input const slider document.getElementById(waterLevelSlider); const waterLevelDisplay document.getElementById(waterLevelValue); slider.addEventListener(input, function(e) { const newWaterLevel parseFloat(e.target.value); waterLevelDisplay.textContent newWaterLevel.toFixed(1) 米; // 更新材质uniform变量这是动态效果的关键。 if (floodMaterial) { floodMaterial.uniforms.waterLevel newWaterLevel; } });4.2 淹没过程动画模拟为了实现自动的“水位上涨”动画我们可以使用Cesium的JulianDate和SampledProperty。// 创建一个水位随时间变化的属性 const waterLevelProperty new Cesium.SampledProperty(Number); const startTime Cesium.JulianDate.now(); const endTime Cesium.JulianDate.addSeconds(startTime, 30, new Cesium.JulianDate()); // 30秒动画 // 在时间线上添加采样点模拟从0米涨到100米 waterLevelProperty.addSample(startTime, 0.0); waterLevelProperty.addSample(endTime, 100.0); // 将材质的uniform变量绑定到这个动态属性 floodMaterial.uniforms.waterLevel waterLevelProperty; // 设置时钟控制动画播放 viewer.clock.startTime startTime.clone(); viewer.clock.stopTime endTime.clone(); viewer.clock.currentTime startTime.clone(); viewer.clock.clockRange Cesium.ClockRange.LOOP_STOP; // 播放到结尾停止 viewer.clock.multiplier 1.0; // 时间流逝速度 viewer.timeline.zoomTo(startTime, endTime); // 时间轴缩放至动画范围这样当你点击播放时间轴水位就会自动从0米平滑上涨到100米淹没区域随之动态变化形成非常直观的模拟动画。5. 效果增强与量化分析基础功能实现后我们可以从视觉和数据分析两个层面进行增强。5.1 视觉增强让水面更真实纯色的水面很假。我们可以在着色器中加入一些简单的效果水面波纹使用噪声纹理Noise Texture或程序化噪声函数如simplex noise扰动水面颜色或法线模拟波纹。这需要在着色器源码中添加噪声计算和采样逻辑。边缘渐变如上文代码所示在靠近水位线的地方通过计算与水位线的距离混合一个发光的颜色让淹没边界更柔和、更有科技感。镜面反射这是一个高级话题。一种取巧的方法是在着色器中根据视角和法线可以简单假设水面法线朝上计算一个菲涅尔效应Fresnel Effect让掠射视角的水面更亮模拟反射。5.2 量化分析计算淹没面积与体积可视化之外客户往往需要具体的数字。Cesium没有直接提供计算任意多边形内低于某一高度的地形面积和体积的API。我们需要自己设计算法。一个可行的思路是采样在分析区域多边形内按照一定分辨率如10米网格生成一系列采样点。获取高程使用Cesium.sampleTerrain函数批量获取这些采样点的精确地形高程。计算面积对于每个网格单元由四个采样点构成如果其平均高程低于水位则将该单元的面积累加到总淹没面积中。网格面积可以根据经纬度差近似计算在中小范围可近似为平面。体积对于每个低于水位的采样点计算水位高程与该点地形高程的差值即水深乘以该点所代表的“面积权重”如网格面积的四分之一将所有点的体积累加。优化全区域高精度采样计算量巨大。可以采用自适应采样地形起伏大的地方密平坦的地方疏或使用Web Worker在后台线程进行计算避免阻塞主线程导致页面卡顿。实操心得量化计算是性能瓶颈。在实际项目中我通常会先做一个快速的低精度估算比如用100米网格给用户即时反馈然后提供一个“精确计算”按钮让用户选择是否启动更耗时的精细计算。同时一定要做好加载状态提示。6. 常见问题与性能优化实录在实际开发中我遇到了不少坑这里记录几个典型问题及其解决方案。6.1 问题一淹没区域边缘闪烁或抖动现象当相机移动或水位接近地形高度时淹没边界线会出现明显的闪烁Z-fighting。原因这是经典的深度冲突Z-fighting。我们的分析水面几何体或着色器处理的片元与地形表面处于几乎相同的深度由于深度缓冲的精度限制GPU无法确定谁在前谁在后。解决方案深度偏移Depth Offset这是最有效的办法。在创建Primitive时设置appearance.renderState.depthTest和polygonOffset。appearance: new Cesium.PerInstanceColorAppearance({ // ... 其他配置 renderState: { depthTest: { enabled: true }, polygonOffset: { enabled: true, factor: -1.0, // 负值将几何体稍微“推远” units: -1.0 } } })通过微调factor和units值可以让水面渲染在离相机稍远一点的位置从而避免与地形表面深度值冲突。着色器微调在着色器中可以对水位判断加入一个微小的容差epsilon例如if (fragmentHeight waterLevel - 0.01)避免在临界点反复横跳。6.2 问题二性能瓶颈大范围分析时卡顿现象当分析区域覆盖整个城市甚至更大范围时帧率FPS显著下降。原因着色器虽然高效但覆盖整个屏幕的巨大Primitive依然会产生海量的片元着色器调用。此外如果量化分析采用高密度采样CPU计算也会成为瓶颈。优化策略分块与LOD将大的分析区域划分为多个较小的区块Tile。根据相机距离动态调整每个区块的渲染精度例如远处的区块使用更简化的几何体或更低分辨率的着色计算。这需要较复杂的调度逻辑。降低着色器复杂度简化着色器中的计算特别是去除昂贵的噪声函数、反射计算等。在交互调整水位时使用一个快速、低效果的着色器在停止交互后再切换为高质量着色器。异步与Worker将量化分析的面积体积计算全部丢给Web Worker确保UI线程流畅。地形采样 (sampleTerrain) 也支持Promise要善用异步避免阻塞。视图裁剪只对视锥体Frustum内的分析区域进行高精度渲染和计算。Cesium的Primitive本身有视锥体裁剪但要确保你的分析区域几何体没有不必要的部分。6.3 问题三与3D Tiles建筑模型的交互需求不仅要淹没地形还要模拟水淹到建筑物一楼、二楼的效果。挑战3D Tiles模型是独立的渲染单元其高度信息封装在模型内部无法像地形一样通过全局高度简单判断。混合方案建筑单独处理为重要的建筑模型单独创建包围盒Bounding Box并计算其底部高程。在水位变化时通过JavaScript判断if (waterLevel buildingBaseHeight) { // 建筑被淹 }。然后通过改变建筑模型的样式如颜色变深、添加水面材质来模拟淹没效果。可以使用Cesium的Cesium3DTileStyle来实现动态着色。裁剪平面这正是方案二的用武之地。对3D Tiles图层启用ClippingPlane设置一个水平裁剪平面平面以下的部分不渲染就能直观看到建筑被“切断”的效果。这需要将3D Tiles的clippingPlanes属性关联到一个可动态更新的ClippingPlaneCollection。const clippingPlanes new Cesium.ClippingPlaneCollection({ planes: [ new Cesium.ClippingPlane(new Cesium.Cartesian3(0.0, 0.0, 1.0), 0.0) // 法线朝上平面高度为0 ], edgeWidth: 1.0, // 裁剪边缘宽度可模拟水线 edgeColor: Cesium.Color.BLUE // 裁剪边缘颜色 }); tileset.clippingPlanes clippingPlanes; // 动态更新平面高度 clippingPlanes.get(0).distance -waterLevel; // 注意距离符号这种“地形用着色器建筑用裁剪”的混合方案能较好地平衡效果与性能实现更真实的城市级淹没模拟。最后我想说的是Cesium的淹没分析实现就像在数字世界中进行水利工程实验每一步都需要精心设计和反复调试。从选择合适的地形数据到编写高效的着色器再到处理各种视觉和性能上的“暗礁”整个过程充满了挑战但当看到水位线随着滑块平滑上升城市低洼地带被逐渐“淹没”时那种将抽象数据转化为直观洞察的成就感是驱动我们不断深入探索的最佳动力。希望这篇结合了原理、代码和踩坑经验的总结能为你点亮一盏灯。在实际操作中多利用Cesium Sandcastle上的示例进行修改和测试那是学习Cesium最快的方式。