### Start Development Server with npm

Source: https://ai4sports.opengvlab.com/help/guide/quickstart/index

Launches the local development environment for Visionary. This command typically uses a tool like Vite to serve the application, enabling hot-reloading and other development features. Access the application via `http://localhost:3000/`.

```bash
npm run dev

```

--------------------------------

### Install Project Dependencies with npm

Source: https://ai4sports.opengvlab.com/help/guide/quickstart/index

Installs all necessary project dependencies listed in `package.json`. This command should be run in the root directory of the Visionary project. It requires Node.js and npm to be installed.

```bash
npm install

```

--------------------------------

### App Class Constructor and Initialization

Source: https://ai4sports.opengvlab.com/help/modules/01-app/api-reference/index

Details on how to instantiate the App class and initialize the application, including WebGPU and ONNX setup.

```APIDOC
## 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:
  1. Initializes ORT (ONNX Runtime) environment
  2. Initializes WebGPU via `initWebGPU_onnx` (with ORT integration fallback)
  3. Creates `GaussianRenderer` and ensures sorter is ready
  4. Initializes camera and sets default controller (FPS)
  5. Binds UI event handlers
  6. Sets up resize handler
  7. Initializes `RenderLoop` with GPU context and callbacks
  8. 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
```

--------------------------------

### TimelineController Composition Example

Source: https://ai4sports.opengvlab.com/help/zh/modules/15-timeline/architecture/index

Demonstrates the Composition Pattern where TimelineController utilizes instances of AnimationState and TimeCalculator. It shows how the controller orchestrates these components for starting and updating the timeline.

```typescript
class TimelineController {
  private animationState = new AnimationState();
  private timeCalculator = new TimeCalculator();

  start(speed?: number) {
    this.animationState.play(speed);
  }

  update(rafNow?: number): number {
    return this.timeCalculator.calculateTime(
      rafNow,
      this.animationState.isPlaying,
      this.animationState.isPaused
    ).adjustedTime;
  }
}

```

--------------------------------

### Camera Math Example (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/11-utils/api-reference/index

Example demonstrating the usage of `focal2fov` and `fov2focal` for calculating camera field of view and focal length. It uses a canvas height for the pixel dimension.

```javascript
const verticalFov = focal2fov(800, canvas.height);
const focalLen = fov2focal(verticalFov, canvas.height);
```

--------------------------------

### Start and Stop Render Loop

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Controls the execution of the main render loop. `start` begins the frame rendering and updates, while `stop` halts the process. `isRunning` checks the current status.

```typescript
start(): void;
stop(): void;
isRunning(): boolean;
```

--------------------------------

### Basic Timeline Controller Initialization and Usage (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/15-timeline/api-reference/index

Demonstrates how to initialize the TimelineController with basic parameters and set up an event listener. It shows how to start the timeline and integrate its update method into a requestAnimationFrame loop for animation.

```javascript
import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016,
});

timeline.addEventListener(event => {
  console.log('Timeline event:', event);
});

timeline.start();

function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  updateAnimations(currentTime);
}
```

--------------------------------

### ONNX Runtime WASM Data Flow Example

Source: https://ai4sports.opengvlab.com/help/modules/13-onnx/architecture/index

Illustrates the data flow within the ONNX Runtime WASM system, from camera input to session execution and rendering. It highlights the role of updateInputBuffers, session.run, and buffer processing.

```text
Camera / Time → updateInputBuffers() → session.run(feeds, fetches)
                                         ↓
                          [gaussBuf, shBuf, countBuf]
                                         ↓
DynamicPointCloud (GPU buffers) → Preprocess (reads countBuf) → Sort → Render

```

--------------------------------

### Initialize Render Loop

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Initializes the render loop with the necessary components: GPU context, renderer, and canvas. This must be called before starting the loop.

```typescript
init(gpu: WebGPUContext, renderer: GaussianRenderer, canvas: HTMLCanvasElement): void;
```

--------------------------------

### Setup Scene Environment and Background (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/11-utils/api-reference/index

Assigns an environment map and a background to a scene. This function is part of the `EnvMapHelper` and is used to configure the visual environment of a 3D scene.

```javascript
setupSceneEnvironment(scene, envMap, background)
```

--------------------------------

### Manager Access Methods (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/01-app/architecture/index

Shows JavaScript examples of how to access individual managers directly from the App instance for advanced usage or debugging. This includes accessing ModelManager, ONNXManager, CameraManager, AnimationManager, and RenderLoop.

```javascript
// Direct ModelManager access
const modelManager = app.getModelManager();

// Direct ONNXManager access
const onnxManager = app.getONNXManager();

// Direct CameraManager access
const cameraManager = app.getCameraManager();

// Direct AnimationManager access
const animationManager = app.getAnimationManager();

// Direct RenderLoop access
const renderLoop = app.getRenderLoop();
```

--------------------------------

### WebGPU Context Sharing Initialization (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/01-app/architecture/index

Demonstrates the two-stage initialization process for WebGPU context sharing with ONNX Runtime, including ORT integration attempts and fallback mechanisms. This ensures efficient resource usage by sharing the GPU device.

```javascript
function initWebGPU_onnx() {
  // 1. ORT Integration Attempt
  // Tries to reuse the ONNX Runtime device (optionally forcing creation with a dummy model)

  // 2. Fallback
  // If ORT integration fails, falls back to standalone WebGPU initialization
}
```

