🦎
spz-loader

About

spz-loader is a set of npm packages for loading .spz, a type of 3D Gaussian Splatting file format. For more information on the .spz format, see the blog post published by Niantic and the GitHub repository.

spz-loader provides @spz-loader/core, which is a pure decoding facility using nianticlabs/spz converted to wasm by Emscripten, and loader packages for various platforms that depend on it.

Features

• 🍱 decode .spz file into pure-JS Object
• 🧩 integration to 3D engines (Babylon.js/PlayCanvas)
• 🥪 divided into core functionality and other features
• ✨ wrapping official implementation through WebAssembly

Limitations

• Spherical Harmonics (SH) is currently not supported

Packages

package	version	description
core		core logics for decode .spz
babylonjs		integration for Babylon.js GaussianSplattingMesh
playcanvas		integration for PlayCanvas Engine and GSplat Entity

Install & Usage

Example of Babylon.js

Install like below. @spz-loader/babylonjs requires Babylon.js version 7 or later.

# for npm
npm i @babylonjs/core @spz-loader/babylonjs

# for pnpm
pnpm add @babylonjs/core @spz-loader/babylonjs

Code example of ESModule or TypeScript.

import "./style.css";

import { Engine, Scene } from "@babylonjs/core";
import { createGaussianSplattingFromSpz } from "@spz-loader/babylonjs";

import spzPath from "../assets/hornedlizard.spz?url";

const engine = new Engine(renderCanvas);
const scene = new Scene(engine);
// ...
const splat = await createGaussianSplattingFromSpzUrl(spzPath, scene);

Core package

Install like below.

# for npm
npm i @spz-loader/core

# for pnpm
pnpm add @spz-loader/core

Usage example of core package.

import { loadSpz } from "@spz-loader/core";

import spzUrl from "../assets/racoonfamily.spz?url";

const splat = await loadSpzFromUrl(spzUrl);
console.log(splat.numPoints);

Developing spz-loader

Environment

Project author's local environment is below.

• Windows 11 Home
• Node.js 20.18.1
• pnpm 9.14.2
• Docker Desktop
  • with VSCode dev container
• Emscripten 3.1.72 (on docker)

Setup

Clone this repo and submodule

git clone https://github.com/drumath2237/spz-loader.git

git submodule update --init --recursive

Repository structure is below. spz-loader is a monorepo project setup by pnpm-workspace.

/
├─ packages/
│    ├─ core/
│    │    └─ lib/
│    │         ├─ spz-wasm/
│    │         │    └─ spz/  <-- submodule
│    │         ├─ build.sh
│    │         └─ index.ts
│    ├─ babylonjs/
│    │    └─ lib/
│    │         └─ index.ts
│    └─ playcanvas/
│         └─ lib/
│              └─ index.ts
├─ package.json
├─ pnpm-lock.yaml
└─ pnpm-workspace.yaml

To install dependencies, you can run pnpm install on the root directory.

pnpm install

Build packages

Run build script build:all. This command does follow:

1. Build spz(C++) to WebAssembly by Emscripten on a Docker container
2. Build @spz-loader/core package by Vite library mode
3. Build @spz-loader/babylonjs package by Vite library mode

pnpm build:all

Author

@drumath2237