feat(all): init commit

packages/docs/api/effect/FaultSlip.md

@@ -0,0 +1,262 @@
+---
+outline: [2, 3]
+---
+
+# FaultSlip
+
+- 源文件：`packages/sdk/src/effect/FaultSlip.ts`
+- 文档位置：`packages/docs/api/effect/FaultSlip.md`
+
+## 接口：`FaultSlipOptions`
+
+- 作用：FaultSlipOptions 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `normal` | `THREE.Vector3` | 否 | 法线方向。 |
+| `rows` | `number` | 否 | 用于保存 `rows` 对应的数据。 |
+| `cols` | `number` | 否 | 用于保存 `cols` 对应的数据。 |
+| `spacingU` | `number` | 否 | 用于保存 `spacingU` 对应的数据。 |
+| `spacingV` | `number` | 否 | 用于保存 `spacingV` 对应的数据。 |
+| `arrowLength` | `number` | 否 | 用于保存 `arrowLength` 对应的数据。 |
+| `shaftWidth` | `number` | 否 | 用于保存 `shaftWidth` 对应的数据。 |
+| `headWidth` | `number` | 否 | 用于保存 `headWidth` 对应的数据。 |
+| `headLength` | `number` | 否 | 用于保存 `headLength` 对应的数据。 |
+| `colorHex` | `number` | 否 | 用于保存 `colorHex` 对应的数据。 |
+| `arrowSideOffset` | `number` | 否 | 用于保存 `arrowSideOffset` 对应的数据。 |
+| `arrowMoveAmp` | `number` | 否 | 用于保存 `arrowMoveAmp` 对应的数据。 |
+| `arrowMoveSpeed` | `number` | 否 | 用于保存 `arrowMoveSpeed` 对应的数据。 |
+| `autoStart` | `boolean` | 否 | 用于标记 `autoStart` 的启用状态。 |
+
+## 类：`FaultSlip`
+
+- 作用：断层滑移引起矿震的可视化效果 基于 Mesh 的包围盒生成断层面和交错箭头动画
+
+### 构造函数
+
+#### `new FaultSlip(mesh: THREE.Mesh, options?: FaultSlipOptions)`
+
+- 作用：创建 FaultSlip 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `mesh` | `THREE.Mesh` | 是 | 目标网格对象。 |
+| `options` | `FaultSlipOptions` | 否 | 当前功能对应的配置项。 |
+
+- 出参：`FaultSlip`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<FaultSlipOptions>` | 用于保存 `options` 对应的数据。 |
+| `group` | `public` | `THREE.Group` | 用于保存 `group` 对应的数据。 |
+| `active` | `public` | `boolean` | 用于标记 `active` 的启用状态。 |
+| `mesh` | `public` | `THREE.Mesh` | 用于保存 `mesh` 对应的数据。 |
+| `arrowAnims` | `public` | `ArrowAnimation[]` | 用于保存 `arrowAnims` 的集合数据。 |
+| `flatArrowShaftGeom` | `public` | `THREE.PlaneGeometry` | 用于保存 `flatArrowShaftGeom` 对应的数据。 |
+| `flatArrowHeadGeom` | `public` | `THREE.ShapeGeometry` | 用于保存 `flatArrowHeadGeom` 对应的数据。 |
+| `flatArrowMat` | `public` | `THREE.MeshBasicMaterial` | 用于保存 `flatArrowMat` 对应的数据。 |
+| `tmpV` | `public` | `THREE.Vector3` | 用于保存 `tmpV` 对应的数据。 |
+| `tmpV2` | `public` | `THREE.Vector3` | 用于保存 `tmpV2` 对应的数据。 |
+| `tmpV3` | `public` | `THREE.Vector3` | 用于保存 `tmpV3` 对应的数据。 |
+| `tmpM` | `public` | `THREE.Matrix4` | 用于保存 `tmpM` 对应的数据。 |
+| `updateBound` | `public` | `((data: RenderEventData) => void) \| null` | 用于保存 `updateBound` 对应的数据。 |
+
+### 方法
+
+#### `start(): void`
+
+- 作用：执行 start 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `stop(): void`
+
+- 作用：执行 stop 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `toggle(): void`
+
+- 作用：执行 toggle 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `update(data: RenderEventData): void`
+
+- 作用：更新 update。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `RenderEventData` | 是 | 输入数据。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setColor(colorHex: number): void`
+
+- 作用：设置 Color。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `colorHex` | `number` | 是 | 参数 `colorHex`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setOpacity(opacity: number): void`
+
+- 作用：设置 Opacity。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `opacity` | `number` | 是 | 参数 `opacity`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setSpeed(speed: number): void`
+
+- 作用：设置 Speed。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `speed` | `number` | 是 | 参数 `speed`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setAmplitude(amplitude: number): void`
+
+- 作用：设置 Amplitude。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `amplitude` | `number` | 是 | 参数 `amplitude`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：释放资源并销毁当前实例。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `init(): void`
+
+- 作用：执行 init 初始化逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `makeArrowMesh(params: { length: number; shaftWidth: number; headWidth: number; headLength: number; }): THREE.Group<THREE.Object3DEventMap>`
+
+- 作用：执行 make Arrow Mesh 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `params` | `{ length: number; shaftWidth: number; headWidth: number; headLength: number; }` | 是 | 参数 `params`，类型为 `{ length: number; shaftWidth: number; headWidth: number; headLength: number; }`。 |
+
+- 出参：`THREE.Group<THREE.Object3DEventMap>`
+- 返回说明：返回 `THREE.Group<THREE.Object3DEventMap>`。
+
+#### `orientArrowOnSection(arrow: THREE.Group, moveDir: THREE.Vector3, sectionNormal: THREE.Vector3): void`
+
+- 作用：执行 orient Arrow On Section 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `arrow` | `THREE.Group` | 是 | 参数 `arrow`，类型为 `THREE.Group`。 |
+| `moveDir` | `THREE.Vector3` | 是 | 参数 `moveDir`，类型为 `THREE.Vector3`。 |
+| `sectionNormal` | `THREE.Vector3` | 是 | 参数 `sectionNormal`，类型为 `THREE.Vector3`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `buildVisualization(): void`
+
+- 作用：执行 build Visualization 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+
+```ts
+  const section = bus.getSection();
+  faultSlip = new FaultSlip(section, {autoStart: true});
+  faultSlipSeismicWave = new SeismicWave({
+    emitterPositions: [new THREE.Vector3(0, 0, 0)],
+    shape: 'sphere',
+    autoStart: true
+  });
+  hasFaultSlip.value = true;
+};
+```
+
+- 来源：`packages/demo/src/disasterFormationPanel/OilGasScene/OilGasMineSeismicPanel.vue`
+
+```ts
+  const section = bus.getSection();
+  faultSlip = new FaultSlip(section, {autoStart: true});
+  faultSlipSeismicWave = new SeismicWave({
+    emitterPositions: [new THREE.Vector3(0, 0, 0)],
+    shape: 'sphere',
+    autoStart: true
+  });
+  hasFaultSlip.value = true;
+};
+```
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `FaultSlip` 的公开方法调用。
+
+## Demo 参考
+
+### `FaultSlip`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+- `packages/demo/src/disasterFormationPanel/OilGasScene/OilGasMineSeismicPanel.vue`
+

packages/docs/api/effect/FlowParticles.md

@@ -0,0 +1,309 @@
+---
+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`
+

packages/docs/api/effect/FractureEffect.md

