Models模块

This module defines the data layer for model metadata and runtime entries. It includes typed interfaces, wrappers for format-specific assets, and utilities for managing models inside Visionary. The module provides a unified data structure that works across all supported formats: Gaussian Splatting formats (PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY), ONNX dynamic models, and FBX mesh files.

Overview

• ModelEntry – full runtime representation with pointCloud reference
• ModelInfo – lightweight, read-only snapshot for UI layers (safe for React rendering)
• FBXModelWrapper – adapter for Three.js FBX assets with animation support and Timeline integration
• Unified typing across all Gaussian formats, ONNX, and FBX

Quick Start

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

// Create a 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,
};

// Create simplified info for 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,
};

Supported Model Types

type ModelType = 
  | 'ply' | 'spz' | 'ksplat' | 'splat' | 'sog' | 'compressed.ply'  // Gaussian formats
  | 'onnx'                                                          // Dynamic ONNX
  | 'fbx';                                                          // FBX mesh

Highlights

• Unified Data Format – consistent interfaces for all model types (Gaussian, ONNX, FBX)
• Type Safety – strict TypeScript contracts with union types for ModelType
• Dynamic Model Support – handles streaming ONNX point clouds via DynamicPointCloud
• Color Metadata – SH vs RGB color modes captured explicitly
• FBX Animation Support – FBXModelWrapper implements ITimelineTarget for timeline control
• Format Agnostic – same interface works for PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY, ONNX, and FBX

Architecture

The module is interface-driven with clear separation:

1. ModelEntry – runtime state and references to pointCloud/object3D
2. ModelInfo – lightweight snapshot for UI panels and lists (no pointCloud reference)
3. Wrappers – format-specific helpers (FBXModelWrapper with animation support)

Data Structure

interface ModelEntry {
  id: string;                                    // Unique identifier
  name: string;                                   // Display name
  visible: boolean;                               // Render visibility
  pointCloud: PointCloud | DynamicPointCloud | FBXModelWrapper;  // Format-specific data
  pointCount: number;                             // Statistics
  isDynamic: boolean;                             // Dynamic updates supported
  modelType: ModelType;                           // Source type (ply, spz, onnx, fbx, etc.)
  colorMode?: 'sh' | 'rgb';                       // Color encoding
  colorChannels?: number;                         // Number of color channels
}

Dependencies

• Point Cloud Classes – PointCloud (static), DynamicPointCloud (ONNX-driven)
• Timeline Module – ITimelineTarget interface for animation control
• Three.js – THREE.Group, THREE.AnimationMixer, THREE.AnimationClip for FBX support
• Format-Specific Loaders – Used by managers to create ModelEntry instances

Related Docs

• Architecture – Interface diagrams, ownership rules, and FBX wrapper notes.
• API Reference – Type definitions, helper utilities, and timeline hooks.
• IO Module – Explains how loaders populate ModelEntry structures.
• Point Cloud Module – Details the GPU objects referenced by each model.
• Timeline Module – Shows how dynamic/FBX entries integrate with playback control.
• Manager Module – Illustrates how model data is tracked across the app.