--------------------------------

### Configure Model Replacement in sceneConfigs.ts

Source: https://ai4sports.opengvlab.com/help/guide/quickstart/index

Update the 'url' and 'loadOptions.type' within 'sceneConfigs.ts' to replace a model in the showcase. This example demonstrates how to specify a new model file and its type for loading.

```typescript
{
    type: 'file',
    url: '/models/your_model.ply',
    loadOptions: { type: 'ply' as const, name: 'Your Model' },
    scale: 2.5
}
```

--------------------------------

### WebGPU Initialization

Source: https://ai4sports.opengvlab.com/help/modules/01-app/architecture/index

Details the WebGPU initialization process, including ORT integration and fallback mechanisms.

```APIDOC
## WebGPU Context Sharing

### Description
The `initWebGPU_onnx()` function handles the initialization of the WebGPU context, prioritizing sharing the GPU device with ONNX Runtime (ORT) for efficiency. If direct sharing fails, it falls back to a standalone WebGPU initialization.

### Initialization Stages

1.  **ORT Integration Attempt**: The function first attempts to reuse the existing ONNX Runtime device. This can optionally be forced by providing a dummy model URL.
2.  **Fallback**: If the ORT integration is unsuccessful, the function proceeds with a standard, standalone WebGPU initialization.

### Benefits of Shared Device

*   **Single Device**: Ensures both ONNX inference and rendering utilize the same GPU device.
*   **Resource Efficiency**: Minimizes memory overhead by avoiding multiple GPU devices.
*   **Feature Consistency**: Guarantees that requested limits and features (e.g., `shader-f16`, timestamp queries) are applied uniformly.
*   **Buffer Compatibility**: Eliminates potential buffer compatibility issues arising from hidden or separate devices.
*   **Graceful Degradation**: The fallback mechanism ensures the application remains functional even if ORT device sharing fails.

### Configuration Options

```typescript
interface WebGPUInitOptions {
  preferShareWithOrt?: boolean;      // Prefer ORT device sharing (default: true)
  dummyModelUrl?: string | null;      // URL of a dummy model to force ORT device creation
  adapterPowerPreference?: 'high-performance' | 'low-power'; // GPU adapter preference
  allowOwnDeviceWhenOrtPresent?: boolean;  // Allow using a separate device if ORT is present (default: false)
}
```

### Usage Example
```javascript
// Initialize WebGPU, preferring to share with ORT
initWebGPU_onnx();

// Initialize WebGPU, forcing ORT device creation with a dummy model
initWebGPU_onnx({ dummyModelUrl: '/path/to/dummy.onnx' });

// Initialize WebGPU with low power preference and allowing own device
initWebGPU_onnx({
  adapterPowerPreference: 'low-power',
  allowOwnDeviceWhenOrtPresent: true
});
```
```

--------------------------------

### Initialize Gaussian Preprocessor and Dispatch Models (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/04-preprocessing/index

Demonstrates the initialization of GaussianPreprocessor for both Spherical Harmonics (SH) and raw RGB color modes, followed by a per-frame loop to dispatch each point cloud model. It shows how to conditionally select the preprocessor based on color mode and pass necessary arguments including an optional count buffer for dynamic point counts.

```javascript
const preprocessorSH = new GaussianPreprocessor();
await preprocessorSH.initialize(device, /*shDegree*/ 3, /*useRawColor*/ false);

const preprocessorRGB = new GaussianPreprocessor();
await preprocessorRGB.initialize(device, /*shDegree*/ 0, /*useRawColor*/ true);

// Per frame: preprocess every point cloud into the global buffers
const encoder = device.createCommandEncoder();
let baseOffset = 0;
for (const pc of pointClouds) {
  const pre = pc.colorMode === 'rgb' ? preprocessorRGB : preprocessorSH;
  const countBuffer = 'countBuffer' in pc ? pc.countBuffer?.() : undefined;
  pre.dispatchModel({
    camera,
    viewport: [width, height],
    pointCloud: pc,
    sortStuff: globalSortStuff,
    settings: buildRenderSettings(pc, frameSettings),
    modelMatrix: pc.transform,
    baseOffset,
    global: { splat2D: globalSplatBuffer },
    countBuffer,
  }, encoder);
  baseOffset += pc.numPoints;
}
// Later in the frame: run global radix sort + renderer draw

```

--------------------------------

### Initialize Application with Custom Settings

Source: https://ai4sports.opengvlab.com/help/modules/01-app/index

Demonstrates how to create and initialize the App instance with custom settings and includes error handling for the initialization process. It also shows how to programmatically load a Gaussian model.

```javascript
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);
}
```

--------------------------------

### Add Custom Scene Loading Method in ShowcaseScene.ts

Source: https://ai4sports.opengvlab.com/help/guide/quickstart/index

Demonstrates how to add a new method to 'ShowcaseScene.ts' for loading custom scenes, such as 'loadScene4'. This involves using 'loadUnifiedModel' and arranging models within the scene.

```typescript
async loadScene4() {
    // Load your models using loadUnifiedModel
    // Arrange them in the scene
}
```

--------------------------------

### Control FBX Model Animation Playback and Timeline

Source: https://ai4sports.opengvlab.com/help/zh/modules/16-models/api-reference/index

