@zappar/three-gaussian-splat

Gaussian Splats for ThreeJS

This library allows you to render 3D Gaussian Splats using the 3D rendering platform ThreeJS.

You may also be interested in Mattercraft, a browser based 3D content development environment perfected for building interactive experiences for the web.

Table Of Contents

Click to expand table of contents

• Gaussian Splats for ThreeJS
  • Table Of Contents
  • Starting Development
    • NPM Package
    • Quick Start
      • GitHub Templates
  • GaussianSplatMesh
    • Loading
    • Adding To Scene
    • Updating the mesh
  • Masking
    • Sphere
    • Plane
    • Helper
    • Performance
  • How do i get .splat files?
  • License

Starting Development

You can use this library by installing from NPM.

NPM Package

Run the following NPM command inside your project directory:

npm install --save @zappar/three-guassian-splat

Then import the library into your JavaScript or TypeScript files:

import * as ZapSplat from '@zappar/three-guassian-splat';

Please note - This library supports Webpack 5 and later.

Quick Start

You can integrate the library with the existing requestAnimationFrame loop of your ThreeJS project. A typical project may look like this. The remainder of this document goes into more detail about each of the component elements of this example.

import * as ZapSplat from '@zappar/three-gaussian-splat';

const bonsai = new URL('./bonsai.splat', import.meta.url).href;
const maxSplats = Infinity;
const splat = new ZapSplat.GaussianSplatMesh(camera, renderer, bonsai, maxSplats);
splat.load();
scene.add(splat);

renderer.setAnimationLoop(animation);

function animation() {
  splat.update();
  renderer.render(scene, camera);
}

GitHub Templates

Explore our template project at this link: Three Gaussian Splat Example on GitHub

For a live preview, visit: Three Gaussian Splat Example Preview

GaussianSplatMesh

You can use the GaussianSplatMesh to construct the splat mesh. It takes 2 arguments.

const splat = new ZapSplat.GaussianSplatMesh(
  url, // url to .splat file
  maxSplats // Maximum number of splats to render. Default = Infinity.
);

Loading

To start loading the .splat file, call the load function.

splat.load();

You may optionally choose to provide a THREE.LoadingManager to track the loading progress:

const loadingManager = new THREE.LoadingManager();
splat.load(loadingManager);

Adding To Scene

The GaussianSplat mesh can be added to the scene like any other Object3D:

scene.add(splat);

Updating the mesh

The mesh needs to be updated before rendering. This can be done by calling the update function.

splat.update(
  camera, // THREE.PerspectiveCamera
  renderer // THREE.WebGLRenderer
);

Masking

The library provides two meshes to define invisible areas of your splat.

Sphere

A MaskingShere can be added to the GaussianSplatMesh to hide anything outside of the sphere.

const splat = new ZapSplat.GaussianSplatMesh(bonsai, Infinity);
splat.load();
scene.add(splat);

const maskSphere = new ZapSplat.MaskingSphere();

splat.addMaskMesh(maskSphere);
maskSphere.position.y = 0.9;
maskSphere.scale.setScalar(2.5);
// set to invisible once finalized position
maskSphere.visible = false;
renderer.setAnimationLoop(animation);

function animation() {
  splat.update(camera, renderer);
  renderer.render(scene, camera);
}

Plane

A MaskingPlane can be added to the GaussianSplatMesh to hide anything in the planes normal direction.

const splat = new ZapSplat.GaussianSplatMesh(bonsai, Infinity);
splat.load();
scene.add(splat);

const maskPlane = new ZapSplat.MaskingPlane();

splat.addMaskMesh(maskPlane);
renderer.setAnimationLoop(animation);

function animation() {
  splat.update(camera, renderer);
  renderer.render(scene, camera);
}

Helper

To aid development, the MaskMesh objects are rendered with a wireframe material. You can hide this by setting the visible property to false.

Performance

For devices that support SharedArrayBuffer, the sorting process within this library is significantly optimized. This feature enhances the efficiency of data handling, leading to faster rendering times and smoother user experiences.

To check if your device supports SharedArrayBuffer, please refer to https://caniuse.com/sharedarraybuffer

How do i get .splat files?

• https://github.com/dylanebert/gsplat.js#faq

Splat format discussion https://github.com/mkkellogg/GaussianSplats3D/issues/47

License

This project is released under the MIT license. It is built upon several other open-source projects:

• gsplat.js, MIT License (c) 2023 Dylan Ebert
• three.js, MIT License (c) 2010-2023 three.js authors
• antimatter15/splat, MIT License (c) 2023 Kevin Kwok
• UnityGaussianSplatting, MIT License (c) 2023 Aras Pranckevičius

Please note that the license of the original 3D Gaussian Splatting research project is non-commercial. While this library provides an open-source rendering implementation, users should consider the source of the splat data separately.