VTK Geometry Loader

一个轻量级的VTK/VTP文件加载器，用于解析ArrayBuffer数据并返回几何体、颜色和材质信息。

功能特性

• 🚀 支持VTK和VTP格式文件
• 🎨 自动提取和处理颜色数据
• 📐 自动计算法向量和包围盒
• 🔧 灵活的材质配置选项
• 📊 多种颜色映射方案
• 💪 完整的TypeScript支持
• 🎯 轻量级，专注于几何数据解析

安装

npm install vtk-geometry-loader

基本使用

import { loadVTKGeometry } from 'vtk-geometry-loader';

// 从文件输入获取ArrayBuffer
const fileInput = document.getElementById('fileInput') as HTMLInputElement;
fileInput.addEventListener('change', async (event) => {
  const file = (event.target as HTMLInputElement).files?.[0];
  if (!file) return;

  const arrayBuffer = await file.arrayBuffer();
  const fileExtension = file.name.split('.').pop()?.toLowerCase();

  try {
    const result = await loadVTKGeometry(arrayBuffer, fileExtension);
    console.log('几何数据:', result.geometry);
    console.log('材质信息:', result.material);
    console.log('文件信息:', result.fileInfo);
    console.log('包围盒:', result.boundingBox);
  } catch (error) {
    console.error('加载失败:', error);
  }
});

高级用法

自定义加载选项

import { VTKGeometryLoader, VTKLoaderOptions } from 'vtk-geometry-loader';

const options: VTKLoaderOptions = {
  computeNormals: true,        // 自动计算法向量
  extractColors: true,         // 提取颜色数据
  colorScheme: 'viridis',      // 颜色映射方案: 'rainbow' | 'viridis' | 'plasma' | 'discrete'
  preferredMaterial: 'phong',  // 材质类型: 'basic' | 'phong' | 'standard'
  enableSmoothing: false,      // 启用几何体平滑
  smoothingFactor: 0.1,        // 平滑强度
  doubleSide: true,           // 双面渲染
  defaultColor: 0x808080      // 默认颜色
};

const result = await VTKGeometryLoader.load(arrayBuffer, 'vtk', options);

与Three.js集成

import * as THREE from 'three';
import { loadVTKGeometry } from 'vtk-geometry-loader';

async function createThreeJSMesh(arrayBuffer: ArrayBuffer, fileExtension: string) {
  const result = await loadVTKGeometry(arrayBuffer, fileExtension);

  // 创建Three.js几何体
  const geometry = new THREE.BufferGeometry();
  geometry.setAttribute('position', new THREE.BufferAttribute(result.geometry.positions, 3));

  if (result.geometry.indices) {
    geometry.setIndex(new THREE.BufferAttribute(result.geometry.indices, 1));
  }

  if (result.geometry.normals) {
    geometry.setAttribute('normal', new THREE.BufferAttribute(result.geometry.normals, 3));
  }

  if (result.geometry.colors) {
    geometry.setAttribute('color', new THREE.BufferAttribute(result.geometry.colors, 3));
  }

  // 创建材质
  const material = new THREE.MeshPhongMaterial({
    color: result.material.color,
    vertexColors: result.material.hasVertexColors,
    side: THREE.DoubleSide
  });

  // 创建网格
  const mesh = new THREE.Mesh(geometry, material);

  return {
    mesh,
    boundingBox: result.boundingBox,
    fileInfo: result.fileInfo
  };
}

错误处理

import { VTKLoaderError } from 'vtk-geometry-loader';

try {
  const result = await loadVTKGeometry(arrayBuffer, fileExtension);
  // 处理成功结果
} catch (error) {
  if (error instanceof VTKLoaderError) {
    switch (error.code) {
      case 'EMPTY_DATA':
        console.error('文件数据为空');
        break;
      case 'UNSUPPORTED_FORMAT':
        console.error('不支持的文件格式');
        break;
      case 'PARSE_ERROR':
        console.error('文件解析失败');
        break;
      default:
        console.error('未知错误:', error.message);
    }
  } else {
    console.error('其他错误:', error);
  }
}

API 参考

主要函数

loadVTKGeometry(data, fileExtension, options?)

加载VTK/VTP文件并返回解析结果。

参数：

• data: ArrayBuffer - VTK/VTP文件的二进制数据
• fileExtension: string - 文件扩展名 ('vtk' 或 'vtp')
• options?: VTKLoaderOptions - 可选的加载配置

返回： Promise<VTKLoaderResult>

isSupportedFormat(fileExtension)

检查文件格式是否受支持。

参数：

• fileExtension: string - 文件扩展名

返回： boolean

数据类型

VTKLoaderResult

interface VTKLoaderResult {
  geometry: VTKGeometry;      // 几何数据
  material: VTKMaterial;      // 材质属性
  fileInfo: VTKFileInfo;      // 文件信息
  boundingBox: {              // 包围盒
    min: [number, number, number];
    max: [number, number, number];
    size: [number, number, number];
    center: [number, number, number];
  };
}

VTKGeometry

interface VTKGeometry {
  positions: Float32Array;    // 顶点位置 [x1,y1,z1, x2,y2,z2, ...]
  indices?: Uint32Array;      // 顶点索引（定义三角形面）
  normals?: Float32Array;     // 法向量 [nx1,ny1,nz1, ...]
  colors?: Float32Array;      // 顶点颜色 [r1,g1,b1, ...] (0-1范围)
  uvs?: Float32Array;         // 纹理坐标 [u1,v1, u2,v2, ...]
}

VTKMaterial

interface VTKMaterial {
  type: 'basic' | 'phong' | 'standard';
  color: number;              // 基础颜色(16进制)
  opacity: number;            // 透明度(0-1)
  transparent: boolean;       // 是否透明
  wireframe: boolean;         // 是否线框模式
  hasVertexColors: boolean;   // 是否有顶点颜色
  specular?: number;          // 镜面反射颜色
  shininess?: number;         // 光泽度
}

支持的颜色映射

• rainbow - 彩虹色映射（默认）
• viridis - Viridis色映射
• plasma - Plasma色映射
• discrete - 离散颜色映射（适合材料ID等）

浏览器兼容性

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

依赖

• @kitware/vtk.js - VTK文件解析核心库

许可证

MIT

贡献

欢迎提交Issue和Pull Request！

变更日志

v1.0.0

• 初始版本
• 支持VTK和VTP格式
• 完整的TypeScript支持
• 多种颜色映射方案