ljq/deep-engine-demo

Fork 0

plum d2329a6854 feat(all): 更新文档

2026-05-06 22:16:20 +08:00

10 KiB

Raw Permalink Blame History

outline

FlowParticles

源文件：packages/sdk/src/effect/FlowParticles.ts
文档位置：packages/docs/api/effect/FlowParticles.md

地热注采流动说明

FlowParticles 在地热注采场景中支持两类模式：

bidirectional：双向对向流动，左右侧粒子分别向中段推进。
single：单向流动，支持按左右流量差异发射“补差粒子”，并在中段附近显隐以模拟注采不均衡。

最新业务逻辑包含：

单向模式的左右段隐藏特例（某侧速度为 0 时，该侧默认隐藏）。
基于几何投影的显隐判定，避免仅按参数 t 带来的路径不均问题。
右侧流量高于左侧时，自动发射补差粒子。

接口：`FlowParticlesGPUOptions`

作用：流动粒子配置。

字段

字段名	类型	必填	作用
`startPipe`	`ParametricPipe`	是	起始管道。
`endPipe`	`ParametricPipe`	是	结束管道。
`particleCount`	`number`	否	粒子总数量。
`speedMultiplier`	`number`	否	粒子流动速度倍率。
`flowMode`	`"single" \| "bidirectional"`	否	流动模式，默认 `single`。
`leftFlowRate`	`number`	否	左侧流量权重。
`rightFlowRate`	`number`	否	右侧流量权重。
`leftSpeedMultiplier`	`number`	否	左侧速度倍率。
`rightSpeedMultiplier`	`number`	否	右侧速度倍率。
`particleSize`	`number`	否	粒子半径。
`heatingThreshold`	`number`	否	加热阈值。
`flowPathCount`	`number`	否	流动路径数量。
`colorStops`	`FlowColorStop[]`	否	颜色断点配置。

接口：`FlowColorStop`

作用：流动颜色断点。

字段

字段名	类型	必填	作用
`color`	`string`	是	颜色值。
`step`	`number`	是	断点位置，范围 [0, 1]。
`frozenProbability`	`number`	否	当粒子经过该断点时被永久冻结颜色的概率，范围 [0, 1]。

类：`FlowParticles`

作用：流动粒子效果。

构造函数

`new FlowParticles(viewer: Viewer, options: FlowParticlesGPUOptions)`

作用：构造函数。
入参：

参数名	类型	必填	说明
`viewer`	`Viewer`	是	视图对象
`options`	`FlowParticlesGPUOptions`	是	配置参数

出参：FlowParticles
返回说明：返回当前类实例。

属性

属性名	可见性	类型	作用
`viewer`	`public`	`Viewer`	用于保存 `viewer` 对应的数据。
`startPipe`	`public`	`ParametricPipe`	用于保存 `startPipe` 对应的数据。
`endPipe`	`public`	`ParametricPipe`	用于保存 `endPipe` 对应的数据。
`particleCount`	`public`	`number`	用于保存 `particleCount` 对应的数据。
`speedMultiplier`	`public`	`number`	用于保存 `speedMultiplier` 对应的数据。
`flowMode`	`public`	`"single" \| "bidirectional"`	当前流动模式。
`leftFlowRate`	`public`	`number`	左侧流量权重。
`rightFlowRate`	`public`	`number`	右侧流量权重。
`leftSpeedMultiplier`	`public`	`number`	左侧速度倍率。
`rightSpeedMultiplier`	`public`	`number`	右侧速度倍率。
`particleSize`	`public`	`number`	用于保存 `particleSize` 对应的数据。
`heatingThreshold`	`public`	`number`	用于保存 `heatingThreshold` 对应的数据。
`flowPathCount`	`public`	`number`	用于保存 `flowPathCount` 对应的数据。
`colorStops`	`public`	`FlowColorStop[]`	用于保存 `colorStops` 的集合数据。
`flowPaths`	`public`	`THREE.CatmullRomCurve3[]`	用于保存 `flowPaths` 的集合数据。
`particles`	`public`	`Particle[]`	用于保存 `particles` 的集合数据。
`flowGeometry`	`public`	`THREE.SphereGeometry \| null`	用于保存 `flowGeometry` 对应的数据。
`flowMaterial`	`public`	`THREE.Material \| null`	用于保存 `flowMaterial` 对应的数据。
`flowPoints`	`public`	`THREE.InstancedMesh \| null`	用于保存 `flowPoints` 对应的数据。
`updateHandler`	`public`	`(() => void) \| null`	用于保存 `updateHandler` 对应的数据。