Provides examples of controlling the animation of an FBX model using 'FBXModelWrapper' methods. This includes starting, pausing, resuming, stopping, setting playback time, speed, and switching animation clips.

```typescript
// Get FBX model entry
const entry = modelManager.getModelWithPointCloud('fbx', 'robot-id');
if (entry && entry.modelType === 'fbx') {
  const wrapper = entry.pointCloud as FBXModelWrapper;

  // Control animation
  wrapper.startAnimation(1.5);  // Play at 1.5x speed
  wrapper.pauseAnimation();
  wrapper.resumeAnimation();
  wrapper.stopAnimation();

  // Timeline control
  wrapper.setAnimationTime(5.0);  // Jump to 5 seconds
  wrapper.setAnimationSpeed(2.0);  // 2x speed

  // Switch clips
  wrapper.switchToClip(1);  // Switch to second animation clip

  // Get clip info
  const clips = wrapper.getClipInfo();
  console.log('Available clips:', clips);
}
```

--------------------------------

### Initialize and Render with GaussianSplattingThreeWebGPU

Source: https://ai4sports.opengvlab.com/help/modules/12-three-integration/architecture/index

This snippet demonstrates the basic initialization and rendering process using the GaussianSplattingThreeWebGPU helper. It covers loading a PLY model and performing a render pass with a command encoder, swap chain view, camera, dimensions, and depth view. Ensure the WebGPU device is initialized before use.

```javascript
const gs = new GaussianSplattingThreeWebGPU();
await gs.initialize(renderer.backend.device);
await gs.loadPLY('/models/room.ply');

const encoder = device.createCommandEncoder();
gs.render(encoder, swapChainView, camera, [width, height], depthView);
device.queue.submit([encoder.finish()]);

```

--------------------------------

### Initialize and Use PerspectiveCamera and PerspectiveProjection

Source: https://ai4sports.opengvlab.com/help/modules/07-camera/index

Demonstrates how to initialize a PerspectiveProjection and PerspectiveCamera, handle viewport resizing, fit the camera's depth range to a bounding box, and upload camera data to GPU uniforms. It relies on the 'src/camera' module and 'gl-matrix'.

```typescript
import { PerspectiveCamera, PerspectiveProjection, deg2rad } from 'src/camera';

const projection = new PerspectiveProjection(
  [canvas.width, canvas.height],
  [deg2rad(60), deg2rad(45)],
  0.1,
  1000,
);
const camera = new PerspectiveCamera(vec3.fromValues(0, 0, -1), quat.create(), projection);

// Match viewport changes
window.addEventListener('resize', () => {
  projection.resize([canvas.width, canvas.height]);
});

// Fit depth range to a point cloud
camera.fitNearFar(pointCloud.bbox);

// Upload to GPU
cameraUniforms.setData({
  view: camera.viewMatrix(),
  proj: camera.projMatrix(),
  position: camera.position(),
});

```

--------------------------------

### GaussianModel 4D Animation Playback Control (JavaScript)

Source: https://ai4sports.opengvlab.com/help/guide/02-Object%20%26%20Interaction/index

Provides examples for controlling the playback of 4D animations for Gaussian Splatting models. This includes starting, pausing, and stopping animations for individual models, as well as global control via the renderer.

```javascript
import { GaussianModel } from 'src/app/GaussianModel';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';

// Individual model control
model.startAnimation(1.0); // Play, speed 1.0x
model.pauseAnimation();    // Pause
model.stopAnimation();     // Stop and reset to zero

// Global control (via renderer)
renderer.startAllAnimations(1.0);
renderer.stopAllAnimations();

```

--------------------------------

### Configure Showcase Scene Models and Camera Settings

Source: https://ai4sports.opengvlab.com/help/guide/quickstart/index

Demonstrates how to configure scene models and camera settings within the Visionary project. This involves updating the `SCENE1_CAROUSEL_ITEMS` array in `sceneConfigs.ts` to add or modify model entries, specifying their `url`, `type`, `loadOptions`, `scale`, and `transform`.

```typescript
// In demo/showcase/scripts/sceneConfigs.ts
import * as THREE from 'three/webgpu';
import { CarouselItemConfig } from './types';

// ------------------------------------------------------------------
// Area A: Carousel List (Multiple Objects)
// ------------------------------------------------------------------
// To add a model, copy a { ... } block inside the array and update the url/type.
export const SCENE1_CAROUSEL_ITEMS: CarouselItemConfig[] = [
    { 
        type: 'file', 
        url: '/models/my_model_01.ply',        // Edit 1: Your model path
        loadOptions: { 
            type: 'ply' as const,              // Edit 2: Matching file type
            name: 'Gallery Item A' 
        },
        scale: 2.5,                            // Optional: Scale factor
        transform: {                           // Optional: Transform settings
            position: new THREE.Vector3(0, -1, 0),
            rotation: new THREE.Euler(0, 0, 0)
        }
    },
    // ... Copy and paste to add more items
];

// ------------------------------------------------------------------
// Area B: Scene Configuration
// ------------------------------------------------------------------
// Configure camera views and model settings in the same file
// For scene logic, modify demo/showcase/scripts/ShowcaseScene.ts


```

--------------------------------

### Initialize and Render Gaussian Splats with WebGPU

Source: https://ai4sports.opengvlab.com/help/modules/06-renderer/index

