前言

MapGIS数字孪生平台提供了丰富的三维仿真能力，MapGISTorrentAnalysis接口可用于模拟洪水、泥石流等自然灾害场景。本文档将详细介绍相关API的核心类、参数及典型用法。

核心类与接口说明

1. MapGISTorrentAnalysis（泥石流/洪水仿真分析）

该类用于创建和管理洪水、泥石流等水体仿真区域。支持设置仿真区域、流量、坡度、阻力等参数，并可动态添加水源、控制仿真过程。

构造方法：

new MapGISCloudRender.MapGISTorrentAnalysis(simulationPosition, options)

• simulationPosition：Cartesian3类型，仿真区域中心点坐标。
• options：Object类型，仿真参数配置，常用字段如下：

参数名	类型	说明	默认值
simulationPosition	Cartesian3	仿真区域场（立方体）上表面中心点坐标。
AreaWorldHeight	Number	仿真区域高度（单位：米）	35000
AreaWorldPixelSize	Number	区域像素大小，正方形边长=该值×1024	200
FluxEnergy	Number	水流能量系数	1.0
SlopScale	Number	水流坡度系数	10
SlopClamp	Number	水流坡度上限	20
VelocityClamp	Number	水流速度上限	8
Friction	Number	水流阻力系数	0.0005
NeedRemoveWater	Boolean	是否自动移除水体	false
NeedFloats	Boolean	是否生成漂浮物	false
SurfaceType	Number	水体类型（0:泥石流, 1:河流/洪水, 2:海面, 3:湖面）	1
IsDebug	Boolean	是否开启调试辅助视图	false

常用属性与方法：

• action：String，仿真状态（init、start、stop、remove、startFall、stopFall）。
• addSource(source)：添加水源对象。
• startTorrent() / stopTorrent()：开启/关闭所有水源。
• startFloats() / stopFloats()：生成/移除漂浮物。
• animationOnEnd：动画结束回调。

2. MapGISTorrentWaterSource（水源）

用于定义仿真中的水源点，需与MapGISTorrentAnalysis配合使用。

构造方法：

new MapGISCloudRender.MapGISTorrentWaterSource(position,  scale)

• position：Cartesian3类型，水源位置（应在仿真场范围内）。
• scale：Cartesian3类型，水源大小缩放（仅XY分量有效）。

常用属性与方法：

• action：String，水源状态（init、start、stop、remove）。
• animationOnEnd：动画结束回调。

完整示例

// 1. 创建仿真场景
const scene = new MapGISCloudRender.MapGISScene(cloudRenderBaseUrl, 'container', { token: cloudRenderServiceToken });
scene.loadScene().then(() => {
  // 2. 相机定位、底图与地形加载
  scene.camera.flyTo(经度, 纬度, 高度, { az, pitch, duration: 0 });
  addImagery();
  addTerrainLayer();

  // 3. 创建洪水仿真分析对象
  const simulationPosition = new MapGISCloudRender.Cartesian3(经度, 纬度, 高度);
  const options = {
    AreaWorldHeight: 200,
    AreaWorldPixelSize: 200,
    FluxEnergy: 5,
    SlopScale: 10,
    SlopClamp: 20,
    VelocityClamp: 8,
    Friction: 0.001,
    NeedRemoveWater: true,
    NeedFloats: false,
    SurfaceType: 1,
    IsDebug: true,
  };
  const torrent = new MapGISCloudRender.MapGISTorrentAnalysis(simulationPosition, options);
  scene.addCovering(torrent).then(() => {
    // 4. 添加水源
    const sourcePosition = new MapGISCloudRender.Cartesian3(经度, 纬度, 高度);
    const speed = new MapGISCloudRender.Cartesian3(1, 1, 1);
    const scale = new MapGISCloudRender.Cartesian3(1, 1, 1);
    const source = new MapGISCloudRender.MapGISTorrentWaterSource(sourcePosition, speed, scale);
    scene.addCovering(source).then(() => {
      torrent.addSource(source);
      // 5. 启动仿真
      setTimeout(() => {
        torrent.action = "start";
      }, 30);
    });
  });
});