feat(all): 更新文档

2026-05-06 22:16:20 +08:00
parent 8a1436d3a8
commit d2329a6854
14 changed files with 233574 additions and 133 deletions
@@ -7,6 +7,19 @@ outline: [2, 3]
 - 源文件：`packages/sdk/src/effect/FlowParticles.ts`
 - 文档位置：`packages/docs/api/effect/FlowParticles.md`

+## 地热注采流动说明
+
+`FlowParticles` 在地热注采场景中支持两类模式：
+
+- `bidirectional`：双向对向流动，左右侧粒子分别向中段推进。
+- `single`：单向流动，支持按左右流量差异发射“补差粒子”，并在中段附近显隐以模拟注采不均衡。
+
+最新业务逻辑包含：
+
+- 单向模式的左右段隐藏特例（某侧速度为 0 时，该侧默认隐藏）。
+- 基于几何投影的显隐判定，避免仅按参数 `t` 带来的路径不均问题。
+- 右侧流量高于左侧时，自动发射补差粒子。
+
 ## 接口：`FlowParticlesGPUOptions`

 - 作用：流动粒子配置。
@@ -19,6 +32,11 @@ outline: [2, 3]
 | `endPipe` | `ParametricPipe` | 是 | 结束管道。 |
 | `particleCount` | `number` | 否 | 粒子总数量。 |
 | `speedMultiplier` | `number` | 否 | 粒子流动速度倍率。 |
+| `flowMode` | `"single" \| "bidirectional"` | 否 | 流动模式，默认 `single`。 |
+| `leftFlowRate` | `number` | 否 | 左侧流量权重。 |
+| `rightFlowRate` | `number` | 否 | 右侧流量权重。 |
+| `leftSpeedMultiplier` | `number` | 否 | 左侧速度倍率。 |
+| `rightSpeedMultiplier` | `number` | 否 | 右侧速度倍率。 |
 | `particleSize` | `number` | 否 | 粒子半径。 |
 | `heatingThreshold` | `number` | 否 | 加热阈值。 |
 | `flowPathCount` | `number` | 否 | 流动路径数量。 |
@@ -65,6 +83,11 @@ outline: [2, 3]
 | `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` 对应的数据。 |
@@ -104,6 +127,34 @@ outline: [2, 3]
 - 出参：`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`

 - 作用：设置冻结概率。
@@ -232,8 +283,13 @@ outline: [2, 3]
    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: [
@@ -287,6 +343,15 @@ outline: [2, 3]
 };
 ```

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

 - 来源：`packages/demo/src/panels/GeothermalScene/GeothermalInjectionProductionPanel.vue`
@@ -0,0 +1,111 @@
+---
+outline: [2, 3]
+---
+
+# VtkStructuredPointsParser
+
+- 源文件：`packages/sdk/src/effect/volume/vtk/VtkStructuredPointsParser.ts`
+- 文档位置：`packages/docs/api/effect/volume/VtkStructuredPointsParser.md`
+
+## 类：`VtkStructuredPointsParser`
+
+- 作用：解析 legacy VTK 体数据，提取指定分量，返回可直接用于体渲染的数据和元信息。
+
+## 支持范围
+
+- 支持 `ASCII` / `BINARY` 编码自动识别。
+- 支持 `DATASET STRUCTURED_POINTS`（binary）。
+- 支持 `ASCII UNSTRUCTURED_GRID` 规则网格转体数据。
+- 支持从 `CELL_DATA` 或 `POINT_DATA` 自动解析标量来源。
+
+## 相关类型
+
+### `IVtkParseFromUrlOptions`
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 远程 VTK 文件地址。 |
+| `componentIndex` | `number` | 是 | 要提取的分量索引，从 0 开始。 |
+| `fileName` | `string` | 否 | 可选文件名，默认从 URL 推断。 |
+| `requestInit` | `RequestInit` | 否 | `fetch` 附加参数。 |
+
+### `IVtkParseFromBufferOptions`
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `buffer` | `ArrayBuffer \| Uint8Array` | 是 | VTK 原始二进制内容。 |
+| `componentIndex` | `number` | 是 | 要提取的分量索引，从 0 开始。 |
+| `fileName` | `string` | 否 | 可选文件名，默认 `unknown.vtk`。 |
+
+### `IVtkParsedComponentResult`
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `metadata` | `IVtkStructuredPointsMetadata` | 体数据元信息。 |
+| `componentIndex` | `number` | 当前提取的分量索引。 |
+| `valueRange` | `[number, number]` | 当前分量值域。 |
+| `values` | `Float32Array` | 当前分量一维标量数组。 |
+
+### `IVtkStructuredPointsMetadata`
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `fileName` | `string` | 文件名。 |
+| `fileSize` | `number` | 文件字节数。 |
+| `sourceDimensions` | `TVector3` | 原始点维度。 |
+| `cellDimensions` | `TVector3` | 渲染采样维度。 |
+| `spacing` | `TVector3` | 网格间距。 |
+| `sourceOrigin` | `TVector3` | 原始原点。 |
+| `pointOrigin` | `TVector3` | 体素中心原点。 |
+| `scalarName` | `string` | 标量名称。 |
+| `scalarType` | `string` | 标量类型描述。 |
+| `componentCount` | `number` | 标量分量数。 |
+| `cellCount` | `number` | 元组数量（通常对应体素数）。 |
+| `scalarSource` | `"cell" \| "point"` | 标量来源。 |
+
+## 方法
+
+### `parseFromUrl(options: IVtkParseFromUrlOptions): Promise<IVtkParsedComponentResult>`
+
+- 作用：从 URL 下载并解析 VTK 数据。
+- 典型错误：下载失败、编码不支持、数据集类型不支持、分量越界。
+
+### `parseFromBuffer(options: IVtkParseFromBufferOptions): IVtkParsedComponentResult`
+
+- 作用：从内存缓冲区解析 VTK 数据。
+- 适用场景：文件上传、自定义网络层、离线缓存解析。
+
+## 使用示例
+
+```ts
+import { VtkStructuredPointsParser, VolumeMesh, VolumeRenderMode } from "@deep/engine";
+
+const parser = new VtkStructuredPointsParser();
+const parsed = await parser.parseFromUrl({
+    url: "/model/vtk/stress_cells_256.vtk",
+    componentIndex: 0,
+});
+
+const [minValue, maxValue] = parsed.valueRange;
+const values = parsed.values;
+
+const voxels = new Uint8Array(values.length);
+const denominator = Math.max(maxValue - minValue, Number.EPSILON);
+
+for (let i = 0; i < values.length; i += 1) {
+    const normalized = (values[i] - minValue) / denominator;
+    voxels[i] = Math.round(Math.max(0, Math.min(1, normalized)) * 255);
+}
+
+const volume = new VolumeMesh(voxels, {
+    shape: parsed.metadata.cellDimensions,
+    mode: VolumeRenderMode.EmissionAbsorptionModel,
+});
+```
+
+## 注意事项
+
+- `componentIndex` 必须在 `[0, componentCount - 1]` 范围内。
+- `UNSTRUCTURED_GRID` 仅支持规则网格输入，非规则点云会抛错。
+- Binary 读取按大端浮点处理（legacy VTK 约定）。
+- 数据值域映射通常需要在业务层完成（如映射到 `Uint8Array` 供体渲染）。