Cesium淹没分析实战：用CallbackProperty动态模拟洪水上涨（附完整代码）

Cesium淹没分析实战：用CallbackProperty动态模拟洪水上涨（附完整代码）

最近在做一个智慧城市的三维应急管理项目，客户指着屏幕上的数字孪生模型问：“如果上游水库泄洪，我们这片区域的水位会怎么涨？能不能动态地、像放电影一样模拟出来？” 这个问题直接指向了三维GIS中一个经典且极具实用价值的课题——动态淹没分析。传统的静态淹没图只能展示最终结果，而决策者更需要看到水位随时间推移的动态上涨过程，这恰恰是Cesium结合其CallbackProperty特性大放异彩的地方。今天，我就结合自己趟过的坑和最终实现的流畅效果，来详细拆解如何从零构建一个逼真的动态洪水淹没模拟。

对于GIS开发者和三维可视化工程师来说，实现淹没分析不仅仅是画一个不断升高的多边形那么简单。核心挑战在于：如何让水位上涨与真实地形无缝贴合？如何高效获取任意划定区域的地形极值？如何保证动画的流畅性与性能？本文将围绕CallbackProperty这一动态属性驱动核心，手把手带你解决这些问题，并提供可直接集成到项目中的完整代码模块。

1. 理解动态淹没分析的核心：CallbackProperty机制

在Cesium的实体（Entity）体系中，大多数几何属性（如位置、高度、颜色）都可以是静态值或动态值。静态值一旦设定就不再改变，而动态值则允许属性随时间或其他条件变化。Cesium.CallbackProperty正是创建这种动态属性的工厂函数。

你可以把它想象成一个智能的、不断自我更新的数据源。它接受一个回调函数和一个布尔值（指示该属性是否恒定）。在场景的每一帧渲染前，Cesium都会调用这个回调函数，取其返回值作为该属性的当前值。这就为我们实现水位连续上涨的动画效果提供了底层支持。

与直接使用Cesium.JulianDate和SampledProperty（适用于基于确切时间样本的动画）不同，CallbackProperty更灵活，它不依赖于严格的时间线，而是依赖于函数内部的逻辑。对于淹没分析，我们通常基于一个自定义的“水位高度”变量来驱动，这个变量可以在回调函数内以我们定义的速率递增。

注意：CallbackProperty的第二个参数isConstant通常设为false，表示该属性是变化的。如果设为true，则回调函数只会被调用一次，后续将使用缓存值，无法实现动画。

来看一个最简单的概念性代码，理解其工作原理：

// 假设我们有一个控制水位高度的变量
let currentWaterHeight = 50.0; // 初始高度，单位：米
const heightIncrement = 0.1; // 每帧上涨0.1米

// 创建一个动态的extrudedHeight属性
const dynamicHeight = new Cesium.CallbackProperty(function(time, result) {
    // 在每一帧，增加水位高度
    currentWaterHeight += heightIncrement;
    
    // 可以设置一个上限
    if (currentWaterHeight > 100.0) {
        currentWaterHeight = 100.0;
    }
    
    // 返回当前的水位高度值
    return currentWaterHeight;
}, false); // isConstant = false，表示值会变化

// 将这个动态属性赋给多边形的拉伸高度
const floodEntity = viewer.entities.add({
    polygon: {
        hierarchy: new Cesium.PolygonHierarchy(positions),
        extrudedHeight: dynamicHeight, // 使用动态属性
        material: Cesium.Color.BLUE.withAlpha(0.6)
    }
});

这段代码创建了一个会“自动生长”的多边形体。关键在于，上涨的逻辑完全由开发者掌控。你可以根据模拟的洪水流量、时间、甚至外部数据（如实时雨量数据）来动态计算currentWaterHeight的变化率，从而实现从简单线性上涨到复杂非线性淹没的各种模拟。

2. 实战第一步：精准获取淹没区域地形高程极值

在开始让水位上涨之前，我们必须先回答一个基础问题：水从哪里开始涨？ 如果简单地将拉伸高度（extrudedHeight）从0开始增加，多边形体很可能从地底深处开始“生长”，因为真实地形的高程通常大于0。这会导致在视觉上，水仿佛是从地下冒出来的，而非在地表汇聚上涨，严重失真。

因此，一个关键的前置步骤是计算用户划定淹没区域内的地形最低点（最小高程）。我们将以此作为水位上涨的起始面。同时，获取最高点也有助于设定合理的上涨上限或进行风险分析。

Cesium本身没有提供直接获取一个任意多边形范围内地形高程极值的API。我们需要一个策略来“采样”区域内的地形。一个高效且精度可控的方法是：构建多边形外包矩形网格，采样网格点高程。

这里，我们借助强大的地理空间处理库turf.js来辅助生成网格。主要步骤分解如下：

1. 坐标转换：将Cesium的Cartesian3坐标数组转换为经纬度数组，供turf处理。
2. 生成外包矩形（Bounding Box）：使用turf快速获取多边形的最小外包矩形，作为采样范围。
3. 创建均匀点网格：在矩形范围内，生成均匀分布的采样点。采样密度（网格大小）需要权衡精度和性能。
4. 地形采样：使用Cesium.sampleTerrainMostDetailed异步获取每个采样点的精确地形高度。
5. 计算极值：遍历所有采样点的高度，找出最大值和最小值。

下面是一个封装好的函数calculateTerrainExtremum，它返回一个Promise，解决后得到包含minHeight和maxHeight的对象。

import * as turf from '@turf/turf';

/**
 * 计算给定多边形区域内的地形高程最小值和最大值
 * @param {Cesium.Viewer} viewer - Cesium Viewer实例
 * @param {Cesium.Cartesian3[]} positions - 多边形顶点坐标数组（Cartesian3）
 * @param {Number} [sampleDensity=10000] - 期望的采样点数量，影响精度和性能
 * @returns {Promise<{minHeight: Number, maxHeight: Number}>}
 */
async function calculateTerrainExtremum(viewer, positions, sampleDensity = 10000) {
    const ellipsoid = viewer.scene.globe.ellipsoid;
    
    // 1. 转换坐标为经纬度数组 [[lng, lat], ...]
    const lonLatArray = positions.map(cartesian3 => {
        const cartographic = ellipsoid.cartesianToCartographic(cartesian3);
        return [
            Cesium.Math.toDegrees(cartographic.longitude),
            Cesium.Math.toDegrees(cartographic.latitude)