@@ -0,0 +1,410 @@
+---
+outline: [2, 3]
+---
+
+# FractureEffect
+
+- 源文件：`packages/sdk/src/effect/FractureEffect.ts`
+- 文档位置：`packages/docs/api/effect/FractureEffect.md`
+
+## 接口：`FractureEffectOptions`
+
+- 作用：FractureEffectOptions 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `points` | `THREE.Vector3[]` | 是 | 用于保存 `points` 的集合数据。 |
+| `curveType` | `'catmullrom' \| 'linear'` | 否 | 用于保存 `curveType` 对应的数据。 |
+| `tension` | `number` | 否 | 用于保存 `tension` 对应的数据。 |
+| `closed` | `boolean` | 否 | 用于标记 `closed` 的启用状态。 |
+| `spacing` | `number` | 否 | 用于保存 `spacing` 对应的数据。 |
+| `bufferRatio` | `number` | 否 | 用于保存 `bufferRatio` 对应的数据。 |
+| `minRadius` | `number` | 否 | 用于保存 `minRadius` 对应的数据。 |
+| `maxRadius` | `number` | 否 | 用于保存 `maxRadius` 对应的数据。 |
+| `animationDuration` | `number` | 否 | 用于保存 `animationDuration` 对应的数据。 |
+| `sphereAnimDuration` | `number` | 否 | 用于保存 `sphereAnimDuration` 对应的数据。 |
+| `sphereOpacity` | `number` | 否 | 用于保存 `sphereOpacity` 对应的数据。 |
+| `spheresVisible` | `boolean` | 否 | 用于标记 `spheresVisible` 的启用状态。 |
+| `cracksVisible` | `boolean` | 否 | 用于标记 `cracksVisible` 的启用状态。 |
+| `colorMode` | `'random' \| 'gradient' \| 'fixed'` | 否 | 用于保存 `colorMode` 对应的数据。 |
+| `fixedColor` | `number` | 否 | 用于保存 `fixedColor` 对应的数据。 |
+| `gradientStart` | `number` | 否 | 用于保存 `gradientStart` 对应的数据。 |
+| `gradientEnd` | `number` | 否 | 用于保存 `gradientEnd` 对应的数据。 |
+| `autoStart` | `boolean` | 否 | 用于标记 `autoStart` 的启用状态。 |
+| `crackModelUrls` | `string[]` | 否 | 用于保存 `crackModelUrls` 的集合数据。 |
+
+## 类：`FractureEffect`
+
+- 作用：压裂效果 沿着一组点生成的曲线生成一系列带弹性动画的球体，模拟压裂过程
+
+### 构造函数
+
+#### `new FractureEffect(options: FractureEffectOptions)`
+
+- 作用：创建 FractureEffect 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `FractureEffectOptions` | 是 | 当前功能对应的配置项。 |
+
+- 出参：`FractureEffect`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<FractureEffectOptions>` | 用于保存 `options` 对应的数据。 |
+| `active` | `public` | `boolean` | 用于标记 `active` 的启用状态。 |
+| `running` | `public` | `boolean` | 用于标记 `running` 的启用状态。 |
+| `spheres` | `public` | `FractureSphere[]` | 用于保存 `spheres` 的集合数据。 |
+| `group` | `public` | `THREE.Group` | 用于保存 `group` 对应的数据。 |
+| `crackModels` | `public` | `THREE.Object3D[]` | 用于保存 `crackModels` 的集合数据。 |
+| `crackModelTemplates` | `public` | `THREE.Object3D[]` | 用于保存 `crackModelTemplates` 的集合数据。 |
+| `progressCallback` | `public` | `((progress: number) => void) \| null` | 用于保存 `progressCallback` 对应的数据。 |
+| `curve` | `public` | `THREE.Curve<THREE.Vector3> \| null` | 用于保存 `curve` 对应的数据。 |
+
+### 方法
+
+#### `createCurve(): void`
+
+- 作用：根据点数组创建曲线
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `onProgress(callback: (progress: number) => void): void`
+
+- 作用：设置进度回调
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `(progress: number) => void` | 是 | 回调函数。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `start(): Promise<void>`
+
+- 作用：开始压裂动画
+
+- 入参：无
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `stop(): void`
+
+- 作用：停止动画
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `clear(): void`
+
+- 作用：清除所有球体和裂缝模型
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `showCracks(): void`
+
+- 作用：显示裂缝模型
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `hideCracks(): void`
+
+- 作用：隐藏裂缝模型
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `toggleCracks(): void`
+
+- 作用：切换裂缝模型显示
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `showSpheres(): void`
+
+- 作用：显示球体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `hideSpheres(): void`
+
+- 作用：隐藏球体
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `toggleSpheres(): void`
+
+- 作用：切换球体显示
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setOpacity(opacity: number): void`
+
+- 作用：设置球体透明度
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `opacity` | `number` | 是 | 参数 `opacity`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updatePoints(points: THREE.Vector3[]): void`
+
+- 作用：更新点数组
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `points` | `THREE.Vector3[]` | 是 | 参数 `points`，类型为 `THREE.Vector3[]`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `restart(): Promise<void>`
+
+- 作用：重新开始
+
+- 入参：无
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `getSphereCount(): number`
+
+- 作用：获取球体数量
+
+- 入参：无
+
+- 出参：`number`
+- 返回说明：返回数值结果。
+
+#### `getSpheres(): FractureSphere[]`
+
+- 作用：获取球体列表
+
+- 入参：无
+
+- 出参：`FractureSphere[]`
+- 返回说明：返回数组结果，元素类型为 `FractureSphere`。
+
+#### `dispose(): void`
+
+- 作用：销毁
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `loadCrackModels(): Promise<void>`
+
+- 作用：加载裂缝模型模板
+
+- 入参：无
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `getRandomHighContrastColor(): THREE.Color`
+
+- 作用：生成高对比度随机颜色
+
+- 入参：无
+
+- 出参：`THREE.Color`
+- 返回说明：返回 `THREE.Color`。
+
+#### `getGradientColor(t: number): THREE.Color`
+
+- 作用：根据位置获取渐变颜色
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `t` | `number` | 是 | 参数 `t`，类型为 `number`。 |
+
+- 出参：`THREE.Color`
+- 返回说明：返回 `THREE.Color`。
+
+#### `getSphereColor(t: number): THREE.Color`
+
+- 作用：获取球体颜色
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `t` | `number` | 是 | 参数 `t`，类型为 `number`。 |
+
+- 出参：`THREE.Color`
+- 返回说明：返回 `THREE.Color`。
+
+#### `easeOutElastic(x: number): number`
+
+- 作用：缓动函数 - easeOutElastic
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `x` | `number` | 是 | 参数 `x`，类型为 `number`。 |
+
+- 出参：`number`
+- 返回说明：返回数值结果。
+
+#### `animateSphereIn(sphere: THREE.Mesh): Promise<void>`
+
+- 作用：球体弹入动画
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `sphere` | `THREE.Mesh` | 是 | 参数 `sphere`，类型为 `THREE.Mesh`。 |
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `calculatePositions(): { position: THREE.Vector3; t: number; index: number; }[]`
+
+- 作用：计算球体位置
+
+- 入参：无
+
+- 出参：`{ position: THREE.Vector3; t: number; index: number; }[]`
+- 返回说明：返回数组结果，元素类型为 `{ position: THREE.Vector3; t: number; index: number; }`。
+
+## 构造示例
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+
+```ts
+  const points = [
+    new THREE.Vector3(1.5, -0.3, 1.5),
+    new THREE.Vector3(0,  -0.3, 0)
+  ]
+
+  effect = new FractureEffect({
+    points: points,
+    curveType: 'catmullrom',
+    tension: 0.5,
+    spacing: 0.1, // 增大间距
+    bufferRatio: 0.02,
+    closed: false, // 不闭合，形成螺旋
+    spheresVisible: showRuptureSpheres.value,
+    cracksVisible: showFractures.value
+  });
+```
+
+- 来源：`packages/demo/src/panels/OilGasScene/FracturingPanel.vue`
+
+```ts
+  const points = generateSpiralPoints();
+
+  effect = new FractureEffect({
+    points: points,
+    curveType: 'catmullrom',
+    tension: 0.5,
+    spacing: 0.2, // 增大间距
+    bufferRatio: 0.02,
+    closed: false, // 不闭合，形成螺旋
+    spheresVisible: showRuptureSpheres.value,
+    cracksVisible: showFractures.value
+  });
+```
+
+## 函数示例
+
+### `FractureEffect.onProgress`
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+
+```ts
+  effect = new FractureEffect({
+    points: points,
+    curveType: 'catmullrom',
+    tension: 0.5,
+    spacing: 0.1, // 增大间距
+    bufferRatio: 0.02,
+    closed: false, // 不闭合，形成螺旋
+    spheresVisible: showRuptureSpheres.value,
+    cracksVisible: showFractures.value
+  });
+
+  isRunning.value = true;
+  effect.onProgress((progress) => {
+    if (progress >= 1) isRunning.value = false;
+  });
+```
+
+### `FractureEffect.showCracks`
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+
+```ts
+  if (effect) {
+    if (showFractures.value) effect.showCracks(); else effect.hideCracks();
+  }
+  isRunning.value = false;
+};
+```
+
+### `FractureEffect.showSpheres`
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+
+```ts
+  if (!effect) return;
+  if (val) effect.showSpheres(); else effect.hideSpheres();
+});
+```
+
+## Demo 参考
+
+### `FractureEffect`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/panels/GeothermalScene/DirectionalReservoir.vue`
+- `packages/demo/src/panels/OilGasScene/FracturingPanel.vue`
+

