1. 从“看”到“算”为什么我们需要淹没分析在三维地理信息领域CesiumJS 凭借其强大的三维地球渲染能力早已成为开发者构建数字孪生、智慧城市、应急指挥等系统的首选框架。我们用它加载倾斜摄影模型、展示动态路径、模拟日照阴影这些都属于“可视化”的范畴。但三维的价值远不止于“看”更在于“算”和“析”。淹没分析就是这种从“看”到“算”的典型跨越。想象一下这个场景你负责一个沿河城市的防汛系统。当气象部门发布暴雨红色预警预测上游水库将泄洪下游河道水位可能上涨5米时决策者最关心的问题是什么绝不是“5米高的水墙长什么样”而是“这5米的水会淹掉哪些街道、哪些小区、哪些重要设施预计有多少人口需要转移直接经济损失大概是多少” 这些问题就是淹没分析要回答的核心。所以淹没分析的本质是基于数字高程模型DEM或地形数据模拟水体如洪水、海水在达到某一特定水位高度时其淹没的范围、深度和体积。它不是一个简单的“贴图”效果而是一个基于空间数据的三维空间计算与模拟过程。在Cesium中实现它意味着我们将这个三维计算引擎从一个“华丽的展示橱窗”升级为一个“专业的分析沙盘”。我见过很多项目花了大价钱做了精美的三维场景但到了需要做应急推演或规划分析时却只能干瞪眼或者退回到二维GIS软件中去计算再费力地把结果“贴”回三维场景流程割裂体验糟糕。而直接在Cesium中实现淹没分析则能实现“分析即所得”让决策者在三维场景中直观、交互地看到分析结果极大地提升了系统的实用性和决策效率。2. 核心原理拆解水位面与地形的布尔运算要实现淹没分析我们首先要理解其最基础的数学模型。抛开复杂的流体动力学模拟那是专业水文模型的事对于大多数应急和规划场景我们常用的是静态淹没分析或水平面淹没分析。其核心思想非常简单可以概括为一句计算一个水平面与地形表面相交后地形表面低于该水平面的区域。这个过程在计算机图形学和GIS中可以看作一次三维布尔运算中的“差集”计算定义淹没体一个无限延伸的水平面水位面与其上方无限空间构成的半空间可以想象为水位面以上的“空气”部分被剔除我们关注的是水位面以下的“水”的部分。定义地形体由地形高程数据构成的三维表面及其下方的实体。执行布尔运算计算“地形体”与“淹没体水位面以下部分”的交集。这个交集区域就是被淹没的区域。在Cesium中我们没有直接的布尔运算API但我们可以通过一系列已有的能力来“拼凑”出这个效果。关键在于理解Cesium渲染管线的两个核心地形Terrain和影像Imagery以及如何创造性地使用Primitive API或3D Tiles的样式化Styling功能。地形CesiumTerrainProvider提供了地表的高程信息它是我们判断某个点是否被淹的“标尺”。自定义绘制则是我们用来“上色”的工具告诉Cesium“请把所有海拔低于X米的地方用某种颜色比如蓝色绘制出来”。因此技术实现路径就清晰了。主流方法有两条基于地形瓦片与着色器Shader的动态绘制这是性能较高、效果较动态的方法。通过编写自定义的GLSL着色器在渲染地形时实时判断每个像素对应一个地理坐标和高程的高度是否低于设定水位如果是则输出水的颜色和材质。基于几何体Primitive的静态绘制这种方法先生成一个代表淹没区域的三角网几何体然后将其作为Primitive添加到场景中。优点是控制灵活可以附加更多属性如淹没深度缺点是在地形复杂区域生成几何体计算量较大。接下来我们将深入最实用、性能也相对更好的着色器方案。3. 实战使用自定义地形着色器实现动态淹没这是目前Cesium社区最常用的实现方式它直接在地形渲染阶段介入效率高能实时响应水位值的变化。其核心是为地形材质Material编写一个自定义的着色器Shader。3.1 环境准备与核心思路首先你需要一个支持高程细节的Cesium地形数据源比如Cesium Ion提供的Quantized-Mesh地形或者自己发布的类似格式地形。假设我们已经有了一个viewer实例并加载了地形。我们的目标是创建一个材质当地形海拔低于某个waterHeight变量时显示为“水”高于时显示为原始地形纹理或另一种材质。这里的关键是在着色器中我们能获取到当前渲染片元像素的世界坐标。通过Cesium提供的内置函数我们可以将其转换为地理坐标经纬度和海拔高度绝对高度。这个海拔高度就是与waterHeight比较的依据。3.2 着色器代码实现详解我们将创建一个CustomTerrainMaterial。下面是一个高度简化的GLSL代码框架用于说明原理// 自定义地形材质着色器 (Fragment Shader 部分) czm_material czm_getMaterial(czm_materialInput materialInput) { czm_material material czm_getDefaultMaterial(materialInput); // 获取当前片元的世界坐标 vec3 worldPosition materialInput.positionWC; // 将世界坐标转换为地理坐标弧度制 vec4 lonLatAlt czm_inverseModelViewProjection * vec4(worldPosition, 1.0); // 此处简化实际中更精确的获取海拔方式是通过czm_sampleHeight或纹理采样 // 假设我们通过uniform传入的地形高度图texture来获取精确高度 float terrainHeight texture2D(terrainHeightTexture, materialInput.st).r * heightRange minHeight; // 从uniform变量获取全局水位高度 float waterLevel u_waterHeight; // 判断是否淹没 if (terrainHeight waterLevel) { // 淹没区域计算淹没深度用于颜色渐变 float depth (waterLevel - terrainHeight) / u_maxDepth; depth clamp(depth, 0.0, 1.0); // 水的颜色可以根据深度渐变 vec3 waterColor mix(u_shallowWaterColor, u_deepWaterColor, depth); material.diffuse waterColor.rgb; material.alpha 0.8; // 水的透明度 // 为水面增加一些镜面高光模拟反光 material.specular 0.5; material.shininess 10.0; } else { // 非淹没区域使用原始地形影像或默认材质 // 这里可以采样原始地形影像纹理 material.diffuse texture2D(u_originalImagery, materialInput.st).rgb; } return material; }代码关键点解析u_waterHeight这是一个由JavaScript端传入的全局统一变量uniform代表当前设定的水位海拔。改变它淹没范围就会实时变化。terrainHeight这是当前像素点对应的实际地形海拔。这里是最容易踩坑的地方。materialInput.positionWC的世界坐标y分量并不是海拔。必须通过坐标转换或采样专门的地形高度纹理来获取精确值。对于Quantized-Mesh地形Cesium在着色器中提供了czm_sampleHeight等方法但使用起来需要处理相对坐标。更通用的做法是在服务端预处理一张与地形瓦片配套的高度图纹理RGB编码高度值在着色器中采样解码。深度渐变通过(waterLevel - terrainHeight)计算淹没深度并归一化到0-1范围用于混合浅水色和深水色让视觉效果更有层次感而不是死板的一块蓝色。材质属性设置了水的alpha透明度、specular镜面反射强度和shininess高光尺寸这些都能极大地增强水的真实感。3.3 JavaScript端的集成与控制在JavaScript端我们需要创建这个自定义材质并将其应用到Cesium的地形上。这里不能直接修改默认地形材质而是需要利用Cesium.Material系统或CustomShaderAPICesium 1.104 推荐。以下使用较新的CustomShader方式// 1. 定义自定义着色器 const customShader new Cesium.CustomShader({ uniforms: { u_waterHeight: { value: 50.0, // 初始水位50米 type: Cesium.UniformType.FLOAT }, u_shallowWaterColor: { value: new Cesium.Color(0.2, 0.5, 0.8, 1.0), // 浅蓝色 type: Cesium.UniformType.VEC4 }, u_deepWaterColor: { value: new Cesium.Color(0.0, 0.2, 0.5, 1.0), // 深蓝色 type: Cesium.UniformType.VEC4 }, u_maxDepth: { value: 20.0, // 最大显示深度用于颜色归一化 type: Cesium.UniformType.FLOAT } }, fragmentShaderText: // 这里填入上面编写的Fragment Shader代码 void fragmentMain(FragmentInput fsInput, inout czm_modelMaterial material) { // 获取高程这里需要根据实际数据源调整获取方式 // 假设我们通过属性传递了高度或者从纹理采样 float height fsInput.attributes.height; // 示例需要地形提供该属性 if (height u_waterHeight) { float depth (u_waterHeight - height) / u_maxDepth; depth clamp(depth, 0.0, 1.0); vec4 waterColor mix(u_shallowWaterColor, u_deepWaterColor, depth); material.diffuse waterColor.rgb; material.alpha waterColor.a; } // 否则使用默认材质 } }); // 2. 获取地形图层的原型对象Primitive并应用自定义着色器 // 注意此方法需要地形图层支持CustomShader且能获取到其primitive实例。 // 对于Cesium全球地形操作较为复杂通常需要自己创建TerrainProvider并包装。 // 更常见的做法是对3D Tiles建筑模型或局部高精度地形做淹没分析。 // 3. 动态更新水位实现动画效果 function animateWaterRise(targetHeight, duration) { const startHeight customShader.uniforms.u_waterHeight.value; const startTime Cesium.JulianDate.now(); const stopTime Cesium.JulianDate.addSeconds(startTime, duration, new Cesium.JulianDate()); viewer.clock.currentTime startTime; viewer.clock.stopTime stopTime; viewer.clock.clockRange Cesium.ClockRange.CLAMPED; viewer.scene.postRender.addEventListener(function() { const currentTime viewer.clock.currentTime; const elapsed Cesium.JulianDate.secondsDifference(currentTime, startTime); const progress Cesium.Math.clamp(elapsed / duration, 0.0, 1.0); const currentWaterHeight startHeight (targetHeight - startHeight) * progress; customShader.uniforms.u_waterHeight.value currentWaterHeight; if (progress 1.0) { viewer.scene.postRender.removeEventListener(this); // 移除监听 } }); } // 调用示例在10秒内水位从50米上升到80米 animateWaterRise(80.0, 10.0);实操心得与巨坑预警地形高度获取是最大难点全局地形Cesium World Terrain的顶点属性中不直接包含绝对海拔。上述代码中的fsInput.attributes.height只是一个理想化示例。实践中你可能需要预处理高度纹理在服务端为地形区域生成一张高度图在着色器中采样。这需要对齐瓦片和纹理的坐标体系。使用czm_sampleHeight在自定义着色器中这是一个未公开但可用的函数用于从地形深度缓存中采样高度。但它操作的是相机空间坐标需要复杂的坐标转换且不同Cesium版本可能不稳定。降级方案如果只针对小范围、高精度地形可以考虑用Cesium.sampleTerrainMostDetailed在CPU端预计算区域高度然后生成一个代表水面的三角网Cesium.PolygonGeometryCesium.HeightReference.CLAMP_TO_GROUND但这失去了逐像素的精度和深度渐变。性能考量片段着色器中的条件判断if语句和纹理采样对性能有影响。确保你的高度图纹理尺寸合理并且只在需要分析的区域内启用此自定义材质。CustomShader兼容性CustomShaderAPI主要针对Cesium3DTileset和Model设计对原生Globe地形的支持有限且复杂。对于全球地形更成熟的做法是使用早期的Cesium.Material系统通过terrainProvider的requestTileGeometry回调进行底层注入但这需要更深的图形学知识。4. 备选方案基于几何体与多边形填充的静态绘制当自定义着色器方案因地形数据源限制而走不通时或者你需要生成的淹没区域作为一个独立的、可交互的实体对象时基于几何体的方案是一个可靠的备选。其思路是在CPU端计算淹没范围生成一个三角网然后将其作为水面渲染。4.1 计算淹没区域轮廓这一步是算法的核心。给定一个水平面高度H和一片地形区域我们需要找出所有地形点中高程值小于H的连续区域。这通常需要采样地形网格在目标区域一个矩形或多边形内按一定分辨率如50米网格采样获取每个网格点的高程。可以使用Cesium.sampleTerrainMostDetailed。二值化将采样点分为两类高程 H淹没点和高程 H非淹没点。轮廓提取使用图像处理中的算法如Marching Squares算法在二维网格上找出淹没区与非淹没区的边界线。这一步计算出的边界是一系列的点序列。构建多边形将这些边界点连接起来形成一个或多个闭合多边形可能包含岛洞。这就是淹没范围在二维地图上的投影。// 伪代码示例展示思路 async function calculateInundationPolygon(rectangle, waterHeight) { // 1. 定义采样网格 const samplingStep 0.001; // 经纬度步长约100米 const positions []; for (let lon rectangle.west; lon rectangle.east; lon samplingStep) { for (let lat rectangle.south; lat rectangle.north; lat samplingStep) { positions.push(Cesium.Cartographic.fromDegrees(lon, lat)); } } // 2. 采样地形高程 const sampledPositions await Cesium.sampleTerrainMostDetailed(terrainProvider, positions); // 3. 二值化并生成二维高度矩阵 // ... 此处省略将sampledPositions转换为二维矩阵matrix的代码 const rows /* 行数 */; const cols /* 列数 */; const heightMatrix /* 二维数组 */; const binaryMatrix heightMatrix.map(row row.map(h h waterHeight ? 1 : 0)); // 4. 使用Marching Squares算法提取轮廓点需要第三方库或自己实现 const contourPoints marchingSquares(binaryMatrix, rectangle, samplingStep); // 5. 返回轮廓点Cartographic数组 return contourPoints; }4.2 生成水面几何体并渲染得到二维多边形轮廓后我们需要将其“贴”到三维地形上形成一个水面。function createWaterSurfacePolygon(hierarchy, waterHeight) { // hierarchy 是由上一步计算出的轮廓点构成的 PolygonHierarchy const waterPolygon viewer.entities.add({ polygon: { hierarchy: hierarchy, // 关键高度模式设为绝对高度并指定水位值 height: waterHeight, extrudedHeight: waterHeight, // 与height相同表示一个平面 heightReference: Cesium.HeightReference.NONE, // 使用绝对高度 material: new Cesium.ColorMaterialProperty( Cesium.Color.fromBytes(0, 100, 255, 150) // 半透明蓝色 ), // 可以添加水面波纹材质 // material: new Cesium.WaterMaterial({ // baseWaterColor: new Cesium.Color(0.2, 0.5, 0.8, 0.8), // specularMap: path/to/waterNormals.jpg, // frequency: 1000.0 // }), outline: false } }); return waterPolygon; }这个方案的优缺点非常明显优点实现思路直观不依赖复杂的着色器编程。生成的水面是一个独立的Entity或Primitive易于控制显示/隐藏、修改颜色、添加事件。可以方便地计算淹没面积和体积基于多边形和平均水深。缺点性能瓶颈在CPU采样和轮廓提取计算量大分辨率越高越慢不适合实时交互调整水位。“硬边”问题水面是一个平整的平面与倾斜的地形相交处会有一条明显的“硬边”看起来不自然不像水与岸坡的渐变浸润。精度与效率的权衡采样分辨率低边界锯齿状严重分辨率高计算耗时剧增。注意对于小范围、精度要求不高的场景或者作为着色器方案生效前的快速原型这个方案是可行的。但在大规模、需要动态效果的应用中着色器方案是更优的选择。5. 性能优化与效果增强技巧无论采用哪种方案在真实项目中应用淹没分析都必须考虑性能和视觉效果。5.1 分级与LOD细节层次策略淹没分析不需要在全屏范围内都以最高精度运行。视锥体裁剪只对当前相机可见区域进行高精度计算或渲染。Cesium内置了视锥体裁剪但对于自定义的CPU端计算需要手动判断。距离分级根据水面到相机的距离动态调整分析精度或渲染质量。远距离使用低分辨率采样或简化的水面几何体甚至只用纯色块。中距离使用中等精度开启简单的深度颜色渐变。近距离启用最高精度计算并添加水面法线贴图模拟波纹、镜面反射、甚至焦散Caustics等高级效果。基于海拔的分级对于大规模洪水模拟远离重点城镇的山区、农田可以使用更粗糙的计算。5.2 水面材质的真实感提升一潭死水的蓝色平面非常假。要让水面“活”起来需要材质上下功夫。法线贴图Normal Map这是模拟水面波纹成本最低、效果最显著的方法。使用一张水的法线贴图在着色器中扰动水面法线结合光照计算就能产生动态波光粼粼的效果。Cesium.WaterMaterial内部就使用了这个技术。镜面反射Specular根据水面法线和视线方向计算高光模拟阳光或灯光的反射亮点。菲涅尔效应Fresnel Effect视线与水面夹角越小掠射角反射越强夹角越大垂直看透射越强。这可以通过一个简单的mix函数结合反射颜色和水的底色来实现。动态动画让法线贴图或某些参数随时间变化产生水流动画。在着色器中传入一个时间uniform用于偏移纹理坐标。// 在片段着色器中添加简单动画和菲涅尔效应 uniform float u_time; uniform sampler2D u_normalMap; vec3 normal texture2D(u_normalMap, materialInput.st vec2(u_time * 0.05, 0.0)).xyz; normal normalize(normal * 2.0 - 1.0); // 从纹理[0,1]转换到法线[-1,1] vec3 viewDir normalize(czm_eyePosition - worldPosition); float fresnel pow(1.0 - max(dot(normal, viewDir), 0.0), 5.0); vec3 color mix(waterBaseColor, waterReflectionColor, fresnel); material.normal normal; // 应用扰动后的法线 material.diffuse color;5.3 与场景元素的交互淹没分析不能孤立存在它需要与场景中的其他元素互动。建筑模型的裁剪当水位上升建筑应该有一部分浸入水中。对于3D Tiles建筑可以通过Cesium3DTileStyle来实现根据建筑底部海拔与水位的关系动态设置color或show属性。更精细的做法是在着色器中对建筑模型进行像素级裁剪。动态标注与信息提示当鼠标悬停在水面上时可以实时显示该点的淹没深度。这需要在Scene.pick事件中获取点击位置的世界坐标然后反算出该点的地形海拔再与当前水位比较计算深度。等高线叠加将水位线等高线叠加显示在地形上可以更清晰地展示淹没边界。这可以通过在指定高度生成一个Polyline并clampToGround来实现。6. 常见问题排查与实战避坑指南在实际开发中你会遇到各种各样奇怪的问题。下面是我踩过的一些坑和解决方案。6.1 水位变化时淹没边缘闪烁或抖动问题描述当动态改变u_waterHeight时水面与陆地交界处出现明显的像素闪烁或抖动。根因分析这是图形学中经典的Z-fighting问题。水面几何体或着色的水面像素与地形几何体在深度Z值上过于接近由于深度缓冲区的精度限制GPU无法确定谁在前谁在后导致渲染顺序随机。解决方案深度偏移Depth Offset在渲染水面时施加一个微小的深度偏移强制让水面绘制在地形“之上”一点点。在Primitive方案中可以设置appearance的depthTest相关属性。在着色器方案中可以修改gl_FragDepth需谨慎会影响性能。提高深度缓冲区精度检查Cesium Viewer的深度缓冲区设置。但通常效果有限。避免绝对共面在几何体方案中不要让水面的height和地形的clampToGround高度完全一致。可以将水面高度设置为waterHeight 0.01增加一个微小偏移。6.2 自定义着色器在部分地形瓦片上不生效问题描述只有部分区域的地形显示了淹没效果其他区域还是原始地形。排查过程检查uniform变量是否成功传入。确保customShader.uniforms.u_waterHeight.value在更新。检查地形Provider。不是所有的TerrainProvider都支持自定义材质或CustomShader。Cesium自带的EllipsoidTerrainProvider平地就不支持复杂的材质。必须使用CesiumTerrainProviderQuantized-Mesh格式。最关键的一点Cesium的地形渲染是分块的。你的着色器可能只应用到了当前视锥体内某几个特定的地形瓦片上。确保你的材质应用逻辑覆盖了所有需要的地形瓦片实例。这通常需要更底层的操作比如修改Globe的_surface的_tileProvider的材质生成函数。6.3 淹没分析范围异常覆盖了整个屏幕或完全消失问题描述设置水位后要么整个地球都变蓝了要么一点效果都没有。排查步骤检查高度坐标系这是最常见的原因。确保你比较的“水位高度”和“地形高度”是在同一个坐标系下。Cesium中常用的有椭球高度Ellipsoid Height相对于WGS84椭球面的高度。Cartographic.height属性就是此高度。GPS数据通常用这个。海拔高度Altitude相对于大地水准面如EGM96的高度。更接近“海拔”的日常概念。 Cesium地形数据如Cesium World Terrain默认提供的是海拔高度。如果你的waterHeight是椭球高度那比较基准就错了结果必然混乱。务必统一使用海拔高度。可以使用Cesium.sampleTerrainMostDetailed获取的海拔作为基准。检查着色器中的高度获取逻辑在着色器中你通过什么方式得到terrainHeight如果采样纹理纹理的编码方式RGB-Float是否正确如果使用内置函数坐标转换是否正确建议先在JavaScript端用sampleTerrain采样几个已知点打印出正确高度然后在着色器中对同一点输出颜色进行调试例如将高度值直接映射为颜色对比验证。检查条件判断逻辑着色器中的if (terrainHeight waterLevel)条件是否写反了大于和小于一念之差天地颠倒。6.4 性能急剧下降页面卡顿问题描述开启淹没分析后帧率FPS大幅下降。优化方向降低着色器复杂度检查片段着色器是否包含了过多的纹理采样、循环或复杂函数。简化计算比如将一些计算移到顶点着色器或JavaScript端。限制分析区域不要全局应用。通过一个多边形边界Rectangle来限定需要执行淹没分析的范围。只在范围内开启自定义着色器或进行CPU计算。采用LOD如前所述根据距离动态调整计算和渲染的精度。使用Web Worker对于CPU密集型的轮廓提取计算一定要放到Web Worker中避免阻塞UI线程。考虑降级方案在低端设备上关闭动态水位和高级水面效果只显示静态的、预计算好的淹没区域平面图。实现一个效果逼真、性能优异的Cesium淹没分析功能是一个融合了GIS概念、三维图形学和前端工程化的挑战。它没有标准答案需要根据你的数据特点、性能要求和展示需求在着色器方案和几何体方案之间做出权衡并针对性地优化。从理解“水平面与地形求交”这一核心原理出发一步步解决高度获取、着色器编写、性能优化这些具体问题你就能在三维场景中让洪水“涨”起来让分析“活”起来。