Demonstrates the core workflow of initializing the GaussianRenderer, preparing multi-model data, and rendering it using WebGPU. This involves setting up the renderer with device and format, initializing it, preparing point clouds with camera and viewport information, and finally rendering the scene within a render pass.

```typescript
import { GaussianRenderer, DEFAULT_KERNEL_SIZE } from 'src/renderer';
import type { RenderArgs, RendererConfig, RenderStats } from 'src/renderer';

const renderer = new GaussianRenderer({
  device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  shDegree: 3,
  debug: true,
});
await renderer.initialize();

renderer.prepareMulti(encoder, device.queue, pointClouds, {
  camera,
  viewport: [canvas.width, canvas.height],
  maxSHDegree: 3,
  kernelSize: DEFAULT_KERNEL_SIZE,
});

const pass = encoder.beginRenderPass(passDesc);
renderer.renderMulti(pass, pointClouds);
pass.end();

```

--------------------------------

### Initialize and Render Multiple Point Clouds

Source: https://ai4sports.opengvlab.com/help/modules/06-renderer/architecture/index

Initializes the renderer and prepares it for rendering multiple point clouds. It then begins a render pass and renders the provided point clouds.

```javascript
await renderer.initialize();

renderer.prepareMulti(encoder, queue, pointClouds, {
  camera,
  viewport: [width, height],
  maxSHDegree: 3,
});

const pass = encoder.beginRenderPass(passDesc);
renderer.renderMulti(pass, pointClouds);
pass.end();

```

--------------------------------

### Save Unified Scene Example Usage

Source: https://ai4sports.opengvlab.com/help/modules/02-io/api-reference/index

Provides an example of how to use the `saveUnifiedScene` function with sample data. It demonstrates the structure of the `scenes` array, including models and keyframes, and how to pass `folderHandle` and `meta` parameters. This example illustrates a practical application of saving scene data.

```javascript
await saveUnifiedScene({
  scenes: [{
    models: [{
      id: 'model-1',
      name: 'MyModel.ply',
      typeTag: 'fileModel',
      trs: [[0, 0, 0], [0, 0, 0, 1], [1, 1, 1]],
      originFile: fileHandle,
      assetName: 'MyModel.ply'
    }],
    keyframes: [{
      objectId: 'model-1',
      frame: 0,
      trs: [[0, 0, 0], [0, 0, 0, 1], [1, 1, 1]]
    }]
  }],
  folderHandle: directoryHandle,
  meta: { createdAt: new Date().toISOString() }
});
```

--------------------------------

### Legacy Per-Model Rendering with prepareMulti

Source: https://ai4sports.opengvlab.com/help/modules/06-renderer/architecture/index

Demonstrates the legacy per-model rendering approach. It uses `prepareMulti` for preprocessing (recommended) and then `render` for individual point clouds, leveraging per-cloud caches and separate draw calls.

```javascript
// Still uses prepareMulti for preprocessing (recommended)
renderer.prepareMulti(encoder, queue, [pointCloud], args);
// Legacy path: uses render() instead of renderMulti()
renderer.render(pass, pointCloud); // Uses per-cloud cache, separate draw

```

--------------------------------

### Control Dynamic Animation

Source: https://ai4sports.opengvlab.com/help/modules/01-app/api-reference/index

Provides global control over dynamic animations. Functions allow starting, pausing, resuming, and stopping animations, as well as setting the current animation time and retrieving performance statistics. Speed can be optionally set when starting an animation.

```typescript
controlDynamicAnimation(action: 'start' | 'pause' | 'resume' | 'stop', speed?: number): void;
setDynamicAnimationTime(time: number): void;
getDynamicPerformanceStats(): Array<{ modelName: string, stats: any }>;

```

--------------------------------

### Initialize Core Managers - JavaScript

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/index

Demonstrates the basic instantiation and setup of key managers including ModelManager, CameraManager, AnimationManager, RenderLoop, FileLoader, ONNXManager, and GaussianLoader. It also shows how to configure loading callbacks for progress and error handling.

```javascript
const modelManager = new ModelManager(10_000);
const cameraManager = new CameraManager();
const animationManager = new AnimationManager(modelManager);
const renderLoop = new RenderLoop(modelManager, animationManager, cameraManager);

// Setup loading callbacks
const loadingCallbacks = {
  onProgress: (show, text, pct) => console.log(`Loading: ${pct}%`),
  onError: (msg) => console.error(msg),
};

const fileLoader = new FileLoader(modelManager, loadingCallbacks);
const onnxManager = new ONNXManager(modelManager);
const gaussianLoader = new GaussianLoader(fileLoader, onnxManager);

const app = new App();
await app.init();

```

--------------------------------

### Basic ONNX Generator Usage Example

Source: https://ai4sports.opengvlab.com/help/modules/13-onnx/api-reference/index

Provides a basic example of using `ONNXGenerator` to load a model, generate data using camera and projection matrices, and access output buffers like Gaussian and SH buffers. It also shows how to retrieve precision information for outputs.