packages/docs/api/effect/RockDebris.md

@@ -0,0 +1,188 @@
+---
+outline: [2, 3]
+---
+
+# RockDebris
+
+- 源文件：`packages/sdk/src/effect/RockDebris.ts`
+- 文档位置：`packages/docs/api/effect/RockDebris.md`
+
+## 枚举：`RockDebrisModelSourceType`
+
+- 作用：落石模型来源类型
+
+| 枚举项 | 值 | 说明 |
+| --- | --- | --- |
+| `GENERATED` | `"GENERATED"` | 使用程序内置的几何体生成落石 |
+| `URL` | `"URL"` | 使用传入 URL 的模型生成落石 |
+
+## 接口：`RockDebrisOptions`
+
+- 作用：RockDebrisOptions 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `count` | `number` | 否 | 生成数量 |
+| `size` | `[number, number]` | 是 | 随机大小范围 [min, max] |
+| `office` | `[number, number]` | 是 | XZ 平面随机偏移范围 [min, max] |
+| `speed` | `number` | 是 | 掉落速度 (units/s) |
+| `startPosition` | `THREE.Vector3` | 是 | 开始位置 |
+| `mesh` | `THREE.Mesh` | 是 | 碰撞 mesh |
+| `modelSourceType` | `RockDebrisModelSourceType` | 否 | URL 模型来源类型 |
+| `modelUrls` | `string[]` | 否 | URL 模型地址列表 |
+
+## 类：`RockDebris`
+
+- 作用：岩爆碎片效果
+
+### 构造函数
+
+#### `new RockDebris(options: RockDebrisOptions)`
+
+- 作用：创建 RockDebris 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `RockDebrisOptions` | 是 | 当前功能对应的配置项。 |
+
+- 出参：`RockDebris`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<RockDebrisOptions>` | 用于保存 `options` 对应的数据。 |
+| `rocks` | `public` | `RockData[]` | 用于保存 `rocks` 的集合数据。 |
+| `active` | `public` | `boolean` | ------ 落石URL模型支持 结束------ |
+| `updateBound` | `public` | `((data: RenderEventData) => void) \| null` | 用于保存 `updateBound` 对应的数据。 |
+| `_matrix` | `public readonly` | `THREE.Matrix4` | 用于保存 `_matrix` 对应的数据。 |
+| `_raycaster` | `public readonly` | `THREE.Raycaster` | 用于保存 `_raycaster` 对应的数据。 |
+| `_rayDirection` | `public readonly` | `THREE.Vector3` | 用于保存 `_rayDirection` 对应的数据。 |
+| `SPAWN_MAX_RETRY` | `public readonly` | `20` | 单个落石生成点的最大重采样次数，防止射线检测陷入无限循环 |
+| `SPAWN_MIN_RAY_DISTANCE` | `public readonly` | `0.05` | 判定“靠墙”时的最小射线距离下限 |
+| `FALL_LIMIT` | `public readonly` | `50` | 超出起始点以下多少距离视为未命中，直接回收 |
+
+### 方法
+
+#### `spawn(): Promise<void>`
+
+- 作用：执行 spawn 相关逻辑。
+
+- 入参：无
+
+- 出参：`Promise<void>`
+- 返回说明：返回 Promise，解析结果类型为 `void`。
+
+#### `start(): void`
+
+- 作用：------ 落石落点射线重采样优化 结束------
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `stop(): void`
+
+- 作用：执行 stop 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `update(data: RenderEventData): void`
+
+- 作用：更新 update。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `RenderEventData` | 是 | 输入数据。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `clear(): void`
+
+- 作用：清理 clear。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：释放资源并销毁当前实例。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `init(): void`
+
+- 作用：执行 init 初始化逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`
+
+```ts
+  if (!archMesh){
+    return;
+  }
+  debris = new RockDebris({
+    count: 10,
+    size: [0.05, 0.1],
+    office: [-0.3, 0.3],
+    speed: 3,
+    startPosition: ROCK_BURST_START_POSITION.clone(),
+    mesh: archMesh,
+    // modelSourceType: RockDebrisModelSourceType.URL,
+    modelSourceType: RockDebrisModelSourceType.GENERATED
+  });
+  debrisReady.value = true;
+}
+```
+
+## 函数示例
+
+### `RockDebris.spawn`
+
+- 来源：`packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`
+
+```ts
+const spawn = () => {
+  ensureDebris();
+  ensureRockBurstLabel();
+  debris?.spawn();
+};
+```
+
+## Demo 参考
+
+### `RockDebrisModelSourceType`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`
+
+### `RockDebris`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/TunnelScene/RockBurstPanel.vue`
+

packages/docs/api/effect/SeismicWave.md

