App Module API Reference

This reference enumerates every public surface exposed by the App module and the managers it coordinates.

App class

The App class is a slim coordinator. It wires UI callbacks, hands logic off to managers, and owns the render loop lifecycle.

constructor()

Creates DOM bindings, manager instances, and UI callbacks. GPU resources are not allocated yet.

Initialized Managers: - ModelManager (max 10000 models) - CameraManager - AnimationManager - RenderLoop - FileLoader (with loading callbacks) - ONNXManager - UIController (with UI callbacks)

init(): Promise

Initializes the complete application:

Initializes ORT (ONNX Runtime) environment
Initializes WebGPU via initWebGPU_onnx (with ORT integration fallback)
Creates GaussianRenderer and ensures sorter is ready
Initializes camera and sets default controller (FPS)
Binds UI event handlers
Sets up resize handler
Initializes RenderLoop with GPU context and callbacks
Starts the render loop

Throws when: - Canvas element is missing - WebGPU initialization fails (shows banner instead)

Fallback Behavior: - If ORT integration fails, falls back to standalone WebGPU - If WebGPU is unavailable, shows error banner and exits gracefully

Model Loading

Gaussian Formats (Unified): - loadGaussian(input: File | string, options?: LoadOptions): Promise<void> – Unified loader for all Gaussian formats (PLY, SPZ, KSplat, SPLAT, SOG, compressed PLY). Auto-detects format or accepts gaussianFormat option.

Format-Specific Loaders: - loadPLY(input: File | string, options?: LoadOptions): Promise<void> – Load PLY format (deprecated, use loadGaussian instead). - loadSPZ(input: File | string, options?: LoadOptions): Promise<void> – Load SPZ format specifically. - loadKSplat(input: File | string, options?: LoadOptions): Promise<void> – Load KSplat format specifically. - loadSplat(input: File | string, options?: LoadOptions): Promise<void> – Load SPLAT format specifically. - loadSOG(input: File | string, options?: LoadOptions): Promise<void> – Load SOG format specifically.

ONNX Models: - loadONNXModel(modelPath: string, name?: string, staticInference?: boolean): Promise<void> – Loads ONNX models through ONNXManager. staticInference=false enables per-frame GPU inference. - loadONNXModelPublic(modelPath?: string, name?: string): Promise<void> – Public alias for integrations.

Sample Files: - loadSample(filename: string): Promise<void> – Loads assets from /assets or configured URL. Auto-detects format.

File Support: - getSupportedFormats(): { gaussian: string[], onnx: string[], models: string[], all: string[] } – Returns all supported file extensions. - isFileSupported(fileName: string): boolean – Checks if a file format is supported.

Internal (Private): - loadFile(file: File): Promise<void> – Internal method that detects file type and routes to appropriate loader.

LoadOptions Interface:

interface LoadOptions {
  /** Expected file type for validation */
  expectedType?: 'gaussian' | 'onnx' | 'model';
  /** Specific Gaussian format (auto-detected if not provided) */
  gaussianFormat?: GaussianFormat;
  /** Static inference for ONNX models */
  staticInference?: boolean;
  /** Enable debug logging */
  debugLogging?: boolean;
}

Note: ONNX ingestion intentionally bypasses FileLoader; it keeps the ONNX workflow GPU-only.

Camera & controls

resetCamera(): void
switchController(type: 'orbit' | 'fps'): void – Orbit mode centers on the visible model bounds when they exist.
getCameraMatrix(): mat4
getProjectionMatrix(): mat4

Rendering state

setGaussianScale(scale: number): void
setBackgroundColor(color: [number, number, number, number]): void
getGaussianScale(): number
getBackgroundColor(): [number, number, number, number]

Models & Diagnostics

Model Queries: - getModels(): ModelInfo[] – Returns lightweight metadata for UI display (safe for React rendering). - getFullModels(): ModelEntry[] – Returns all model entries with full pointCloud references (for debugging/testing). - getModelWithPointCloud(modelType: 'ply' | 'onnx' | 'fbx', id?: string): ModelEntry | null – Gets a specific model entry with full pointCloud reference.

Debug Information: - getDebugInfo(): any – Returns aggregated snapshot across all managers:

{
  app: { initialized, canvas, supportedFormats },
  models: { count, capacity, totalPoints, visiblePoints },
  camera: CameraManager.getDebugInfo(),
  animation: AnimationManager.getDebugInfo(),
  renderLoop: RenderLoop.getDebugInfo(),
  onnx: { hasModels, modelCount, performanceStats }
}

Dynamic Animation Control

controlDynamicAnimation(action: 'start' | 'pause' | 'resume' | 'stop', speed?: number): void – Global control for all dynamic models.
setDynamicAnimationTime(time: number): void – Set animation time for dynamic models.
getDynamicPerformanceStats(): Array<{ modelName: string, stats: any }> – Get performance statistics for dynamic models.

