3dgs-loader

3DGS Loader

This module provides a unified loader framework for 3D Gaussian Splatting (3DGS) data. It supports multiple data formats and exposes a consistent usage API, independent of the underlying format.

The loader layer is responsible only for data loading and parsing. It does not handle rendering, sorting, LOD, or interaction logic.

1. Loader Overview

All loaders inherit from a shared base class Loader and follow the same public API.

Supported loaders include:

• SplatLoader (.splat)
• SogLoader (.sog , .json , ArrayBuffer )
• SpzLoader （.spz , ArrayBuffer）
• KSplatLoader (.ksplat , ArrayBuffer)
• PlyLoader (.ply , ArrayBuffer)

Because the interface is uniform, loaders can be swapped without changing application code.

2. Basic Usage (Common to All Loaders)

2.1 Create a Loader

import SplatLoader from './loaders/SplatLoader'

const loader = new SplatLoader({
    workerLimit: 4,        // Number of workers (0 = disabled)
    workerBaseUrl: './',   // Base URL for worker scripts
    wasmBaseUrl: './',     // Base URL for WASM assets (if required)
})

All loader types accept the same constructor options.

Note

SplatLoader is a special case: it only provides load() and loadColumns(), and does not implement loadAsSplat() or parseAsSplat(), because the .splat format is already the native splat representation.

2.2 Load as Columns

const columns = await loader.loadColumns('scene.splat', {
    onProgress: (percent) => {
        console.log(`loading: ${percent}`)
    },
})

• Loads a 3DGS source and parses it into column-based data
• Recommended entry point for most pipelines
• Suitable for any downstream 3DGS workflow

2.3 Parse as Columns (From Existing Buffer)

const columns = await loader.parseColumns(dataBuffer)

• Parses an already loaded binary buffer
• Skips network requests
• Useful for custom I/O or streaming systems

2.4 Load as Splat

const splat = await loader.loadAsSplat('***.ply', {
    onProgress: (percent) => {
        console.log(`loading: ${percent}`)
    },
})

• Loads a 3DGS source and parses it directly into Splat format
• Skips the column-based representation
• Useful for exporting, legacy pipelines, or direct splat-based workflows
• Not supported by SplatLoader

2.5 Parse as Splat (From Existing Buffer)

const splat = await loader.parseAsSplat(dataBuffer)

• Parses raw data directly into Splat format
• Suitable when data is already available in memory
• Not supported by SplatLoader

2.6 Load as Attributes

const attributes = await loader.loadAsAttributes('***.ply', {
    onProgress: (percent) => {
        console.log(`loading: ${percent}`)
    },
})

• Loads a 3DGS source and parses it directly into Attributes format
• Produces typed arrays:
  • positions: Float32Array
  • scales: Float32Array
  • rotations: Float32Array
  • colors: Uint8Array

---

2.7 Parse as Attributes (From Existing Buffer)

const attributes = await loader.parseAsAttributes(dataBuffer)

• Parses raw data already available in memory into Attributes format

Attributes Format Definition

interface
GaussianSplatAttributes
{
    numSplats: number
    positions: Float32Array   // xyz, length = numSplats * 3
    scales: Float32Array      // sx sy sz (linear), length = numSplats * 3
    rotations: Float32Array   // quaternion xyzw, length = numSplats * 4
    colors: Uint8Array        // rgba, length = numSplats * 4
}

2.8 Dispose the Loader

loader.dispose()

Always dispose the loader when it is no longer needed to properly release worker and memory resources.

3. Worker Acceleration (Optional)

All loaders support worker-based parsing through WorkerPool, allowing heavy decoding and parsing work to run off the main thread.

3.1 Enable Worker Acceleration

const loader = new SogLoader({
    workerLimit: 4,   // Enable worker-based parsing
})

• Parsing runs entirely off the main thread
• ArrayBuffers are transferred to workers (zero-copy)
• Fully transparent to the calling code

4. WASM Support (Optional)

Some loaders (notably SogLoader) rely on WebAssembly (WASM) modules for decoding compressed data, such as WebP-encoded spherical harmonics.

4.1 When WASM Is Required

• SOG data may store SH coefficients in WebP format
• Decoding WebP efficiently requires a WASM-based decoder
• The WASM module is not bundled with the loader by default

4.2 Required WASM Assets

The following files must be available at runtime:

/webp/
├─ wasm_webp.wasm
└─ wasm_webp.min.js

These files must be copied to a publicly accessible location.

4.3 Configure WASM Path

const loader = new SogLoader({
    workerLimit: 4,
    wasmBaseUrl: './',   // Base URL that contains the /webp directory
})

The loader resolves the WebP WASM script URL internally and passes it to the worker or main-thread parser as needed.