App Module

The App Module serves as the central orchestrator for the 3D Gaussian Splatting WebGPU viewer. It implements a Manager-based Architecture to decouple loading, rendering, animation, and user interaction logic. The module manages the complete application lifecycle, from initialization to rendering, and coordinates all other modules including WebGPU context management, UI interactions, and rendering pipeline orchestration.

Module Overview

Path: src/app/
Purpose: Application lifecycle management and UI coordination
Dependencies: renderer, point_cloud, camera, controls, io modules

Core Components

Component	File	Purpose
`App`	`app.ts`	Main application class and lifecycle orchestrator
`ModelManager`	`managers/model-manager.ts`	Data ownership and model tracking
`FileLoader`	`managers/file-loader.ts`	Unified asset loader (PLY, SPZ, KSplat, SPLAT, SOG, Compressed PLY, ONNX, FBX)
`ONNXManager`	`managers/onnx-manager.ts`	Dynamic ONNX model management
`CameraManager`	`managers/camera-manager.ts`	Camera and controller management
`AnimationManager`	`managers/animation-manager.ts`	Dynamic content updates
`RenderLoop`	`managers/render-loop.ts`	Frame cycle and rendering coordination
`WebGPUContext`	`webgpu-context.ts`	WebGPU initialization and context management
`UIController`	`ui-controller.ts`	User interaction and event handling
`DOMElements`	`dom-elements.ts`	DOM element references and utilities

Quick Start

Basic Usage

import { App } from './src/app';

// Create and initialize the application
const app = new App();
await app.init();

// Load a Gaussian model (supports multiple formats)
await app.loadGaussian('model.ply');
// or
await app.loadGaussian('model.spz');
await app.loadGaussian('model.ksplat');
await app.loadGaussian('model.splat');
await app.loadGaussian('model.sog');

// Load an ONNX model for dynamic inference
await app.loadONNXModel('./models/dynamic.onnx', 'Dynamic Model', false);

Application Initialization Flow

DOM Setup - Query and cache all required DOM elements via DOMElements
Manager Initialization - Create all manager instances (Model, File, ONNX, Camera, Animation, RenderLoop)
ORT Environment - Initialize ONNX Runtime environment
WebGPU Context - Initialize WebGPU device with ORT integration (with fallback)
Renderer Creation - Set up the Gaussian renderer with GPU resources
Camera Setup - Initialize perspective camera with default settings
UI Binding - Attach event listeners for user interactions
Render Loop - Start the main animation frame loop

Key Features

File Loading

Multiple Formats: Supports PLY, SPZ, KSplat, SPLAT, SOG, compressed PLY, ONNX, and FBX
Drag & Drop: Direct file loading from filesystem
Sample Files: Pre-loaded demonstration files via loadSample()
Progress Tracking: Real-time loading progress with UI feedback
Error Handling: Comprehensive error messages and recovery
Format Detection: Automatic format detection via detectGaussianFormat()

Camera Controls

Multiple Controllers: Orbit and FPS camera modes via switchController()
Mouse Navigation: Left-click for rotation, right-click for panning
Scroll Zoom: Mouse wheel for camera distance control
Keyboard Input: WASD movement with controller integration
Reset Function: One-click camera position reset
Auto-Framing: Automatic camera setup for point clouds

Rendering Controls

Gaussian Scaling: Real-time splat size adjustment via setGaussianScale()
Background Color: Customizable scene background via setBackgroundColor()
Performance Stats: FPS monitoring and point count display
Responsive Viewport: Automatic canvas resizing
Multi-Model Rendering: Support for multiple concurrent models

WebGPU Management

ORT Integration: Shared WebGPU device with ONNX Runtime
Feature Detection: Automatic WebGPU capability checking
Context Configuration: Optimal GPU context setup with fallback
Error Recovery: Graceful fallback for unsupported browsers
Resource Management: Efficient GPU memory handling

Dynamic Models

