How to use Three.js's native Gaussian Splatting support (GaussianSplat, SPZ). Load .spz/.ksplat/.splat/glTF splats, pick a file format, and run a capture-to-render workflow with Polycam, Luma AI, Scaniverse, and SuperSplat.
Ben Houston • • 8 min read
The upcoming Three.js r186 release adds native 3D Gaussian Splatting support, and it's a big deal: splats have been usable in Three.js for a while through community add-ons, but now they're a first-class citizen of the engine, with a built-in mesh type and s for the major formats.
I covered the underlying technical details in an earlier post, Adding Native Gaussian Splatting Support to Three.js. This one is the practical companion: what Gaussian Splats are good for, how to load and render one in a few lines of code, which file format to pick, and how to go from a real-world capture to a splat you can drop into a Three.js scene.
Gaussian Splats# #
A Gaussian Splat is a point cloud where every point is a fuzzy, oriented, colored 3D ellipsoid (a "splat") instead of a hard vertex. Render thousands to millions of them, sorted back-to-front, and they blend into a photorealistic image, without any of the meshing, UV unwrapping, or material baking that traditional surface reconstruction needs.
That makes splats a great fit for capturing real-world objects and scenes and showing them in high fidelity, especially subjects that are hard to model by hand: foliage, fur, reflective or translucent surfaces, cluttered rooms, museum artifacts. Because a splat is built directly from photos rather than a hand-authored mesh, the result looks like the source material with a fraction of the traditional reconstruction work, and once it's loaded you treat it like any other object in your Three.js scene: sorted and shaded fresh each frame.
There is a scale limit worth knowing up front, though: GaussianSplat
is built for a single captured object or a room-scale scene, not an entire city block. It has no level-of-detail (LOD) streaming and no spatial segmentation or culling, so a city-scale capture or a multi-gigabyte splat cloud needs tiling or reduction by hand before it will run smoothly. Large-scene tooling can sit on top of this foundation later, and I go into that groundwork in the implementation post.
an SPZ file# #
Here's the whole pipeline, start to finish: load a .spz
file, wrap it in a mesh, and render it.
import * as THREE from 'three/webgpu';
import { SPZ } from 'three/addons/s/SPZ.js';
import { GaussianSplat } from 'three/addons/objects/GaussianSplat.js';
const renderer = new THREE.WebGPURenderer();
await renderer.init();
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera( 50, window.innerWidth / window.innerHeight, 0.01, 100 );
camera.position.set( 0, 0.3, 2 );
// 1. Load the splat data
const splatGeometry = await new SPZ().loadAsync( 'model.spz' );
// 2. Wrap it in a mesh and add it to the scene
const splats = new GaussianSplat( splatGeometry );
scene.add( splats );
// 3. Render as usual. The mesh sorts itself every frame by default.
renderer.setAnimationLoop( () => {
renderer.render( scene, camera );
} );
That's really all there is to it: one call, one new GaussianSplat( geometry )
, and a scene.add()
. Because GaussianSplat
extends THREE.Mesh
, it composes with the rest of the scene graph just like any other object, so transforms, visible
, and raycasting groups all work the way you'd expect.
One requirement to keep in mind: GaussianSplat
needs WebGPURenderer
. The renderer is built from TSL nodes plus compute shaders for the depth sort, so make sure both three/webgpu
and three/tsl
resolve in your import map.
Picking a file format# #
Splats come in several file formats depending on where they were captured or exported, and Three.js ships five s to cover them. All five produce the same internal BufferGeometry
shape (position
, covariance
, color
, and optional packed sphericalHarmonics1..3
attributes), so whichever you use, GaussianSplat
consumes the result identically:
| Extension | Notes | |
|---|---|---|
SPZ |
.spz |
Recommended. Niantic's compact format. v4 is zstd-compressed and streamed section-by-section: smallest files and fastest to load. Also reads legacy v1–v3 (gzip). |
GaussianSplatPLY |
.ply |
Most interoperable. Native output of the original 3D Gaussian Splatting research code and most training/cleanup tools, so this is the format you receive most often. Uncompressed and per-vertex text/binary, large on disk and slow to load compared to .spz . |
KSPLAT |
.ksplat |
Format used by the GaussianSplats3D viewer. Useful if you already have assets from that pipeline. |
SPLAT |
.splat |
Original fixed 32-byte-per-splat format (antimatter15/splat). Uncompressed, easy to generate, large on disk. |
GLTFGaussianSplatExtension |
.gltf / .glb |
Implements the |
KHR_gaussian_splatting |
If you get to choose the format, use SPZ version 4 for viewers: it gives you the smallest transfer size and the fastest parse.
PLY splats#
Splats also often arrive as .ply
files, since that's the native output of the original 3D Gaussian Splatting research code and of many training and cleanup tools. GaussianSplatPLY
handles them, following the same pattern as SPZ
and SPLAT
:
import { GaussianSplatPLY } from 'three/addons/s/GaussianSplatPLY.js';
import { GaussianSplat } from 'three/addons/objects/GaussianSplat.js';
const splatGeometry = await new GaussianSplatPLY().loadAsync( 'point_cloud.ply' );
scene.add( new GaussianSplat( splatGeometry ) );
This is the right to reach for when a splat only exists as a raw .ply
export.
glTF splats#
If your splat is embedded in a glTF file, there's one extra setup step. Because GaussianSplat
needs WebGPURenderer
, GLTF
doesn't register the glTF splat plugin for you automatically, so you register it yourself:
import { GLTF } from 'three/addons/s/GLTF.js';
import { GLTFGaussianSplatExtension } from 'three/addons/s/GLTFGaussianSplatExtension.js';
const = new GLTF();
.register( ( parser ) => new GLTFGaussianSplatExtension( parser ) );
const gltf = await .loadAsync( 'scene.gltf' );
scene.add( gltf.scene ); // splat primitives arrive as GaussianSplat instances
With that registered, a mesh primitive using KHR_gaussian_splatting
loads as a GaussianSplat
(or a Group
of them, for multi-primitive meshes) and lands in the returned scene graph like any other glTF node, mixed in alongside regular meshes, cameras, and animations if the file has them.
SPLAT and KSPLAT files (legacy formats)#
SPLAT
and KSPLAT
exist mainly for legacy compatibility, covering assets and pipelines built around antimatter15/splat
and the GaussianSplats3D
viewer.
The API matches SPZ
closely, so swapping between them is just a matter of picking the right class and pointing it at the matching extension:
import { SPLAT } from 'three/addons/s/SPLAT.js';
import { GaussianSplat } from 'three/addons/objects/GaussianSplat.js';
const splatGeometry = await new SPLAT().loadAsync( 'model.splat' );
scene.add( new GaussianSplat( splatGeometry ) );
js
import { KSPLAT } from 'three/addons/s/KSPLAT.js';
import { GaussianSplat } from 'three/addons/objects/GaussianSplat.js';
const splatGeometry = await new KSPLAT().loadAsync( 'model.ksplat' );
scene.add( new GaussianSplat( splatGeometry ) );
Both s produce the same BufferGeometry
shape as SPZ
, so GaussianSplat
and everything downstream of it (sorting, rendering, glTF export) behaves identically regardless of which you used to get there.
Capture, clean up, convert, render# #
Getting from a real-world subject to a splat in your Three.js scene takes four steps.
1. Capture#
Start by walking around your subject with a mobile scanning app. Overlapping photos or video go to the app (or its cloud backend), which reconstructs a splat from them. A few apps cover this well:
Gaussian Splat capture in the mobile app, cloud processing.Polycam:Niantic's mobile scanning app, with on-device Gaussian Splat capture and export straight toScaniverse:.spz
.consumer splat-capture app, cloud-processed.Luma AI:
Any of the three will reconstruct a usable splat from your capture.
2. Clean up#
Raw reconstructions tend to come out with stray floater splats, background clutter, and rough edges, so it's worth trimming those before you ship.
has its own cropping and cleanup tools, handy if you captured with it and want to stay in one app.Polycam(PlayCanvas's free web-based editor) is purpose-built for splat editing: cropping, erasing floaters, re-exporting. It works with splats from any source, so reach for it when you want more control than a capture app gives, or when the splat came from somewhere else.SuperSplat
3. Convert to SPZ#
Once you have a clean splat (usually as .ply
or .splat
), convert it to .spz
v4 before it in Three.js:
uploadNiantic's online SPZ converter:.ply
/.splat
, download.spz
.- If you captured with
Scaniverse, you can skip this step entirely, since it exports.spz
v4 directly.
4. Render#
With a .spz
file in hand, drop it into your project and load it with SPZ
and GaussianSplat
, exactly as in the example earlier in this post.