Skip to content

Models Module

本模块定义了模型元数据和运行时条目的数据层。它包括类型化接口、特定格式资产的包装器，以及用于在 Visionary 内部管理模型的实用工具。该模块提供了一个统一的数据结构，适用于所有支持的格式：高斯 Splatting 格式 (PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY)、ONNX 动态模型和 FBX 网格文件。

概览

  • ModelEntry – 带有 pointCloud 引用的完整运行时表示
  • ModelInfo – 用于 UI 层的轻量级、只读快照（React 渲染安全）
  • FBXModelWrapper – 带有动画支持和 Timeline 集成的 Three.js FBX 资产适配器
  • 统一类型 – 跨所有高斯格式、ONNX 和 FBX 的统一类型

快速开始

import { ModelEntry, ModelInfo, ModelType } from 'src/models';
import { PointCloud } from 'src/point_cloud';

// 创建一个 PLY model entry
const entry: ModelEntry = {
  id: 'hero',
  name: 'Hero Asset',
  visible: true,
  pointCloud: new PointCloud(device, gaussianData),
  pointCount: 1_000_000,
  isDynamic: false,
  modelType: 'ply',
  colorMode: 'sh',
  colorChannels: 48,
};

// 创建用于 UI 的简化信息
const info: ModelInfo = {
  id: entry.id,
  name: entry.name,
  visible: entry.visible,
  pointCount: entry.pointCount,
  isDynamic: entry.isDynamic,
  modelType: entry.modelType,
  colorMode: entry.colorMode,
  colorChannels: entry.colorChannels,
};

支持的模型类型

type ModelType = 
  | 'ply' | 'spz' | 'ksplat' | 'splat' | 'sog' | 'compressed.ply'  // 高斯格式
  | 'onnx'                                                          // 动态 ONNX
  | 'fbx';                                                          // FBX 网格

亮点

  • 统一数据格式 – 所有模型类型（高斯、ONNX、FBX）的一致接口
  • 类型安全 – 针对 ModelType 使用联合类型的严格 TypeScript 契约
  • 动态模型支持 – 通过 DynamicPointCloud 处理流式 ONNX 点云
  • 颜色元数据 – 显式捕获 SH 与 RGB 颜色模式
  • FBX 动画支持 – FBXModelWrapper 实现了 ITimelineTarget 以进行 timeline 控制
  • 格式无关 – 相同的接口适用于 PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY, ONNX 和 FBX

架构

该模块由接口驱动，具有清晰的分离：

  1. ModelEntry – 运行时状态和对 pointCloud/object3D 的引用
  2. ModelInfo – 用于 UI 面板和列表的轻量级快照（无 pointCloud 引用）
  3. Wrappers – 特定格式的助手（带有动画支持的 FBXModelWrapper）

数据结构

interface ModelEntry {
  id: string;                                    // 唯一标识符
  name: string;                                   // 显示名称
  visible: boolean;                               // 渲染可见性
  pointCloud: PointCloud | DynamicPointCloud | FBXModelWrapper;  // 特定格式的数据
  pointCount: number;                             // 统计信息
  isDynamic: boolean;                             // 支持动态更新
  modelType: ModelType;                           // 源类型 (ply, spz, onnx, fbx 等)
  colorMode?: 'sh' | 'rgb';                       // 颜色编码
  colorChannels?: number;                         // 颜色通道数
}

依赖

  • Point Cloud Classes – PointCloud (静态), DynamicPointCloud (ONNX 驱动)
  • Timeline Module – 用于动画控制的 ITimelineTarget 接口
  • Three.js – 用于 FBX 支持的 THREE.Group, THREE.AnimationMixer, THREE.AnimationClip
  • 特定格式 Loaders – 由 managers 使用以创建 ModelEntry 实例

相关文档

  • Architecture – 接口图、所有权规则和 FBX 包装器说明。
  • API Reference – 类型定义、辅助工具和 timeline 钩子。
  • IO Module – 解释加载器如何填充 ModelEntry 结构。
  • Point Cloud Module – 详述每个模型引用的 GPU 对象。
  • Timeline Module – 展示动态/FBX 条目如何与播放控制集成。
  • Manager Module – 说明如何在整个应用程序中跟踪模型数据。