方法

`setParticleCount(count: number): void`

作用：设置粒子数量并重建系统。
入参：

参数名	类型	必填	说明
`count`	`number`	是	粒子数量

出参：void
返回说明：无返回值。

`setSpeedMultiplier(speed: number): void`

作用：设置速度倍率。
入参：

参数名	类型	必填	说明
`speed`	`number`	是	速度倍率

出参：void
返回说明：无返回值。

`setSideFlowRates(leftRate: number, rightRate: number): void`

作用：设置左右流量权重。双向模式下会重建粒子系统；单向模式下用于更新发射和保留判定。
入参：

参数名	类型	必填	说明
`leftRate`	`number`	是	左侧流量权重。
`rightRate`	`number`	是	右侧流量权重。

出参：void
返回说明：无返回值。

`setSideSpeedMultipliers(leftSpeed: number, rightSpeed: number): void`

作用：设置左右速度倍率，用于控制两侧流动推进速度。
入参：

参数名	类型	必填	说明
`leftSpeed`	`number`	是	左侧速度倍率。
`rightSpeed`	`number`	是	右侧速度倍率。

出参：void
返回说明：无返回值。

`setFrozenProbability(probability: number): void`

作用：设置冻结概率。
入参：

参数名	类型	必填	说明
`probability`	`number`	是	冻结概率，范围 [0, 1]

出参：void
返回说明：无返回值。

`setHeatingThreshold(threshold: number): void`

作用：设置加热阈值。
入参：

参数名	类型	必填	说明
`threshold`	`number`	是	阈值，范围 [0, 1]

出参：void
返回说明：无返回值。

`setColorStops(stops: FlowColorStop[]): void`

作用：动态更新颜色断点。
入参：

参数名	类型	必填	说明
`stops`	`FlowColorStop[]`	是	断点数组

出参：void
返回说明：无返回值。

`dispose(): void`

作用：释放资源。
入参：无
出参：void
返回说明：无返回值。

`toVector3(point: THREE.Vector3 | { x: number; y: number; z: number }): THREE.Vector3`

作用：点位转换为 THREE.Vector3。
入参：

参数名	类型	必填	说明
`point`	`THREE.Vector3 \| { x: number; y: number; z: number }`	是	输入点

出参：THREE.Vector3
返回说明：转换结果

`init(): void`

作用：初始化。
入参：无
出参：void
返回说明：无返回值。

`createFlowPaths(): void`

作用：生成流动路径。
入参：无
出参：void
返回说明：无返回值。

`initParticles(): void`

作用：初始化粒子网格。
入参：无
出参：void
返回说明：无返回值。

`setupUpdateLoop(): void`

作用：绑定更新循环。
入参：无
出参：void
返回说明：无返回值。

`update(): void`

作用：每帧更新。
入参：无
出参：void
返回说明：无返回值。

`calculateHeatColor(t: number): number`

作用：计算热值。
入参：

参数名	类型	必填	说明
`t`	`number`	是	路径进度

出参：number
返回说明：热值

构造示例

来源：packages/demo/src/panels/GeothermalScene/GeothermalInjectionProductionPanel.vue

  try {
    const flowParticles = new FlowParticles(viewer, {
      startPipe: pipe1,
      endPipe: pipe2,
      flowMode: "single",
      particleCount: particleCount.value,
      speedMultiplier: speedMultiplier.value,
      leftFlowRate: 1,
      rightFlowRate: 1.2,
      leftSpeedMultiplier: 1,
      rightSpeedMultiplier: 1,
      particleSize: particleSize.value,
      heatingThreshold: heatingThreshold.value,
      colorStops: [
        {color: "#00FF00", step: 0},
        {color: "#FFFF00", step: 0.4},
        {color: "#FF0000", step: 0.6},
      ],
    });
    flowParticles.flowPoints.renderOrder = 0
    bus.setFlowParticles(flowParticles);
  } catch (error) {
    bus.setFlowParticles(null);
    console.error("创建热突破流体失败:", error);
  }

