An advanced 3D Gaussian Splatting renderer for THREE.js

Features - Getting Started - Documentation - FAQ

Features

• Load multiple splats files simultaneously (demo)
• Combine and composite splats with regular Meshes (demo)
• Animation (demo)
• Real Time Visual Effects (demo)
• Multiple Camera Views (demo)
• Procedurally generated splats (demo)

Check out all the examples

Getting Started

Copy code

Copy code below in an index.html file.

<style> body {margin: 0;} </style>
<script type="importmap">
{
  "imports": {
    "three": "/node_modules/three/build/three.module.js",
    "@forge-gfx/forge": "/dist/forge.module.js"
  }
}
</script>
<script type="module">
import * as THREE from "three";
import { SplatMesh } from "@forge-gfx/forge";

const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement)

const butterfly = new SplatMesh({ url: "../assets/basic/butterfly.wlg"});
butterfly.quaternion.set(1, 0, 0, 0);
butterfly.position.set(0, 0, -1);
scene.add(butterfly);

renderer.setAnimationLoop(function animate(time) {
  renderer.render(scene, camera);
  butterfly.rotation.y += 0.01;
});
</script>

Web Editor

Remix the glitch starter template

Usage from CDN

<script type="importmap">
  {
    "imports": {
      "three": "https://cdnjs.cloudflare.com/ajax/libs/three.js/0.174.0/three.module.js",
      "forge": "cdn/url/to/forge.module.js"
     }
  }
</script>

Install with NPM

npm install forge-dev

Develop and contribute to the project

The examples fetch the assets from an external URL. To work offline is possible to downloading the assets files locally with the following command:

npm run assets:download

Install Rust if it's not already installed in your machine.

Next, build Forge by running:

npm install
npm run build

This will first build the Rust Wasm component (can be invoked via npm run build:wasm), then Forge itself (npm run build).

Once you've fetched the data and built Forge, you can run run the examples:

npm start

This will run a dev server by default at http://localhost:8080/. Check the console log output to see if yours is served on a different port.

Build troubleshooting

First try cleaning all the build files and re-building everything:

npm run clean
npm install
npm run build

There's no versioning system for assets. If you need to re-download a specific file you can delete that asset file individually or download all assets from scratch:

 npm run assets:clean
 npm run assets:download

Ignore dist directory during development

To ignore the dist directory and prevent accidental commits and merge conflicts

git update-index --assume-unchanged dist/*

To revert and be able to commit into to the dist directory again:

git update-index --no-assume-unchanged dist/*

To list ignored files in case of need to troubleshoot

git ls-files -v | grep '^[a-z]' | cut -c3-

Build docs

Install Mkdocs Material

pip install mkdocs-material

If you hit an externally managed environment error on macOS and if you installed python via brew try:

brew install mkdocs-material

Edit markdown in /docs directory

mkdocs serve

Build Forge website

Build the static site and docs in a site directory.

npm run site:build

You can run any static server in the site directory but for convenience you can run

npm run site:serve

Deploy Forge website

TO-DO

Compress splats

To compress a splat to spz run

npm run assets:compress <file or URL to ply>