gsplat.js Documentation

gsplat.js supports both .ply and .splat file formats:

• .splat files: A compact format consisting of a raw Uint8Array buffer. They offer quicker loading times than .ply files but do not contain SH (Spherical Harmonics) coefficients, meaning colors are not view-dependent.
• .ply files: Standard Gaussian Splatting files that can contain SH coefficients for view-dependent coloring.

Note on Conversion: You can convert .ply to .splat and vice versa. However, be aware that converting .ply $\rightarrow$ .splat $\rightarrow$ .ply will result in the loss of SH coefficients.

To use gsplat.js in your project, ensure your environment supports ES6 modules. It is recommended to use a module bundler like Vite.

1. Initialize a project with Vite (if starting from scratch):

   npm create vite@latest gsplat -- --template vanilla-ts

2. Install dependencies and start the dev server:

   cd gsplat
   npm install
   npm run dev

3. Install the gsplat package:

   npm install --save gsplat

The gsplat.js editor is a tool for real-time editing of Gaussian Splatting objects.

Importing Splats

To load Gaussian Splatting objects into the editor, drag and drop .ply or .splat files directly into the editor window.

Exporting Splats

You can download your edited splats as a .splat file using the download button in the top right corner:

• Single Object: If an object is currently selected, only that specific object will be downloaded.
• All Objects: If no object is selected, all objects in the scene will be combined into a single .splat file for download.

To render a Gaussian Splatting scene, you need to initialize a Scene, a Camera, a WebGLRenderer, and OrbitControls. Use SPLAT.Loader.LoadAsync to load .splat data into the scene, then implement a rendering loop using requestAnimationFrame.

import * as SPLAT from "gsplat";

const scene = new SPLAT.Scene();
const camera = new SPLAT.Camera();
const renderer = new SPLAT.WebGLRenderer();
const controls = new SPLAT.OrbitControls(camera, renderer.canvas);

async function main() {
    const url = "https://huggingface.co/datasets/dylanebert/3dgs/resolve/main/bonsai/bonsai-7k.splat";

    await SPLAT.Loader.LoadAsync(url, scene, () => {});

    const frame = () => {
        controls.update();
        renderer.render(scene, camera);

        requestAnimationFrame(frame);
    };

    requestAnimationFrame(frame);
}

main();

Use these keyboard and mouse shortcuts to manipulate objects in the editor:

Selection and Actions

• Select / Confirm: Left Mouse
• Cancel: Right Mouse
• Delete: X

Transformations

• Grab (Translate): G
• Rotate: R
• Scale: S

Axis Locking

• Lock to X axis: X
• Lock to Y axis: Y
• Lock to Z axis: Z

Use the following mouse controls to navigate the scene:

• Orbit: Middle Mouse
• Pan: Shift + Middle Mouse
• Zoom: Scroll Wheel

The renderer manages a collection of ShaderProgram instances. By default, it includes a RenderProgram. You can extend the rendering capabilities by adding custom programs or remove existing ones.

• addProgram(program: ShaderProgram): Adds a new shader program to the rendering pipeline.
• removeProgram(program: ShaderProgram): Removes a specific shader program. Throws an error if the program is not found.
• dispose(): Cleans up all managed programs.

Use these methods for spatial calculations and vector properties:

• cross(v: Vector3): Vector3: Returns the cross product of this vector and v.
• dot(v: Vector3): number: Returns the dot product of this vector and v.
• lerp(v: Vector3, t: number): Vector3: Linearly interpolates between this vector and v by factor t.
• magnitude(): number: Returns the length of the vector.
• normalize(): Vector3: Returns a new vector with the same direction but a magnitude of 1.
• distanceTo(v: Vector3): number: Returns the Euclidean distance between this vector and v.
• equals(v: Vector3): boolean: Checks if two vectors have identical components.
• clone(): Vector3: Returns a deep copy of the vector.
• flat(): number[]: Returns the components as an array [x, y, z].
• toString(): string: Returns a string representation in the format [x, y, z].

Use the static Matrix4.Compose method to create a transformation matrix from position, rotation, and scale. This is a convenient way to build a model matrix for an object in 3D space.

Parameters:

• position: A Vector3 representing the translation.
• rotation: A Quaternion representing the rotation.
• scale: A Vector3 representing the scaling factors.

The following properties are available on the WebGLRenderer instance:

• canvas: Returns the HTMLCanvasElement used for rendering.
• gl: Returns the WebGL2RenderingContext.
• renderProgram: Returns the primary RenderProgram instance.
• backgroundColor: Returns the current Color32 background color.

You can control the dimensions of the rendering viewport and the background color of the canvas.

• setSize(width: number, height: number): Manually sets the canvas dimensions and updates the WebGL viewport.
• resize(): Resizes the canvas to match its current CSS client dimensions.
• backgroundColor: A getter/setter for the Color32 background color. Setting this updates the canvas's CSS background style.