函数示例

`FlowParticles.setFrozenProbability`

来源：packages/demo/src/disasterFormationPanel/GeothermalScene/ThermalBreakthroughDisasterPanel.vue

    flowParticles.setColorStops([
      {color: '#00FF00', step: 0.0},
      {color: '#FFFF00', step: 0.5},
      {color: '#FF0000', step: 0.7},
    ]);
    // 约 30% 的粒子保持初始颜色，模拟热突破中部分流体未被加热
    flowParticles.setFrozenProbability(1);
  }
  isActive.value = !!flowParticles;
};

`FlowParticles.setColorStops`

来源：packages/demo/src/disasterFormationPanel/GeothermalScene/ThermalBreakthroughDisasterPanel.vue

  if (flowParticles) {
    flowParticles.setColorStops([
      {color: '#00FF00', step: 0.0},
      {color: '#FFFF00', step: 0.5},
      {color: '#FF0000', step: 0.7},
    ]);
    // 约 30% 的粒子保持初始颜色，模拟热突破中部分流体未被加热
    flowParticles.setFrozenProbability(1);
  }
  isActive.value = !!flowParticles;
};

`FlowParticles.setSideFlowRates`

if (flowParticles) {
  flowParticles.setSideFlowRates(1, 1.4);
  flowParticles.setSideSpeedMultipliers(1, 0.9);
}

`FlowParticles.dispose`

来源：packages/demo/src/panels/GeothermalScene/GeothermalInjectionProductionPanel.vue

  if (!previousFlowParticles) return;
  previousFlowParticles.dispose();
  bus.setFlowParticles(null);
};

Demo 参考

`FlowParticles`

以下示例文件中可以看到该 API 的实际调用方式：

packages/demo/src/hooks/Bus.ts
packages/demo/src/panels/GeothermalScene/GeothermalInjectionProductionPanel.vue

10 KiB Raw Permalink Blame History

FlowParticles

地热注采流动说明

接口：FlowParticlesGPUOptions

字段

接口：FlowColorStop

字段

类：FlowParticles

构造函数

new FlowParticles(viewer: Viewer, options: FlowParticlesGPUOptions)

属性

方法

setParticleCount(count: number): void

setSpeedMultiplier(speed: number): void

setSideFlowRates(leftRate: number, rightRate: number): void

setSideSpeedMultipliers(leftSpeed: number, rightSpeed: number): void

setFrozenProbability(probability: number): void

setHeatingThreshold(threshold: number): void

setColorStops(stops: FlowColorStop[]): void

dispose(): void

toVector3(point: THREE.Vector3 | { x: number; y: number; z: number }): THREE.Vector3

init(): void

createFlowPaths(): void

initParticles(): void

setupUpdateLoop(): void

update(): void

calculateHeatColor(t: number): number

构造示例

函数示例

FlowParticles.setFrozenProbability

FlowParticles.setColorStops

FlowParticles.setSideFlowRates

FlowParticles.dispose

Demo 参考

FlowParticles

10 KiB

Raw Permalink Blame History

接口：`FlowParticlesGPUOptions`

接口：`FlowColorStop`

类：`FlowParticles`

`new FlowParticles(viewer: Viewer, options: FlowParticlesGPUOptions)`

`setParticleCount(count: number): void`

`setSpeedMultiplier(speed: number): void`

`setSideFlowRates(leftRate: number, rightRate: number): void`

`setSideSpeedMultipliers(leftSpeed: number, rightSpeed: number): void`

`setFrozenProbability(probability: number): void`

`setHeatingThreshold(threshold: number): void`

`setColorStops(stops: FlowColorStop[]): void`

`dispose(): void`

`toVector3(point: THREE.Vector3 | { x: number; y: number; z: number }): THREE.Vector3`

`init(): void`

`createFlowPaths(): void`

`initParticles(): void`

`setupUpdateLoop(): void`

`update(): void`

`calculateHeatColor(t: number): number`

`FlowParticles.setFrozenProbability`

`FlowParticles.setColorStops`

`FlowParticles.setSideFlowRates`

`FlowParticles.dispose`

`FlowParticles`