Manager Access (Advanced)

Direct access to manager instances for advanced usage:

getModelManager(): ModelManager – Access to model storage and tracking.
getONNXManager(): ONNXManager – Access to ONNX model management.
getCameraManager(): CameraManager – Access to camera and controller management.
getAnimationManager(): AnimationManager – Access to animation and dynamic update logic.
getRenderLoop(): RenderLoop – Access to render loop and frame cycle.

Note: These methods are intended for advanced use cases. Most operations should go through the App public API.

Manager Classes

The App module uses a manager-based architecture. While most operations should go through the App class, managers can be accessed directly for advanced use cases.

ModelManager

Central repository for all loaded 3D content.

Path: src/app/managers/model-manager.ts

Key Methods: - addModel(model: Omit<ModelEntry, 'id'>): ModelEntry – Registers a model, assigns unique ID. Throws if capacity (default 10000) is reached. - removeModel(id: string): boolean – Removes a model by ID. - getModels(): ModelInfo[] – Returns simplified metadata (safe for UI/React rendering). - getFullModels(): ModelEntry[] – Returns all model entries with full pointCloud references. - getModelWithPointCloud(modelType: 'ply' | 'onnx' | 'fbx', id?: string): ModelEntry | null – Gets a specific model entry. - getModelsByType(modelType: 'ply' | 'onnx' | 'fbx'): ModelEntry[] – Gets models by type. - getVisibleModels(): ModelEntry[] – Gets only visible models. - setModelVisibility(id: string, visible: boolean): void – Sets model visibility. - getModelCount(): number – Gets total model count. - getRemainingCapacity(): number – Gets remaining model capacity. - getTotalPoints(): number – Gets total point count across all models. - getTotalVisiblePoints(): number – Gets total visible point count. - isAtCapacity(): boolean – Checks if at model limit.

ModelEntry Interface:

interface ModelEntry {
  id: string;
  name: string;
  visible: boolean;
  pointCloud: PointCloud | DynamicPointCloud;
  pointCount: number;
  isDynamic: boolean;
  modelType: 'ply' | 'onnx' | 'fbx' | 'spz' | 'ksplat' | 'splat' | 'sog';
  colorMode?: string;
  colorChannels?: number;
}

FileLoader

Unified asset loader that wraps the IO module.

Path: src/app/managers/file-loader.ts

Supported Formats: - Gaussian: .ply, .spz, .ksplat, .splat, .sog, .compressed.ply - Mesh: .fbx

Key Methods: - loadFile(file: File, device: GPUDevice): Promise<ModelEntry | null> – Direct loading from File object. - loadSample(filename: string, device: GPUDevice, expectedType?: string): Promise<ModelEntry | null> – Loading from URL. Includes special handling for Blob URLs. - validateFile(file: File): boolean – Checks size limits (1GB default) and format support. - getSupportedExtensions(): string[] – Returns all supported file extensions.

LoadingCallbacks Interface:

interface LoadingCallbacks {
  onProgress?: (show: boolean, text?: string, pct?: number) => void;
  onError?: (message: string) => void;
}

ONNXManager

Handles the lifecycle of neural network-driven point clouds.

Path: src/app/managers/onnx-manager.ts

Key Methods: - loadONNXModel(device: GPUDevice, modelPath: string, cameraMatrix: Float32Array, projMatrix: Float32Array, name?: string, options?: ONNXLoadOptions): Promise<ModelEntry> – Creates an ONNXGenerator (ONNX Runtime Session) and a DynamicPointCloud. If staticInference=false, wires the generator to the point cloud for real-time updates. - disposeModel(id: string): void – Cleans up GPU buffers and ORT sessions associated with a model. - getONNXPerformanceStats(): object – Returns count of active generators and point clouds. - hasONNXModels(): boolean – Checks if any ONNX models are loaded. - getONNXModels(): ModelEntry[] – Returns all ONNX model entries.

ONNXLoadOptions Interface:

interface ONNXLoadOptions {
  staticInference?: boolean;  // If true, runs inference once; if false, runs per-frame.
  maxPoints?: number;         // Manual override for buffer allocation.
  precisionConfig?: object;   // FP16/FP32 precision settings for ONNX Runtime.
  debugLogging?: boolean;     // Enable debug logging.
}

CameraManager

Manages the camera matrix and user input controllers.

Path: src/app/managers/camera-manager.ts