@@ -0,0 +1,304 @@
+---
+outline: [2, 3]
+---
+
+# SeismicWave
+
+- 源文件：`packages/sdk/src/effect/SeismicWave.ts`
+- 文档位置：`packages/docs/api/effect/SeismicWave.md`
+
+## 接口：`SeismicWaveOptions`
+
+- 作用：SeismicWaveOptions 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `emitterPositions` | `THREE.Vector3[]` | 否 | 用于保存 `emitterPositions` 的集合数据。 |
+| `minRadius` | `number` | 否 | 用于保存 `minRadius` 对应的数据。 |
+| `maxRadius` | `number` | 否 | 用于保存 `maxRadius` 对应的数据。 |
+| `waveDuration` | `number` | 否 | 用于保存 `waveDuration` 对应的数据。 |
+| `spawnInterval` | `number` | 否 | 用于保存 `spawnInterval` 对应的数据。 |
+| `opacity` | `number` | 否 | 控制对象或材质的透明度。 |
+| `color` | `THREE.Color` | 否 | 颜色配置。 |
+| `autoStart` | `boolean` | 否 | 用于标记 `autoStart` 的启用状态。 |
+| `startDelay` | `number` | 否 | 用于保存 `startDelay` 对应的数据。 |
+| `shape` | `'sphere' \| 'hemisphere'` | 否 | 用于保存 `shape` 对应的数据。 |
+| `useRangeCulling` | `boolean` | 否 | 用于标记 `useRangeCulling` 的启用状态。 |
+
+## 类：`SeismicWave`
+
+- 作用：SeismicWave 类。
+
+### 构造函数
+
+#### `new SeismicWave(options?: SeismicWaveOptions)`
+
+- 作用：创建 SeismicWave 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `SeismicWaveOptions` | 否 | 当前功能对应的配置项。 |
+
+- 出参：`SeismicWave`
+- 返回说明：返回当前类实例。
+
+#### `new SeismicWave(position: THREE.Vector3, startDelay?: number)`
+
+- 作用：创建 SeismicWave 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `position` | `THREE.Vector3` | 是 | 位置参数。 |
+| `startDelay` | `number` | 否 | 参数 `startDelay`，类型为 `number`。 |
+
+- 出参：`SeismicWave`
+- 返回说明：返回当前类实例。
+
+#### `new SeismicWave(positions: THREE.Vector3[], startDelay?: number)`
+
+- 作用：创建 SeismicWave 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `positions` | `THREE.Vector3[]` | 是 | 参数 `positions`，类型为 `THREE.Vector3[]`。 |
+| `startDelay` | `number` | 否 | 参数 `startDelay`，类型为 `number`。 |
+
+- 出参：`SeismicWave`
+- 返回说明：返回当前类实例。
+
+#### `new SeismicWave(optionsOrPosition?: SeismicWaveOptions | THREE.Vector3 | THREE.Vector3[], startDelay?: number)`
+
+- 作用：创建 SeismicWave 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `optionsOrPosition` | `SeismicWaveOptions \| THREE.Vector3 \| THREE.Vector3[]` | 否 | 参数 `optionsOrPosition`，类型为 `SeismicWaveOptions \| THREE.Vector3 \| THREE.Vector3[]`。 |
+| `startDelay` | `number` | 否 | 参数 `startDelay`，类型为 `number`。 |
+
+- 出参：`SeismicWave`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `options` | `public` | `Required<SeismicWaveOptions>` | 用于保存 `options` 对应的数据。 |
+| `emitters` | `public` | `SeismicEmitter[]` | 用于保存 `emitters` 的集合数据。 |
+| `waves` | `public` | `SeismicWaveInstance[]` | 用于保存 `waves` 的集合数据。 |
+| `geometry` | `public` | `THREE.SphereGeometry \| null` | 用于保存 `geometry` 对应的数据。 |
+| `active` | `public` | `boolean` | 用于标记 `active` 的启用状态。 |
+| `startTime` | `public` | `number \| null` | 用于保存 `startTime` 对应的数据。 |
+| `delayTimer` | `public` | `number \| null` | 用于保存 `delayTimer` 对应的数据。 |
+| `boundingBox` | `public` | `ParametricBox \| null` | 用于保存 `boundingBox` 对应的数据。 |
+
+### 方法
+
+#### `init(): void`
+
+- 作用：执行 init 初始化逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `start(): void`
+
+- 作用：执行 start 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `startWithDelay(delay: number): void`
+
+- 作用：执行 start With Delay 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `delay` | `number` | 是 | 参数 `delay`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `stop(): void`
+
+- 作用：执行 stop 相关逻辑。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `clearWaves(): void`
+
+- 作用：清理 Waves。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `spawnWave(position: THREE.Vector3): void`
+
+- 作用：执行 spawn Wave 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `position` | `THREE.Vector3` | 是 | 位置参数。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `update(data: RenderEventData): void`
+
+- 作用：更新 update。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `RenderEventData` | 是 | 输入数据。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `removeFromScene(scene: THREE.Scene): void`
+
+- 作用：移除 From Scene。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `scene` | `THREE.Scene` | 是 | 目标场景实例。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setOpacity(opacity: number): void`
+
+- 作用：设置 Opacity。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `opacity` | `number` | 是 | 参数 `opacity`，类型为 `number`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setColor(color: number): void`
+
+- 作用：设置 Color。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `color` | `number` | 是 | 颜色参数。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateEmitterPositions(positions: THREE.Vector3[]): void`
+
+- 作用：更新 Emitter Positions。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `positions` | `THREE.Vector3[]` | 是 | 参数 `positions`，类型为 `THREE.Vector3[]`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：释放资源并销毁当前实例。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createDefaultEmitters(): THREE.Vector3[]`
+
+- 作用：创建 Default Emitters。
+
+- 入参：无
+
+- 出参：`THREE.Vector3[]`
+- 返回说明：返回数组结果，元素类型为 `THREE.Vector3`。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+
+```ts
+  const section = bus.getSection();
+  faultSlip = new FaultSlip(section, {autoStart: true});
+  faultSlipSeismicWave = new SeismicWave({
+    emitterPositions: [new THREE.Vector3(0, 0, 0)],
+    shape: 'sphere',
+    autoStart: true
+  });
+  hasFaultSlip.value = true;
+};
+```
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+
+```ts
+const createRockBurst = () => {
+  rockBurstSeismicWave = new SeismicWave({
+    emitterPositions: [new THREE.Vector3(1.5, 1.5, 1.5)],
+    shape: 'sphere',
+    autoStart: true
+  });
+  hasRockBurst.value = true;
+};
+```
+
+## 函数示例
+
+### `SeismicWave.dispose`
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+
+```ts
+  if (faultSlipSeismicWave) {
+    faultSlipSeismicWave.dispose();
+    faultSlipSeismicWave = null;
+  }
+  hasFaultSlip.value = false;
+};
+```
+
+## Demo 参考
+
+### `SeismicWave`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/MineSeismicPanel.vue`
+- `packages/demo/src/disasterFormationPanel/OilGasScene/OilGasMineSeismicPanel.vue`
+- `packages/demo/src/panels/TunnelScene/DisturbanceLoadingPanel.vue`
+

packages/docs/api/effect/volume/PointCloud.md

@@ -0,0 +1,218 @@
+---
+outline: [2, 3]
+---
+
+# PointCloud
+
+- 源文件：`packages/sdk/src/effect/volume/PointCloud.ts`
+- 文档位置：`packages/docs/api/effect/volume/PointCloud.md`
+
+## 接口：`PointCloudColorStop`
+
+- 作用：点云颜色停靠点配置。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `color` | `string` | 是 | 颜色值（支持十六进制、rgb、hsl 等 Canvas 支持的格式）。 |
+| `step` | `number` | 是 | 渐变位置，范围 0~1。 |
+
+## 接口：`PointCloudOptions`
+
+- 作用：点云渲染配置。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | 场景树显示名称。 |
+| `pointCloudData` | `PointCloudData` | 是 | 外部已准备好的点云数据。 |
+| `colorStops` | `PointCloudColorStop[]` | 否 | 颜色映射节点。 |
+| `pointSize` | `number` | 否 | 点大小（像素单位）。 |
+
+## 类：`PointCloud`
+
+- 作用：点云渲染对象。 参考 `webgpu_instance_points.html`： 使用 `Sprite + PointsNodeMaterial + instancedBufferAttribute + count` 的模式进行实例化点渲染。
+- 继承/实现：`extends THREE.Sprite`
+
+### 构造函数
+
+#### `new PointCloud(viewer: Viewer, options: PointCloudOptions)`
+
+- 作用：创建点云渲染对象。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 视图实例 |
+| `options` | `PointCloudOptions` | 是 | 点云渲染配置 |
+
+- 出参：`PointCloud`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `viewer` | `public readonly` | `Viewer` | 场景视图实例。 |
+| `opacity` | `public` | `THREE.UniformNode<'float', number>` | 控制对象或材质的透明度。 |
+| `densityRange` | `public` | `THREE.UniformNode<'vec2', THREE.Vector2>` | 用于保存 `densityRange` 对应的数据。 |
+
+### 方法
+
+#### `filterByIntensity(min: number, max: number = 1): void`
+
+- 作用：按强度区间过滤点云显示。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `min` | `number` | 是 | 最小强度 |
+| `max` | `number` | 否 | 最大强度 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setPointSize(pointSize: number): void`
+
+- 作用：批量更新点大小。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `pointSize` | `number` | 是 | 新的点大小（像素单位） |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `dispose(): void`
+
+- 作用：销毁点云对象并释放资源。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+
+```ts
+  const pointCloudData = PointCloudTool.convertVolumeToPointCloudData({
+    data: mesh.data,
+    x: mesh.sizeX,
+    y: mesh.sizeY,
+    z: mesh.sizeZ,
+    min: [box.min.x, box.min.y, box.min.z],
+    max: [box.max.x, box.max.y, box.max.z],
+    threshold: 0
+  });
+
+  volume = new PointCloud(viewer, {
+    name: '粉尘浓度',
+    pointCloudData,
+    pointSize: pointSize.value,
+    colorStops: [
+      {color: '#d18f0a', step: 0.0},
+      {color: '#f23100', step: 0.05},
+      {color: '#6609ff', step: 0.1},
+      {color: '#06ffaa', step: 0.15},
+      {color: '#ce0e59', step: 0.2},
+      {color: '#00f60b', step: 0.3},
+      {color: '#ffef00', step: 0.5},
+      {color: '#fd0000', step: 1.0}
+    ],
+  });
+  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
+  volume.setPointSize(pointSize.value);
+  hasVolume.value = true;
+  bus.triggerSceneTreeUpdate();
+```
+
+- 来源：`packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+
+```ts
+  /**
+   * 创建点云并绑定颜色映射。
+   */
+  cloud = new PointCloud(viewer, {
+    name: "地热温度点云",
+    pointCloudData,
+    pointSize: pointSize.value,
+    colorStops: [
+      {color: "#0000FF", step: 0.0},
+      {color: "#00FF00", step: 0.33},
+      {color: "#FFFF00", step: 0.66},
+      {color: "#FF0000", step: 1.0},
+    ],
+  });
+```
+
+## 函数示例
+
+### `PointCloud.filterByIntensity`
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+
+```ts
+    pointSize: pointSize.value,
+    colorStops: [
+      {color: '#d18f0a', step: 0.0},
+      {color: '#f23100', step: 0.05},
+      {color: '#6609ff', step: 0.1},
+      {color: '#06ffaa', step: 0.15},
+      {color: '#ce0e59', step: 0.2},
+      {color: '#00f60b', step: 0.3},
+      {color: '#ffef00', step: 0.5},
+      {color: '#fd0000', step: 1.0}
+    ],
+  });
+  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
+  volume.setPointSize(pointSize.value);
+  hasVolume.value = true;
+  bus.triggerSceneTreeUpdate();
+};
+```
+
+### `PointCloud.setPointSize`
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+
+```ts
+    colorStops: [
+      {color: '#d18f0a', step: 0.0},
+      {color: '#f23100', step: 0.05},
+      {color: '#6609ff', step: 0.1},
+      {color: '#06ffaa', step: 0.15},
+      {color: '#ce0e59', step: 0.2},
+      {color: '#00f60b', step: 0.3},
+      {color: '#ffef00', step: 0.5},
+      {color: '#fd0000', step: 1.0}
+    ],
+  });
+  volume.filterByIntensity(intensityRange.value[0], intensityRange.value[1]);
+  volume.setPointSize(pointSize.value);
+  hasVolume.value = true;
+  bus.triggerSceneTreeUpdate();
+};
+```
+
+## Demo 参考
+
+### `PointCloud`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+- `packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStrainDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStressDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+- `packages/demo/src/views/GeothermalScene.vue`
+- `packages/demo/src/views/TunnelScene.vue`
+