ONNX Support: Load and run ONNX models for dynamic point cloud generation
Real-time Inference: Per-frame GPU inference for dynamic content
Animation Control: Start, pause, resume, and stop dynamic animations
Performance Tracking: Monitor inference performance metrics

Architecture

The App module uses a Manager-based Architecture where the App class acts as a facade orchestrating specialized managers:

┌─────────────────────────────────────────┐
│              App (Facade)               │  ← Main orchestrator
├─────────────────────────────────────────┤
│  UIController  │  DOMElements          │  ← UI layer
│  WebGPUContext │  GaussianRenderer      │  ← Rendering layer
└────────────────┬────────────────────────┘
                 │ delegates to
┌────────────────┴────────────────────────┐
│           Manager Layer                 │
├─────────────────────────────────────────┤
│  ModelManager      │  FileLoader        │  ← Data management
│  ONNXManager       │  CameraManager     │  ← Dynamic & view control
│  AnimationManager  │  RenderLoop        │  ← Update & render cycle
└─────────────────────────────────────────┘
                 │ uses
┌────────────────┴────────────────────────┐
│         Core Subsystems                 │
├─────────────────────────────────────────┤
│  PointCloud / DynamicPointCloud         │
│  GaussianRenderer                       │
│  IO Module (defaultLoader)              │
└─────────────────────────────────────────┘

See Architecture Guide for detailed design decisions.

Usage Examples

Custom Initialization

import { App } from './src/app';

const app = new App();

// Custom initialization with error handling
try {
  await app.init();
  console.log('Application started successfully');

  // Load a model programmatically
  await app.loadGaussian('path/to/model.ply');
} catch (error) {
  console.error('Failed to initialize:', error);
}

Loading Different Formats

// Load PLY format
await app.loadGaussian('model.ply');

// Load SPZ format
await app.loadSPZ('model.spz');

// Load KSplat format
await app.loadKSplat('model.ksplat');

// Load SPLAT format
await app.loadSplat('model.splat');

// Load SOG format
await app.loadSOG('model.sog');

// Load ONNX model (static inference)
await app.loadONNXModel('./models/model.onnx', 'Model Name', true);

// Load ONNX model (dynamic per-frame inference)
await app.loadONNXModel('./models/dynamic.onnx', 'Dynamic Model', false);

Accessing Managers

// Get manager instances for advanced usage
const modelManager = app.getModelManager();
const cameraManager = app.getCameraManager();
const onnxManager = app.getONNXManager();
const animationManager = app.getAnimationManager();
const renderLoop = app.getRenderLoop();

// Get debug information
const debugInfo = app.getDebugInfo();
console.log(debugInfo);

Browser Compatibility

Chrome/Edge: 113+ (full WebGPU support)
Firefox: Nightly builds with WebGPU enabled
Safari: WebGPU experimental features required

Performance Considerations

Memory Usage: Scales with point cloud size (up to 16M points)
GPU Requirements: Dedicated GPU recommended for large datasets
Canvas Resolution: Automatically adapts to device pixel ratio
Frame Rate: Target 60fps with dynamic quality adjustment

Error Handling

The App Module includes comprehensive error handling:

WebGPU Unavailable: Shows fallback message with browser recommendations
File Loading Errors: Displays specific error messages in modal dialogs
GPU Memory Limits: Graceful degradation with user feedback
Renderer Failures: Recovery mechanisms with error reporting

Development Notes

Manager Architecture: Responsibilities are separated into dedicated managers for better modularity
State Management: Centralized application state in AppState interface (RenderLoop)
Event System: Callback-based UI interaction system via UICallbacks
Resource Cleanup: Proper GPU resource lifecycle management
Performance Monitoring: Built-in FPS and memory usage tracking
Format Support: Uses defaultLoader from IO module for unified format handling
ORT Integration: WebGPU device sharing with ONNX Runtime for efficient GPU usage

Architecture – Manager-oriented design breakdown and lifecycle flowcharts.
API Reference – Full App facade and manager APIs, including loaders and WebGPU helpers.