```typescript
import { ONNXGenerator } from './onnx/onnx_generator';

const generator = new ONNXGenerator({
  modelUrl: '/models/gaussians3d.onnx',
  maxPoints: 1_000_000,
  debugLogging: true,
  device: gpuDevice
});

await generator.initialize();
await generator.generate({
  cameraMatrix: viewMatrix,
  projectionMatrix: projMatrix,
  time: performance.now() / 1000,
});

const gaussianBuffer = generator.getGaussianBuffer();
const shBuffer = generator.getSHBuffer();
const countBuffer = generator.getCountBuffer();

// Access precision information
const gaussPrecision = generator.getGaussianPrecision();
const colorPrecision = generator.getColorPrecision();
console.log(`Gaussian: ${gaussPrecision.dataType}, Color: ${colorPrecision.dataType}`);
```

--------------------------------

### Camera Control API

Source: https://ai4sports.opengvlab.com/help/modules/01-app/architecture/index

Allows manipulation and retrieval of camera parameters, including switching modes and getting view matrices.

```APIDOC
## Camera Control API

### Description
This API provides functionalities to control and query the camera's state within the application. You can reset the camera, switch between different control modes, and retrieve the current view and projection matrices.

### Methods

- **`resetCamera()`**
  - **Description**: Resets the camera to its default position and orientation.

- **`switchController(mode)`**
  - **Description**: Switches the camera control mode.
  - **Parameters**:
    - `mode` (string): The desired camera control mode. Accepted values are 'orbit' or 'fps'.

- **`getCameraMatrix()`**
  - **Description**: Retrieves the current camera's view matrix.
  - **Returns**: (mat4) The current view matrix.

- **`getProjectionMatrix()`**
  - **Description**: Retrieves the current camera's projection matrix.
  - **Returns**: (mat4) The current projection matrix.

### Request Example
```javascript
// Switch to FPS camera control
App.switchController('fps');

// Get the current camera view matrix
const viewMatrix = App.getCameraMatrix();

// Reset the camera
App.resetCamera();
```

### Response
- **`resetCamera()`**: Returns void.
- **`switchController(mode)`**: Returns void.
- **`getCameraMatrix()`**: Returns a 4x4 matrix representing the view transformation.
- **`getProjectionMatrix()`**: Returns a 4x4 matrix representing the projection transformation.
```

--------------------------------

### Initialize and Update PointCloud

Source: https://ai4sports.opengvlab.com/help/modules/03-point_cloud/index

Demonstrates how to load Gaussian data, initialize a PointCloud instance, update its parameters, and set up bind groups for rendering. This is typically used for static point cloud data.

```typescript
import { PointCloud } from 'src/point_cloud';

const gaussianData = await defaultLoader.loadFile(file); // IO module
const pc = new PointCloud(device, gaussianData);

pc.updateModelParamsBuffer(modelMatrix);
pc.setGaussianScaling(1.2);

computePass.setBindGroup(0, pc.bindGroup());
renderPass.setBindGroup(0, pc.renderBindGroup());

```

--------------------------------

### Usage Snippet: Packing Structs

Source: https://ai4sports.opengvlab.com/help/modules/10-uniform/api-reference/index

Example of packing data into a Float32Array for uniform buffer usage.

```APIDOC
## Usage Snippet: Packing Structs

```javascript
// Assuming 'settingsUniform' is an existing UniformBuffer instance
const settingsData = new Float32Array(20); // 80 bytes

// Fill settingsData with appropriate values (e.g., clipping boxes, scaling)
// Example:
// settingsData[0] = 1.0; // some value
// ... fill other elements

settingsUniform.setData(settingsData);
settingsUniform.flush();
```

### Description

Shows how to prepare data, potentially representing a struct or multiple values, into a `Float32Array` and then upload it to a `UniformBuffer`. This often involves manual packing or using `UniformUtils` helpers.
```

--------------------------------

### OpenGVLab Camera Setup and Matrix Generation (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/07-camera/api-reference/index

Demonstrates setting up a perspective camera and projection using OpenGVLab's camera module. It calculates view and projection matrices, and frustum planes based on a bounding box. Requires OpenGVLab's camera utilities.

```javascript
import { PerspectiveCamera, PerspectiveProjection, deg2rad } from 'src/camera';

const projection = new PerspectiveProjection(
  [1920, 1080],
  [deg2rad(65), deg2rad(45)],
  0.1,
  500,
);
const camera = new PerspectiveCamera(vec3.fromValues(0, 2, -4), quat.create(), projection);
camera.fitNearFar(pointCloud.bbox);

const view = camera.viewMatrix();
const proj = camera.projMatrix();
const planes = camera.frustumPlanes();

```

--------------------------------

### Usage Snippet: Updating Per Frame

Source: https://ai4sports.opengvlab.com/help/modules/10-uniform/api-reference/index

Example of updating uniform data on a per-frame basis.

```APIDOC
## Usage Snippet: Updating Per Frame

```javascript
// Assuming 'cameraUniform' is an existing UniformBuffer instance
function updateCamera(cameraBytes) {
  cameraUniform.setData(cameraBytes); // Update CPU cache
  cameraUniform.flush();             // Upload changes to GPU
}
```

### Description

Illustrates how to update the data within an existing `UniformBuffer` and synchronize those changes to the GPU. This is typically done each frame or whenever the uniform data changes.
```

--------------------------------

### TimelineController Initialization and Basic Usage

Source: https://ai4sports.opengvlab.com/help/zh/modules/15-timeline/index

Demonstrates how to initialize the TimelineController and perform basic playback and time control operations.

