310 lines
7.9 KiB
Markdown
310 lines
7.9 KiB
Markdown
---
|
|
outline: [2, 3]
|
|
---
|
|
|
|
# FlowParticles
|
|
|
|
- 源文件：`packages/sdk/src/effect/FlowParticles.ts`
|
|
- 文档位置：`packages/docs/api/effect/FlowParticles.md`
|
|
|
|
## 接口：`FlowParticlesGPUOptions`
|
|
|
|
- 作用：流动粒子配置。
|
|
|
|
### 字段
|
|
|
|
| 字段名 | 类型 | 必填 | 作用 |
|
|
| --- | --- | --- | --- |
|
|
| `startPipe` | `ParametricPipe` | 是 | 起始管道。 |
|
|
| `endPipe` | `ParametricPipe` | 是 | 结束管道。 |
|
|
| `particleCount` | `number` | 否 | 粒子总数量。 |
|
|
| `speedMultiplier` | `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` 对应的数据。 |
|
|
| `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`
|
|
- 返回说明：无返回值。
|
|
|
|
#### `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,
|
|
particleCount: particleCount.value,
|
|
speedMultiplier: speedMultiplier.value,
|
|
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.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`
|
|
|