112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
---
|
||
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` 供体渲染）。
|