```APIDOC
## TimelineController Initialization and Basic Usage

### Description
This section covers the initialization of the `TimelineController` and its fundamental methods for controlling animation playback and time.

### Method
`new TimelineController(options)`

### Parameters
#### Constructor Options
- **`timeScale`** (number) - Optional - The global time scaling factor.
- **`animationSpeed`** (number) - Optional - The initial animation speed multiplier.
- **`timeUpdateMode`** (string) - Optional - The mode for updating time ('fixed_delta' or 'variable_delta'). Defaults to 'fixed_delta'.
- **`fixedDeltaTime`** (number) - Optional - The fixed time step for 'fixed_delta' mode.
- **`maxDeltaTime`** (number) - Optional - The maximum allowed delta time in 'variable_delta' mode.

### Request Example
```javascript
import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016, // ~60 FPS
  maxDeltaTime: 0.05
});
```

### Core Operations
#### Playback Control
- **`timeline.start(speedMultiplier?: number)`**: Starts or resumes playback.
- **`timeline.pause()`**: Pauses playback.
- **`timeline.resume()`**: Resumes playback from a paused state.
- **`timeline.stop()`**: Stops playback and resets the time.

#### Time Control
- **`timeline.setTime(time: number)`**: Sets the current time of the timeline.
- **`timeline.setSpeed(speed: number)`**: Sets the animation speed multiplier.
- **`timeline.setTimeScale(scale: number)`**: Sets the global time scale.

#### Update Loop
- **`timeline.update(currentTime: number): number`**: Updates the timeline and returns the current time. This should be called within the animation loop.

### Request Example (Playback and Update)
```javascript
// Playback control
timeline.start(1.0); // Start at 1x speed
timeline.pause();
timeline.resume();
timeline.stop();

// Time control
timeline.setTime(5.0);
timeline.setSpeed(2.0); // 2x speed
timeline.setTimeScale(0.5); // Half speed

// Update loop
function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  // Use currentTime for animations
}
animate();
```

### Response
#### Success Response (200)
- **`currentTime`** (number) - The current time of the timeline after the update.

#### Response Example
```json
{
  "currentTime": 5.123
}
```
```

--------------------------------

### Usage Snippet: Creating and Binding a Uniform

Source: https://ai4sports.opengvlab.com/help/modules/10-uniform/api-reference/index

Example of creating a UniformBuffer and binding it to a render pass.

```APIDOC
## Usage Snippet: Creating and Binding a Uniform

```javascript
import { UniformBuffer } from 'src/uniform';

// Assuming 'device' is an initialized GPUDevice
const projBytes = new Float32Array(16); // 64 bytes
const projUniform = new UniformBuffer(device, projBytes, 'projection');

// In your render pass encoder:
renderPass.setBindGroup(0, projUniform.bindGroup);
```

### Description

Demonstrates the basic steps to instantiate a `UniformBuffer` with initial data and then bind its associated `GPUBindGroup` to a specific index in a render pass.
```

--------------------------------

### Basic ORT Initialization Example

Source: https://ai4sports.opengvlab.com/help/modules/17-config/api-reference/index

Demonstrates the basic usage pattern for initializing the ONNX Runtime (ORT) environment using the Config module. It imports necessary functions, retrieves default WASM paths, initializes the environment, and logs the action.

```javascript
import { 
  initOrtEnvironment, 
  getDefaultOrtWasmPaths 
} from 'src/config';

// During app initialization
const wasmPaths = getDefaultOrtWasmPaths();
initOrtEnvironment(wasmPaths);
console.log(`ORT environment initialized with paths: ${wasmPaths}`);
```

--------------------------------

### Usage Snippet: Cloning for Multiple Cameras

Source: https://ai4sports.opengvlab.com/help/modules/10-uniform/api-reference/index

Example of cloning a UniformBuffer for scenarios like multiple cameras.

```APIDOC
## Usage Snippet: Cloning for Multiple Cameras

```javascript
// Assuming 'device' and 'mainData' are available
const mainCam = new UniformBuffer(device, mainData, 'main-camera');

// Create a separate uniform buffer with the same initial data
const debugCam = mainCam.clone(); 

// Now 'debugCam' can be modified independently or used with a different bind group index.
```

### Description

Demonstrates the use of the `clone()` method to create a new `UniformBuffer` instance that shares the same underlying data and configuration as an existing one. This is particularly useful for scenarios where you need multiple, independent uniform buffers that initially contain the same data, such as per-camera uniforms.
```

--------------------------------

### Setup Renderer Tone Mapping (JavaScript)

Source: https://ai4sports.opengvlab.com/help/modules/11-utils/api-reference/index

Copies tone-mapping settings from a reference renderer or applies default settings (ACES with an exposure of 0.8) to the target renderer. This helps ensure consistent visual appearance across different rendering contexts.

```javascript
setupRendererToneMapping(renderer, refRenderer?, toneMapping?, exposure?)
```

--------------------------------

### Basic Timeline Controller Usage (TypeScript)

Source: https://ai4sports.opengvlab.com/help/zh/modules/15-timeline/index

Demonstrates the basic initialization and playback control of the TimelineController. It shows how to set up the controller with various options like time scale, animation speed, and time update mode, and how to use playback methods like start, pause, resume, and stop. It also covers setting specific times and speeds, and integrating with the animation loop using `requestAnimationFrame`.