packages/docs/api/effect/volume/PointCloudTool.md

@@ -0,0 +1,172 @@
+---
+outline: [2, 3]
+---
+
+# PointCloudTool
+
+- 源文件：`packages/sdk/src/effect/volume/PointCloudTool.ts`
+- 文档位置：`packages/docs/api/effect/volume/PointCloudTool.md`
+
+## 接口：`PointCloudData`
+
+- 作用：点云数据结构。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `positions` | `Float32Array` | 是 | 点位坐标数组，格式为 xyzxyz... |
+| `densities` | `Float32Array` | 是 | 点位强度数组，范围为 0~1。 |
+
+## 接口：`PointCloudNoiseOptions`
+
+- 作用：噪声点云生成参数。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `x` | `number` | 否 | X 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `y` | `number` | 否 | Y 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `z` | `number` | 否 | Z 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `size` | `number` | 否 | 统一分辨率，同时设置 x/y/z。 |
+| `spaceSize` | `number` | 否 | 点云空间边长。 |
+| `min` | `[number, number, number]` | 否 | 点云空间最小边界 [x, y, z]。 |
+| `max` | `[number, number, number]` | 否 | 点云空间最大边界 [x, y, z]。 |
+| `threshold` | `number` | 否 | 强度阈值，范围 0~1。 |
+| `noiseScale` | `number` | 否 | 噪声空间缩放。 |
+
+## 接口：`PointCloudGridOptions`
+
+- 作用：规则网格点云参数。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `xRange` | `[number, number]` | 是 | X 轴最小值与最大值。 |
+| `yRange` | `[number, number]` | 是 | Y 轴最小值与最大值。 |
+| `zRange` | `[number, number]` | 是 | Z 轴最小值与最大值。 |
+| `xCount` | `number` | 是 | X 轴采样数量。 |
+| `yCount` | `number` | 是 | Y 轴采样数量。 |
+| `zCount` | `number` | 是 | Z 轴采样数量。 |
+| `density` | `number \| ((x: number, y: number, z: number) => number)` | 否 | 强度值或强度计算函数。 |
+
+## 接口：`PointCloudFromVolumeOptions`
+
+- 作用：体积数据转点云参数。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `data` | `Uint8Array \| Uint16Array \| Float32Array` | 是 | 体素数据，通常来自 VolumeTool（如 Uint8Array）。 |
+| `x` | `number` | 否 | X 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `y` | `number` | 否 | Y 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `z` | `number` | 否 | Z 方向分辨率（可选，如果提供 size 则忽略）。 |
+| `size` | `number` | 否 | 统一分辨率，同时设置 x/y/z。 |
+| `spaceSize` | `number` | 否 | 点云空间边长。 |
+| `min` | `[number, number, number]` | 否 | 点云空间最小边界 [x, y, z]。 |
+| `max` | `[number, number, number]` | 否 | 点云空间最大边界 [x, y, z]。 |
+| `threshold` | `number` | 否 | 强度阈值，范围 0~1，仅保留大于该值的点。 |
+| `sourceMin` | `number` | 否 | 原始数据最小值，默认 0。 |
+| `sourceMax` | `number` | 否 | 原始数据最大值，默认 255（兼容 VolumeTool 输出）。 |
+
+## 类：`PointCloudTool`
+
+- 作用：点云数据工具类。
+
+### 方法
+
+#### `generateNoisePointCloudData(options: PointCloudNoiseOptions): PointCloudData`
+
+- 作用：直接生成噪声点云数据。 生成逻辑基于点云密度： 1. 使用 3D 噪声采样 2. 将噪声值映射到 0~1 强度 3. 根据阈值筛选有效点
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `PointCloudNoiseOptions` | 是 | 生成参数 |
+
+- 出参：`PointCloudData`
+- 返回说明：点云数据
+
+#### `generateGridPointCloud(options: PointCloudGridOptions): PointCloudData`
+
+- 作用：生成规则网格点云数据。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `PointCloudGridOptions` | 是 | 规则网格参数 |
+
+- 出参：`PointCloudData`
+- 返回说明：点云数据
+
+#### `convertVolumeToPointCloudData(options: PointCloudFromVolumeOptions): PointCloudData`
+
+- 作用：将体积数据转换为点云数据。 默认按 VolumeTool 输出规则将 0~255 映射为 0~1 强度，并根据阈值筛选。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `options` | `PointCloudFromVolumeOptions` | 是 | 转换参数 |
+
+- 出参：`PointCloudData`
+- 返回说明：点云数据
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `PointCloudTool` 的构造调用。
+
+## 函数示例
+
+### `PointCloudTool.generateNoisePointCloudData`
+
+- 来源：`packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+
+```ts
+  /**
+   * 生成用于温度点云的点数据。
+   */
+  const pointCloudData = PointCloudTool.generateNoisePointCloudData({
+    min: [-2.5, -2.5, -2.5],
+    max: [2.5, 2.5, 2.5],
+    x: 170,
+    y: 170,
+    z: 170,
+    threshold: 0,
+  });
+```
+
+### `PointCloudTool.convertVolumeToPointCloudData`
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+
+```ts
+  const box = new THREE.Box3().setFromObject(mesh);
+  const pointCloudData = PointCloudTool.convertVolumeToPointCloudData({
+    data: mesh.data,
+    x: mesh.sizeX,
+    y: mesh.sizeY,
+    z: mesh.sizeZ,
+    min: [box.min.x, box.min.y, box.min.z],
+    max: [box.max.x, box.max.y, box.max.z],
+    threshold: 0
+  });
+```
+
+## Demo 参考
+
+### `PointCloudTool`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+- `packages/demo/src/panels/GeothermalScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStrainDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudStressDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/PointCloud/PointCloudTemperatureDisplayPanel.vue`
+

packages/docs/api/effect/volume/VolumeMesh.md

@@ -0,0 +1,314 @@
+---
+outline: [2, 3]
+---
+
+# VolumeMesh
+
+- 源文件：`packages/sdk/src/effect/volume/VolumeMesh.ts`
+- 文档位置：`packages/docs/api/effect/volume/VolumeMesh.md`
+
+## 接口：`ColorStop`
+
+- 作用：ColorStop 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `color` | `string` | 是 | 颜色配置。 |
+| `step` | `number` | 是 | 用于保存 `step` 对应的数据。 |
+
+## 枚举：`VolumeRenderMode`
+
+- 作用：VolumeRenderMode 枚举定义。
+
+| 枚举项 | 值 | 说明 |
+| --- | --- | --- |
+| `EmissionAbsorptionModel` | `0` | 枚举值 `EmissionAbsorptionModel`。 |
+| `MinimumIntensityProjection` | `1` | 枚举值 `MinimumIntensityProjection`。 |
+| `MaximumIntensityProjection` | `2` | 枚举值 `MaximumIntensityProjection`。 |
+
+## 接口：`VolumeRenderingOptions`
+
+- 作用：VolumeRenderingOptions 的结构定义。
+
+### 字段
+
+| 字段名 | 类型 | 必填 | 作用 |
+| --- | --- | --- | --- |
+| `name` | `string` | 是 | 名称。 |
+| `scale` | `number` | 否 | 用于保存 `scale` 对应的数据。 |
+| `size` | `number` | 否 | 尺寸参数。 |
+| `sizeX` | `number` | 否 | 用于保存 `sizeX` 对应的数据。 |
+| `sizeY` | `number` | 否 | 用于保存 `sizeY` 对应的数据。 |
+| `sizeZ` | `number` | 否 | 用于保存 `sizeZ` 对应的数据。 |
+| `data` | `Uint8Array` | 是 | 输入数据。 |
+| `colorStops` | `ColorStop[]` | 否 | 用于保存 `colorStops` 的集合数据。 |
+| `range` | `number` | 否 | 用于保存 `range` 对应的数据。 |
+| `threshold` | `number` | 否 | 阈值配置。 |
+| `steps` | `number` | 否 | 用于保存 `steps` 对应的数据。 |
+| `useSmoothing` | `boolean` | 否 | 用于标记 `useSmoothing` 的启用状态。 |
+| `mode` | `VolumeRenderMode` | 否 | 用于保存 `mode` 对应的数据。 |
+| `clipMode` | `0 \| 1` | 否 | 用于保存 `clipMode` 对应的数据。 |
+| `clipPlane` | `THREE.Vector4` | 否 | 用于保存 `clipPlane` 对应的数据。 |
+| `showWireframe` | `boolean` | 否 | 用于标记 `showWireframe` 的启用状态。 |
+
+## 函数：`isVolumeMesh`
+
+- 作用：执行 is Volume Mesh 相关逻辑。
+
+### 签名
+
+```ts
+function isVolumeMesh(value: any): boolean
+```
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `value` | `any` | 是 | 要写入的新值。 |
+
+- 出参：`boolean`
+- 返回说明：返回布尔结果。
+
+## 类：`VolumeMesh`
+
+- 作用：VolumeMesh 类。
+- 继承/实现：`extends THREE.Mesh<THREE.BufferGeometry, THREE.NodeMaterial>`
+
+### 构造函数
+
+#### `new VolumeMesh(viewer: Viewer, options: VolumeRenderingOptions)`
+
+- 作用：创建 VolumeMesh 实例。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `viewer` | `Viewer` | 是 | 关联的 Viewer 实例。 |
+| `options` | `VolumeRenderingOptions` | 是 | 当前功能对应的配置项。 |
+
+- 出参：`VolumeMesh`
+- 返回说明：返回当前类实例。
+
+### 属性
+
+| 属性名 | 可见性 | 类型 | 作用 |
+| --- | --- | --- | --- |
+| `panelCounter` | `public static` | `number` | 用于保存 `panelCounter` 对应的数据。 |
+| `range` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `range` 对应的数据。 |
+| `threshold` | `public` | `THREE.UniformNode<'float', number>` | 阈值配置。 |
+| `opacity` | `public` | `THREE.UniformNode<'float', number>` | 控制对象或材质的透明度。 |
+| `steps` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `steps` 对应的数据。 |
+| `useSmoothing` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `useSmoothing` 对应的数据。 |
+| `mode` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `mode` 对应的数据。 |
+| `clipMode` | `public` | `THREE.UniformNode<'float', number>` | 用于保存 `clipMode` 对应的数据。 |
+| `clipPlane` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlane` 对应的数据。 |
+| `clipPlaneX` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneX` 对应的数据。 |
+| `clipPlaneY` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneY` 对应的数据。 |
+| `clipPlaneZ` | `public` | `THREE.UniformNode<'vec4', THREE.Vector4>` | 用于保存 `clipPlaneZ` 对应的数据。 |
+| `uniformScale` | `public` | `number` | 用于保存 `uniformScale` 对应的数据。 |
+| `data` | `public` | `Uint8Array` | 输入数据。 |
+| `viewer` | `public` | `Viewer` | 用于保存 `viewer` 对应的数据。 |
+| `volumeTexture` | `public` | `THREE.Data3DTexture` | 用于保存 `volumeTexture` 对应的数据。 |
+| `transferTexture` | `public` | `THREE.Texture` | 用于保存 `transferTexture` 对应的数据。 |
+| `material` | `public` | `THREE.NodeMaterial` | 材质参数。 |
+| `wireframe` | `public` | `ParametricWireframe` | 用于保存 `wireframe` 对应的数据。 |
+| `sizeX` | `public` | `number` | 用于保存 `sizeX` 对应的数据。 |
+| `sizeY` | `public` | `number` | 用于保存 `sizeY` 对应的数据。 |
+| `sizeZ` | `public` | `number` | 用于保存 `sizeZ` 对应的数据。 |
+| `canvas` | `public` | `HTMLCanvasElement` | 用于保存 `canvas` 对应的数据。 |
+| `colorStops` | `public` | `ColorStop[]` | 用于保存 `colorStops` 的集合数据。 |
+| `isVolumeMesh` | `public` | `boolean` | 用于标记 `isVolumeMesh` 的启用状态。 |
+
+### 方法
+
+#### `updateTransferTexture(colorStops: ColorStop[]): void`
+
+- 作用：更新 Transfer Texture。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateVolumeData(data: Uint8Array): void`
+
+- 作用：更新 Volume Data。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `data` | `Uint8Array` | 是 | 输入数据。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `setWireframeVisible(visible: boolean): void`
+
+- 作用：设置 Wireframe Visible。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `visible` | `boolean` | 是 | 是否可见。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `updateTransferTextureCanvas(colorStops: ColorStop[]): void`
+
+- 作用：更新 Transfer Texture Canvas。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createTransferTexture(colorStops: ColorStop[]): THREE.Texture<unknown, THREE.TextureEventMap>`
+
+- 作用：创建 Transfer Texture。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `colorStops` | `ColorStop[]` | 是 | 参数 `colorStops`，类型为 `ColorStop[]`。 |
+
+- 出参：`THREE.Texture<unknown, THREE.TextureEventMap>`
+- 返回说明：返回 `THREE.Texture<unknown, THREE.TextureEventMap>`。
+
+#### `numberToHex(n: number): string`
+
+- 作用：执行 number To Hex 相关逻辑。
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `n` | `number` | 是 | 参数 `n`，类型为 `number`。 |
+
+- 出参：`string`
+- 返回说明：返回字符串结果。
+
+#### `dispose(): void`
+
+- 作用：释放资源并销毁当前实例。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `createDebugPanel(): void`
+
+- 作用：创建 Debug Panel。
+
+- 入参：无
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+## 构造示例
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
+
+```ts
+      rangeMin: 6,
+      rangeMax: 53,
+      baseData: data
+    });
+		// 获取 RAW 后重新遍历体数据，使用 noise3d 重新生成体素值。
+		data = regenerateVolumeDataWithNoise3D(data, size);
+	} catch (error: unknown) {
+		// RAW 加载失败时回退为全 0 数据，保证面板不崩溃。
+		console.error("温度体 RAW 加载失败，已回退为默认空数据：", error);
+		data = new Uint8Array(size * size * size);
+	}
+
+	volume = new VolumeMesh(viewer, {
+		name: "温度",
+		size,
+		scale: 4.99,
+		data: data,
+		mode: VolumeRenderMode.MaximumIntensityProjection,
+		colorStops: [
+			{ color: "#ae1be9", step: 0.0 },
+			{ color: "#0bdb04", step: 0.05 },
+			{ color: "#10e52b", step: 0.1 },
+			{ color: "#1232db", step: 0.15 },
+			{ color: "#0000FF", step: 0.2 },
+			{ color: "#00FFFF", step: 0.33 },
+			{ color: "#FFFF00", step: 0.66 },
+			{ color: "#FF0000", step: 1.0 },
+		],
+	});
+	volume.renderOrder = 3;
+	// volume.material.depthTest = true
+```
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
+
+```ts
+  const volumeData = generatePipeFilledVolumeData(outerBox);
+
+  volume = new VolumeMesh(viewer, {
+    name: '形变场数据',
+    size: VOLUME_SIZE,
+    scale: 4.99,
+    data: volumeData,
+    mode: VolumeRenderMode.MaximumIntensityProjection,
+    colorStops: [
+      // 强度 10（step≈0.04）起始为亮绿色，随强度升高过渡至深绿，热点高强度区映射为红色。
+      {color: "#335b33", step: 0.04},
+      {color: "#00ff00", step: 0.62},
+      {color: "#b31414", step: 0.90},
+      {color: "#FF0000", step: 1.00},
+    ],
+  });
+  volume.renderOrder = 1
+  // volume.material.depthTest = true
+  volume.material.opacity = 0.5
+  hasVolume.value = true;
+  bus.triggerSceneTreeUpdate()
+```
+
+## 函数示例
+
+- 当前 Demo 中没有直接展示 `VolumeMesh` 的公开方法调用。
+
+## Demo 参考
+
+### `VolumeRenderMode`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
+- `packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StressDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/TemperatureDisplayPanel.vue`
+
+### `VolumeMesh`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/DustDisasterLabelPanel.vue`
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
+- `packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StressDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/TemperatureDisplayPanel.vue`
+

