@zappar/three-gaussian-splat
v0.1.0
Published
This library allows you to render [3D Gaussian Splats](https://github.com/graphdeco-inria/gaussian-splatting) using the 3D rendering platform ThreeJS.
Downloads
7
Maintainers
Keywords
Readme
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
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.