---
outline: [2, 3]
---

# 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`

```ts
  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`

```ts
    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`

```ts
  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`

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

### `FlowParticles.dispose`

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

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

## Demo 参考

### `FlowParticles`

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

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