deep-engine-demo/packages/docs/api/effect/volume/VtkStructuredPointsParser.md

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 数据。
• 适用场景：文件上传、自定义网络层、离线缓存解析。

使用示例

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