packages/docs/api/effect/volume/VolumeNode.md

@@ -0,0 +1,104 @@
+---
+outline: [2, 3]
+---
+
+# VolumeNode
+
+- 源文件：`packages/sdk/src/effect/volume/VolumeNode.ts`
+- 文档位置：`packages/docs/api/effect/volume/VolumeNode.md`
+
+## 接口：`IVoxelMaterialOptions`
+
+- 作用：IVoxelMaterialOptions 的结构定义。
+
+### 定义
+
+```ts
+export interface IVoxelMaterialOptions {
+    readonly colorTexture: NodeElements;
+    readonly texture: NodeElements;
+    readonly range: NodeElements;
+    readonly threshold: NodeElements;
+    readonly opacity: NodeElements;
+    readonly steps: NodeElements;
+    readonly useSmoothing: NodeElements;
+    readonly mode: NodeElements;
+    readonly clipMode: NodeElements;
+    readonly clipPlane: NodeElements;
+    readonly clipPlaneX: NodeElements;
+    readonly clipPlaneY: NodeElements;
+    readonly clipPlaneZ: NodeElements;
+
+    readonly [key: string]: unknown;
+}
+```
+
+## 接口：`IEmissionAbsorptionModelOptions`
+
+- 作用：IEmissionAbsorptionModelOptions 的结构定义。
+
+### 定义
+
+```ts
+export interface IEmissionAbsorptionModelOptions {
+    readonly colorTexture: NodeElements;
+    readonly texture: NodeElements;
+    readonly range: NodeElements;
+    readonly threshold: NodeElements;
+    readonly opacity: NodeElements;
+    readonly steps: NodeElements;
+    readonly useSmoothing: NodeElements;
+    readonly clipMode: NodeElements;
+    readonly clipPlane: NodeElements;
+    readonly clipPlaneX: NodeElements;
+    readonly clipPlaneY: NodeElements;
+    readonly clipPlaneZ: NodeElements;
+
+    readonly [key: string]: unknown;
+}
+```
+
+## 接口：`IMaximumIntensityProjectionOptions`
+
+- 作用：IMaximumIntensityProjectionOptions 的结构定义。
+
+### 定义
+
+```ts
+export interface IMaximumIntensityProjectionOptions {
+    readonly colorTexture: NodeElements;
+    readonly texture: NodeElements;
+    readonly opacity: NodeElements;
+    readonly steps: NodeElements;
+    readonly clipMode: NodeElements;
+    readonly clipPlane: NodeElements;
+    readonly clipPlaneX: NodeElements;
+    readonly clipPlaneY: NodeElements;
+    readonly clipPlaneZ: NodeElements;
+
+    readonly [key: string]: unknown;
+}
+```
+
+## 接口：`IMinimumIntensityProjectionOptions`
+
+- 作用：IMinimumIntensityProjectionOptions 的结构定义。
+
+### 定义
+
+```ts
+export interface IMinimumIntensityProjectionOptions {
+    readonly colorTexture: NodeElements;
+    readonly texture: NodeElements;
+    readonly opacity: NodeElements;
+    readonly steps: NodeElements;
+    readonly clipMode: NodeElements;
+    readonly clipPlane: NodeElements;
+    readonly clipPlaneX: NodeElements;
+    readonly clipPlaneY: NodeElements;
+    readonly clipPlaneZ: NodeElements;
+
+    readonly [key: string]: unknown;
+}
+```
+

