---
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` 供体渲染）。