```typescript
import { TimelineController } from './timeline';

const timeline = new TimelineController({
  timeScale: 1.0,
  animationSpeed: 1.0,
  timeUpdateMode: 'fixed_delta',
  fixedDeltaTime: 0.016, // ~60 FPS
  maxDeltaTime: 0.05
});

// Playback control
timeline.start(1.0); // Start at 1x speed
timeline.pause();
timeline.resume();
timeline.stop();

// Time control
timeline.setTime(5.0);
timeline.setSpeed(2.0); // 2x speed
timeline.setTimeScale(0.5); // Half speed

// Update loop
function animate() {
  requestAnimationFrame(animate);
  const currentTime = timeline.update(performance.now());
  // Use currentTime for animations
}

animate(); // Start the animation loop
```

--------------------------------

### Get Supported Gaussian Format Extensions

Source: https://ai4sports.opengvlab.com/help/modules/02-io/api-reference/index

Returns an array containing all supported file extensions for Gaussian formats.

```typescript
function getSupportedGaussianFormats(): string[];
// Returns: ['.ply', '.spz', '.ksplat', '.splat', '.sog', '.compressed.ply']
```

--------------------------------

### Get Render Loop Debug Info

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Returns debug information related to the render loop's operation. This can be helpful for diagnosing issues with frame scheduling or rendering performance.

```typescript
getDebugInfo(): any;
```

--------------------------------

### WebGPU Initialization Options Interface (TypeScript)

Source: https://ai4sports.opengvlab.com/help/modules/01-app/architecture/index

Defines the configuration options for initializing WebGPU, including preferences for sharing context with ONNX Runtime, forcing ORT device creation, and specifying adapter power preferences. This interface allows for flexible setup of GPU resource management.

```typescript
interface WebGPUInitOptions {
  preferShareWithOrt?: boolean;      // Prefer ORT device sharing
  dummyModelUrl?: string | null;      // Force ORT device creation
  adapterPowerPreference?: 'high-performance' | 'low-power';
  allowOwnDeviceWhenOrtPresent?: boolean;  // Allow separate device
}
```

--------------------------------

### WebGPU Initialization

Source: https://ai4sports.opengvlab.com/help/modules/01-app/api-reference/index

Initializes a WebGPU context, negotiating a shared device and canvas context. It can optionally reuse an ONNX Runtime device or force materialization with a dummy model URL.

```APIDOC
## POST /initWebGPU_onnx

### Description
Negotiates a shared WebGPU device and canvas context. It prefers reusing the ONNX Runtime device; pass `dummyModelUrl` to force materialization.

### Method
POST

### Endpoint
/initWebGPU_onnx

### Parameters
#### Query Parameters
- **canvas** (HTMLCanvasElement) - Required - The canvas element to use for rendering.
- **opts** (object) - Optional - Options for WebGPU initialization.
  - **preferShareWithOrt** (boolean) - Optional - Whether to prefer sharing the device with ONNX Runtime.
  - **dummyModelUrl** (string | null) - Optional - URL of a dummy model to force materialization.
  - **adapterPowerPreference** (GPURequestAdapterOptions['powerPreference']) - Optional - Preferred power usage for the adapter.
  - **allowOwnDeviceWhenOrtPresent** (boolean) - Optional - Whether to allow using own device when ONNX Runtime is present.

### Response
#### Success Response (200)
- **WebGPUContext** (object) - The WebGPU context containing device, context, and format.
  - **device** (GPUDevice) - The WebGPU device.
  - **context** (GPUCanvasContext) - The canvas context.
  - **format** (GPUTextureFormat) - The texture format.

#### Response Example
```json
{
  "device": "<GPUDevice>",
  "context": "<GPUCanvasContext>",
  "format": "bgra8unorm"
}
```
```

--------------------------------

### Get Gaussian Scale and Background Color

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Retrieves the current global rendering settings for Gaussian scale and background color. These getters allow querying the active rendering configuration.

```typescript
getGaussianScale(): number;
getBackgroundColor(): [number, number, number, number];
```

--------------------------------

### Load Gaussian and Other Formats - JavaScript

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/index

Provides examples of loading various Gaussian formats (SPZ, KSplat) and ONNX models using both the FileLoader and the higher-level GaussianLoader. It demonstrates auto-detection of file formats and specific loading methods.

```javascript
// Load Gaussian formats via FileLoader
await fileLoader.loadFile(file, device); // Auto-detects format
await fileLoader.loadSample('model.spz', device, 'gaussian');

// Load via GaussianLoader (creates GaussianModel)
const model = await gaussianLoader.createFromSPZ(renderer, 'model.spz');
const model2 = await gaussianLoader.createFromKSplat(renderer, 'model.ksplat');
const model3 = await gaussianLoader.createFromONNX(renderer, 'model.onnx', camMat, projMat);

```

--------------------------------

### Get Camera Frustum Planes

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Returns the frustum planes of the camera's view volume as a Float32Array. These planes are used for culling objects outside the camera's view.

```typescript
getFrustumPlanes(): Float32Array;
```

--------------------------------

### Get Camera Position and Rotation

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Retrieves the camera's current position in 3D space and its rotation as a quaternion. These properties are fundamental for understanding the camera's orientation and placement.

```typescript
getPosition(): vec3;
getRotation(): quat;
```

--------------------------------