packages/docs/api/effect/volume/VolumeTool.md

@@ -0,0 +1,213 @@
+---
+outline: [2, 3]
+---
+
+# VolumeTool
+
+- 源文件：`packages/sdk/src/effect/volume/VolumeTool.ts`
+- 文档位置：`packages/docs/api/effect/volume/VolumeTool.md`
+
+## 类：`VolumeTool`
+
+- 作用：体积数据工具类
+
+### 方法
+
+#### `remap(value: number, fromMin: number, fromMax: number, toMin = 0, toMax = 1): number`
+
+- 作用：线性映射：将值从输入范围映射到输出范围
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `value` | `number` | 是 | 输入值 |
+| `fromMin` | `number` | 是 | 输入范围最小值 |
+| `fromMax` | `number` | 是 | 输入范围最大值 |
+| `toMin` | `number` | 否 | 输出范围最小值（默认0） |
+| `toMax` | `number` | 否 | 输出范围最大值（默认1） |
+
+- 出参：`number`
+- 返回说明：映射后的值
+
+#### `generateVolumeData({ x, y, z, size = 256, rangeMin, rangeMax, }: { x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }): Uint8Array<ArrayBufferLike>`
+
+- 作用：生成3D体积数据，使用Simplex噪声算法
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                   x,                                   y,                                   z,                                   size = 256,                                   rangeMin,                                   rangeMax,                               }` | `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }` | 是 | 参数 `{                                   x,                                   y,                                   z,                                   size = 256,                                   rangeMin,                                   rangeMax,                               }`，类型为 `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; }`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+#### `generateVolumeDataWithClearLayers({ x, y, z, size = 256, rangeMin, rangeMax, clearLayers = 0 }: { x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }): Uint8Array<ArrayBufferLike>`
+
+- 作用：生成3D体积数据并清除外层，使用Simplex噪声算法
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                                  x,                                                  y,                                                  z,                                                  size = 256,                                                  rangeMin,                                                  rangeMax,                                                  clearLayers = 0                                              }` | `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }` | 是 | 参数 `{                                                  x,                                                  y,                                                  z,                                                  size = 256,                                                  rangeMin,                                                  rangeMax,                                                  clearLayers = 0                                              }`，类型为 `{ x?: number; y?: number; z?: number; size?: number; rangeMin: number; rangeMax: number; clearLayers?: number; }`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+#### `generateNoiseAroundPoints({ size = 256, worldOrigin, worldSize, points, rangeMin, rangeMax }: { size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }): Uint8Array<ArrayBufferLike>`
+
+- 作用：在指定世界空间坐标周围生成3D噪声值
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                          size = 256,                                          worldOrigin,                                          worldSize,                                          points,                                          rangeMin,                                          rangeMax                                      }` | `{ size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }` | 是 | 参数 `{                                          size = 256,                                          worldOrigin,                                          worldSize,                                          points,                                          rangeMin,                                          rangeMax                                      }`，类型为 `{ size?: number; worldOrigin: [number, number, number]; worldSize: number; points: Array<{ position: [number, number, number]; radius: number, density: number }>; rangeMin: number; rangeMax: number; }`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+#### `clearOuterLayers({ data, width, height, depth, layers }: { data: Uint8Array; width: number; height: number; depth: number; layers: number; }): void`
+
+- 作用：清除体素空间最外层的数据，将其设置为0
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                 data,                                 width,                                 height,                                 depth,                                 layers                             }` | `{ data: Uint8Array; width: number; height: number; depth: number; layers: number; }` | 是 | 参数 `{                                 data,                                 width,                                 height,                                 depth,                                 layers                             }`，类型为 `{ data: Uint8Array; width: number; height: number; depth: number; layers: number; }`。 |
+
+- 出参：`void`
+- 返回说明：无返回值。
+
+#### `generateRandomVolumeInBox({ outerBox, innerBox, size = 256, rangeMin = 0, rangeMax = 255 }: { outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }): Uint8Array<ArrayBufferLike>`
+
+- 作用：在内部包围盒中生成随机体积数据
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                          outerBox,                                          innerBox,                                          size = 256,                                          rangeMin = 0,                                          rangeMax = 255                                      }` | `{ outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }` | 是 | 参数 `{                                          outerBox,                                          innerBox,                                          size = 256,                                          rangeMin = 0,                                          rangeMax = 255                                      }`，类型为 `{ outerBox: THREE.Box3; innerBox: THREE.Box3; size?: number; rangeMin?: number; rangeMax?: number; }`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+#### `generateRandomVolumeAroundPipe({ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255 }: TRandomVolumeAroundPipeOptions): Uint8Array<ArrayBufferLike>`
+
+- 作用：在管道周围生成随机体积数据
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                               outerBox,                                               pipeStart,                                               pipeEnd,                                               pipeRadius,                                               size = 256,                                               rangeMin = 0,                                               rangeMax = 255                                           }` | `TRandomVolumeAroundPipeOptions` | 是 | 参数 `{                                               outerBox,                                               pipeStart,                                               pipeEnd,                                               pipeRadius,                                               size = 256,                                               rangeMin = 0,                                               rangeMax = 255                                           }`，类型为 `TRandomVolumeAroundPipeOptions`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+#### `generateRandomVolumeAroundPipeWithBaseData({ outerBox, pipeStart, pipeEnd, pipeRadius, size = 256, rangeMin = 0, rangeMax = 255, baseData }: TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }): Uint8Array<ArrayBufferLike>`
+
+- 作用：在已有体积数据基础上按管道规则继续生成数据
+
+- 入参：
+
+| 参数名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `{                                                           outerBox,                                                           pipeStart,                                                           pipeEnd,                                                           pipeRadius,                                                           size = 256,                                                           rangeMin = 0,                                                           rangeMax = 255,                                                           baseData                                                       }` | `TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }` | 是 | 参数 `{                                                           outerBox,                                                           pipeStart,                                                           pipeEnd,                                                           pipeRadius,                                                           size = 256,                                                           rangeMin = 0,                                                           rangeMax = 255,                                                           baseData                                                       }`，类型为 `TRandomVolumeAroundPipeOptions & { baseData: Uint8Array; }`。 |
+
+- 出参：`Uint8Array<ArrayBufferLike>`
+- 返回说明：Uint8Array格式的体积数据
+
+## 构造示例
+
+- 当前 Demo 中没有直接展示 `VolumeTool` 的构造调用。
+
+## 函数示例
+
+### `VolumeTool.remap`
+
+- 来源：`packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
+
+```ts
+	const mappedZList = new Float32Array(VOLUME_SIZE);
+
+	for (let x = 0; x < VOLUME_SIZE; x++) {
+		mappedXList[x] = VolumeTool.remap(x, 0, VOLUME_SIZE - 1, outerBox.min.x, outerBox.max.x);
+	}
+	for (let y = 0; y < VOLUME_SIZE; y++) {
+		mappedYList[y] = VolumeTool.remap(y, 0, VOLUME_SIZE - 1, outerBox.min.y, outerBox.max.y);
+	}
+	for (let z = 0; z < VOLUME_SIZE; z++) {
+		mappedZList[z] = VolumeTool.remap(z, 0, VOLUME_SIZE - 1, outerBox.min.z, outerBox.max.z);
+	}
+```
+
+### `VolumeTool.generateVolumeData`
+
+- 来源：`packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
+
+```ts
+  const viewer = bus.getViewer();
+  const data = VolumeTool.generateVolumeData({size: 256, rangeMin: 10, rangeMax: 50});
+
+  volume = new VolumeMesh(viewer, {
+    name: "应变场",
+    size: 256,
+    data,
+    mode: VolumeRenderMode.EmissionAbsorptionModel,
+    clipMode: bus.clippingMode === 'single' ? 1 : 0,
+    scale: 4.99,
+    colorStops: [
+      {color: '#00FFFF', step: 0.2},
+      {color: '#0080FF', step: 0.5},
+      {color: '#8000FF', step: 0.7},
+      {color: '#FF00FF', step: 1.0},
+    ],
+  });
+  volume.renderOrder = 1
+  // 如果加载面面板已打开，则启用体材质深度测试
+  if (bus.getLoadSurfaceExists && bus.getLoadSurfaceExists()) {
+```
+
+### `VolumeTool.generateRandomVolumeAroundPipeWithBaseData`
+
+- 来源：`packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
+
+```ts
+	try {
+		// 与 StressDisplayPanel 一致：通过 resources.loadRawData 加载 RAW。
+		data = await getTemperatureVolumeData();
+    data = VolumeTool.generateRandomVolumeAroundPipeWithBaseData({
+      outerBox: outerBox,
+      pipeStart: new THREE.Vector3(-0.11, 0, -2.505),
+      pipeEnd: new THREE.Vector3(-0.11, 0, -1.4),
+      pipeRadius: 0.25,
+      size: 256,
+      rangeMin: 6,
+      rangeMax: 53,
+      baseData: data
+    });
+		// 获取 RAW 后重新遍历体数据，使用 noise3d 重新生成体素值。
+		data = regenerateVolumeDataWithNoise3D(data, size);
+	} catch (error: unknown) {
+		// RAW 加载失败时回退为全 0 数据，保证面板不崩溃。
+		console.error("温度体 RAW 加载失败，已回退为默认空数据：", error);
+		data = new Uint8Array(size * size * size);
+	}
+```
+
+## Demo 参考
+
+### `VolumeTool`
+
+以下示例文件中可以看到该 API 的实际调用方式：
+
+- `packages/demo/src/disasterFormationPanel/GoldMineScene/TemperaturePanel.vue`
+- `packages/demo/src/panels/GeothermalScene/DustConcentrationPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StrainDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/StressDisplayPanel.vue`
+- `packages/demo/src/panels/TunnelScene/FieldData/TemperatureDisplayPanel.vue`
+