Key Methods: - initCamera(canvas: HTMLCanvasElement): void – Sets up default Perspective Camera (45 deg FOV). - switchController(type: 'orbit' | 'fps'): void – Switches camera controller. When switching to Orbit, calculates a target center based on scene content to prevent orbiting empty space. Preserves camera position/rotation during switch. - setupCameraForPointCloud(pc: PointCloud): void – Auto-frames the camera to fit the given Point Cloud's Bounding Box. - update(dt: number): void – Updates the active controller (Orbit/FPS) logic. - resize(canvas: HTMLCanvasElement): void – Handles canvas resize. - resetCamera(): void – Resets camera to default position. - getCameraMatrix(): mat4 – Gets current view matrix. - getProjectionMatrix(): mat4 – Gets current projection matrix. - getController(): CameraController – Gets the active camera controller. - setOrbitCenter(center: vec3): void – Sets orbit center for Orbit controller. - getDebugInfo(): object – Returns camera debug information.

AnimationManager

Drives the updates for dynamic content.

Path: src/app/managers/animation-manager.ts

Key Methods: - updateDynamicPointClouds(view: mat4, proj: mat4, time: number): Promise<void> – Throttling: Prevents re-entry if the previous update is still processing (_frameUpdating flag). Iterates through all visible dynamic models and calls their update() method. - controlDynamicAnimation(action: 'start' | 'pause' | 'resume' | 'stop', speed?: number): void – Global control for all dynamic models. - setUpdateInterval(ms: number): void – Limits update frequency (e.g., to cap physics/inference FPS independent of render FPS). - setDynamicAnimationTime(time: number): void – Sets animation time for dynamic models. - getDynamicPerformanceStats(): Array<{ modelName: string, stats: AnimationStats }> – Returns performance statistics for dynamic models. - getDebugInfo(): object – Returns animation debug information.

AnimationStats Interface:

interface AnimationStats {
  updateCount: number;
  averageUpdateTime: number;
  lastUpdateTime: number;
}

RenderLoop

The "heartbeat" of the application.

Path: src/app/managers/render-loop.ts

Workflow: 1. init(gpu, renderer, canvas): Initializes with GPU context, renderer, and canvas. 2. start(): Kicks off requestAnimationFrame. 3. frame() Loop: - Calculates dt (Delta Time). - CameraManager.update(dt) - AnimationManager.updateDynamicPointClouds(...) - FPS Counting: Updates internal counters. - renderer.renderMulti(...): Submits GPU draw commands.

Key Methods: - start() / stop(): void – Controls render loop lifecycle. - setGaussianScale(scale: number): void – Updates global rendering uniform. - getGaussianScale(): number – Gets current Gaussian scale. - setBackgroundColor(color: [number, number, number, number]): void – Sets background color. - getBackgroundColor(): [number, number, number, number] – Gets current background color. - getPerformanceInfo(): object – Returns real-time FPS and frame times. - setCallbacks(callbacks: FPSCallbacks): void – Sets FPS and point count update callbacks. - getState(): AppState – Gets current render state. - getDebugInfo(): object – Returns render loop debug information.

FPSCallbacks Interface:

interface FPSCallbacks {
  onFPSUpdate?: (fps: number) => void;
  onPointCountUpdate?: (count: number) => void;
}

AppState Interface:

interface AppState {
  background: [number, number, number, number];
  gaussianScale: number;
  animationId: number;
  lastTime: number;
  frames: number;
  fpsAccumStart: number;
}

GaussianModel

A THREE.Object3D wrapper that keeps Gaussian splat models synchronized with GPU state.

constructor(entry: ModelEntry)

Properties

modelName: string
pointCloud: PointCloud | DynamicPointCloud
autoSyncEnabled: boolean
gaussianScale: number

Methods

syncTransformToGPU(): void
enableAutoSync(): void
disableAutoSync(): void
getModelEntry(): ModelEntry
isDynamic(): boolean
updateDynamicData(): void

GaussianThreeJSRenderer

Bridges Visionary with Three.js so splats and mesh geometry render on the same WebGPU device.

constructor(renderer: THREE.WebGPURenderer, scene: THREE.Scene, gaussianModels: GaussianModel[])

Properties

renderer: GaussianRenderer
gaussianModels: GaussianModel[]
autoDepthMode: boolean

Methods

onResize(width: number, height: number): void
onBeforeRender(renderer: THREE.WebGPURenderer, scene: THREE.Scene, camera: THREE.Camera): void
addGaussianModel(model: GaussianModel): void
removeGaussianModel(model: GaussianModel): void
setAutoDepthMode(enabled: boolean): void
getSceneDepthTexture(): THREE.DepthTexture | null
dispose(): void

WebGPU helpers

initWebGPU_onnx(canvas, opts?): Promise<WebGPUContext | null> negotiates a shared WebGPU device and canvas context. It prefers reusing the ONNX Runtime device; pass dummyModelUrl to force materialization.

type WebGPUContext = {
  device: GPUDevice;
  context: GPUCanvasContext;
  format: GPUTextureFormat;
};

