🦎
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 (now, only Babylon.js)
• 🥪 divided into core functionality and other features
• ✨ wrapping official implementation through WebAssembly

Limitations

• Spherical Harmonics (SH) is currently not supported

Install & Usage

For Web3D Engines (example for Babylon.js)

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

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

# for pnpm
pnpm add -D @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";

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

const engine = new Engine(renderCanvas);
const scene = new Scene(engine);

// ...

const spzBuffer = await fetch(spzPath).then((res) => res.arrayBuffer());
const splat = await createGaussianSplattingFromSpz(spzBuffer, scene);

Core package

Install like below.

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

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

Usage example of core package.

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

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

const spzBuffer = await fetch(spzUrl)
  .then((res) => res.arrayBuffer())
  .then((buf) => new Uint8Array(buf));

const splat = await loadSpz(spzBuffer);

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
├─ 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