### Get Render Statistics

Source: https://ai4sports.opengvlab.com/help/modules/06-renderer/architecture/index

The `getRenderStats(pointCloud)` function returns statistics related to the rendering process, including the total number of points, visible splats, and an estimate of memory usage.

```javascript
getRenderStats(pointCloud)
```

--------------------------------

### Manage Gaussian Renderer Instances (TypeScript)

Source: https://ai4sports.opengvlab.com/help/guide/01-Fundations/index

Demonstrates how to manage Gaussian renderer instances to avoid performance crashes. It shows how to initialize a renderer for the first model and append subsequent models to the existing renderer, disposing of redundant instances.

```typescript
import { loadUnifiedModel } from 'src/app/unified-model-loader';
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';

// Define a member variable to hold the unique renderer reference
private activeGaussianRenderer: GaussianThreeJSRenderer | null = null;

async function handleModelLoad(url: string) {
    const result = await loadUnifiedModel(renderer, scene, url);

    // 1. Handle standard Mesh models
    // ...

    // 2. Handle Gaussian models
    if (result.gaussianRenderer && result.models.length > 0) {
        const newSplatModel = result.models[0];

        if (!this.activeGaussianRenderer) {
            // [Scenario A: Initialization] 
            // No active renderer, use the instance returned by the loader
            this.activeGaussianRenderer = result.gaussianRenderer;

        } else {
            // [Scenario B: Appending] 
            // Renderer exists, "merge" the new model into it
            this.activeGaussianRenderer.appendGaussianModel(newSplatModel);

            // CRITICAL: Dispose of the redundant temporary renderer created by the loader
            // to release WebGPU resources.
            if (typeof result.gaussianRenderer.dispose === 'function') {
                result.gaussianRenderer.dispose();
            }
        }
    }
}
```

--------------------------------

### Control Dynamic Animation

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Manages the playback of dynamic animations, allowing actions like starting, pausing, resuming, and stopping. An optional speed parameter can control the animation playback rate.

```typescript
controlDynamicAnimation(action: 'start' | 'pause' | 'resume' | 'stop', speed?: number): void;
```

--------------------------------

### Set and Get Target FPS

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Allows setting a target frames per second for the render loop, which can be used for throttling performance. `getTargetFPS` retrieves the currently set target FPS.

```typescript
setTargetFPS(fps: number): void;
getTargetFPS(): number;
```

--------------------------------

### Quick Start: Initialize and Render Gaussian Splats in Three.js (TypeScript)

Source: https://ai4sports.opengvlab.com/help/modules/12-three-integration/index

This snippet demonstrates how to initialize the GaussianThreeJSRenderer and integrate it into an existing Three.js application. It covers setting up the Three.js renderer, loading Gaussian models, initializing the Gaussian renderer, and integrating its update and render calls into the animation loop. This approach ensures compatibility with Three.js features like post-processing and XR sessions.

```typescript
import { GaussianThreeJSRenderer } from 'src/app/GaussianThreeJSRenderer';
import { GaussianModel } from 'src/app/GaussianModel';

const threeRenderer = await initThreeContext(canvas);       // r155+ WebGPU renderer
const gaussianModels = loadedEntries.map(entry => new GaussianModel(entry));
gaussianModels.forEach(model => scene.add(model));

const gaussianRenderer = new GaussianThreeJSRenderer(threeRenderer, scene, gaussianModels);
await gaussianRenderer.init();
scene.add(gaussianRenderer); // ensures onBeforeRender hooks fire

function animate(timeMs: number) {
  requestAnimationFrame(animate);

  gaussianRenderer.updateDynamicModels(camera, timeMs * 0.001);
  gaussianRenderer.renderOverlayScene(gizmoScene, camera); // optional
  gaussianRenderer.renderThreeScene(camera);
  gaussianRenderer.drawSplats(threeRenderer, scene, camera);
}

animate(0);

```

--------------------------------

### Three.js Context Initialization

Source: https://ai4sports.opengvlab.com/help/modules/01-app/api-reference/index

Initializes a shared WebGPU renderer for Three.js applications.

```APIDOC
## POST /initThreeContext

### Description
Builds a shared WebGPU renderer for Three.js. Returns `null` when WebGPU or ORT integration cannot be established.

### Method
POST

### Endpoint
/initThreeContext

### Parameters
#### Query Parameters
- **canvasElement** (HTMLCanvasElement) - Required - The canvas element to initialize the renderer with.

### Response
#### Success Response (200)
- **THREE.WebGPURenderer** (object) - The initialized WebGPU renderer instance, or null if initialization fails.

#### Response Example
```json
{
  "renderer": "<THREE.WebGPURenderer>"
}
```
```

--------------------------------

### Get Frame Timing Information

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Provides details about the timing of individual frames and the average frame duration. `getLastFrameTime` returns the duration of the most recent frame, and `getAverageFrameTime` calculates the average over time.

```typescript
getLastFrameTime(): number;
getAverageFrameTime(): number;
```

--------------------------------

### Set and Get Dynamic Animation Time

Source: https://ai4sports.opengvlab.com/help/modules/14-managers/api-reference/index

Allows setting a specific time point for the dynamic animation or retrieving the current animation time. This enables precise control over animation playback.

```typescript
setDynamicAnimationTime(time: number): void;
getLastUpdateTime(): number;
```