Supported options:

preferShareWithOrt?: boolean
dummyModelUrl?: string | null
adapterPowerPreference?: GPURequestAdapterOptions['powerPreference']
allowOwnDeviceWhenOrtPresent?: boolean

UIController & DOMElements

UIController owns DOM event bindings while the App supplies callbacks. DOMElements exposes typed selectors used across the UI layer.

interface UICallbacks {
  onFileLoad(file: File): Promise<void>;
  onSampleLoad(filename: string): void;
  onResetCamera(): void;
  onGaussianScaleChange(scale: number): void;
  onBackgroundColorChange(color: [number, number, number, number]): void;
  onControllerSwitch(type: 'orbit' | 'fps'): void;
}

UnifiedModelLoader

A unified loader for PLY, ONNX, FBX, GLTF, OBJ, STL, and more.

constructor(renderer: THREE.WebGPURenderer, scene: THREE.Scene)

interface UnifiedLoadOptions {
  type?: ModelType;
  name?: string;
  isGaussian?: boolean;
  cameraMatrix?: Float32Array;
  projectionMatrix?: Float32Array;
  gaussianOptions?: GaussianLoadOptions;
  fbxOptions?: FBXLoadOptions;
  sourceFile?: File;
  onProgress?: (progress: number) => void;
  onError?: (error: Error) => void;
}

Methods

loadModel(input: File | string, options?: UnifiedLoadOptions): Promise<LoadResult>
loadModels(inputs: (File | string)[], options?: UnifiedLoadOptions): Promise<LoadResult[]>

Convenience wrapper:

async function loadUnifiedModel(
  renderer: THREE.WebGPURenderer,
  scene: THREE.Scene,
  input: File | string | (File | string)[],
  options?: UnifiedLoadOptions
): Promise<LoadResult | LoadResult[]>

TransformTracker

Tracks model transforms and source metadata for save/load pipelines.

constructor()

Methods

install(app: App): void
uninstall(): void
getTransform(modelId: string): ModelTransform | null
getSource(modelId: string): ModelSource | null
updateSource(modelId: string, newSource: ModelSource): void
getAllTrackedModels(): Array<{ modelId: string; source: ModelSource; transform: ModelTransform }>
cleanupRemovedModels(currentModelIds: string[]): void

interface ModelSource {
  kind: 'relative' | 'url';
  path?: string;
  url?: string;
  originalName?: string;
}

interface ModelTransform {
  position?: [number, number, number];
  rotationEulerRad?: [number, number, number];
  scale?: [number, number, number];
}

SceneFS

Directory-based scene manager backed by the File System Access API and a scene.json manifest.

constructor()

Methods

pickFolderRead(): Promise<void>
pickFolderWrite(): Promise<void>
loadScene(app: App): Promise<void>
saveScene(app: App): Promise<void>
getRootHandle(): FileSystemDirectoryHandle | null

interface SceneManifest {
  version: 1;
  meta?: {
    app?: string;
    createdAt?: string;
    unit?: 'meter' | 'centimeter' | string;
  };
  env?: {
    bgColor?: [number, number, number, number];
    gaussianScale?: number;
    camera?: {
      position: [number, number, number];
      target: [number, number, number];
      up: [number, number, number];
      fov: number;
    } | null;
  };
  assets: AssetEntry[];
}

interface AssetEntry {
  name: string;
  type: AssetType; // 'ply' | 'onnx' | 'fbx'
  path: string;
  dynamic?: boolean;
  transform?: {
    position?: [number, number, number];
    rotationEulerRad?: [number, number, number];
    scale?: [number, number, number];
  };
  extras?: {
    urlFallback?: string;
  };
}

Three.js bootstrap

initThreeContext(canvasElement) builds a shared WebGPU renderer for Three.js.

async function initThreeContext(
  canvasElement: HTMLCanvasElement
): Promise<THREE.WebGPURenderer | null>

Returns null when WebGPU or ORT integration cannot be established.

Important notes

The renderer batches every visible model, performs one global radix sort, and emits a single indirect draw call per frame.
Dynamic ONNX models expose a GPU-side count buffer; preprocessing respects the live instance count without reallocating memory.

App Module API Reference

Table of contents

App class

constructor()

init(): Promise

Model Loading

Camera & controls

Rendering state

Models & Diagnostics

Dynamic Animation Control

Manager Access (Advanced)

Manager Classes

ModelManager

FileLoader

ONNXManager

CameraManager

AnimationManager

RenderLoop

GaussianModel

Properties

Methods

GaussianThreeJSRenderer

Properties

Methods

WebGPU helpers

UIController & DOMElements

UnifiedModelLoader

Methods

TransformTracker

Methods

SceneFS

Methods

Three.js bootstrap

Important notes