Splat files#

loadSplats reads PLY (standard or SuperSplat compressed), SPZ, RAD, and RDX files into a table, and writeSplats writes a table to any of these formats. Both run on a worker by default, so a large file does not block the page. SplatFiles and the per-format classes do the same work on the current thread, in a page, a worker, or Node.

Code: src/worker/splatFiles.ts (loadSplats, loadSplatFile, writeSplats); src/core/files.ts (SplatFiles), ply.ts, compressedPly.ts, spz.ts, rad.ts, and rdx.ts.

// Ext splats by default, in data.bundles.extSplats
const data = await loadSplats("scene.spz");

// Packed splats and packed SH, reporting progress
const packed = await loadSplats(file, {
  layout: "packedSplats",
  sh: "packed",
  onProgress: (f, stage) => bar.update(f, stage),
});

// Write an SPZ file and save it
const bytes = await writeSplats(data, "spz", { version: 3 });
const blob = new Blob([bytes]);
download(blob, "scene.spz");

loadSplats#

loadSplats(source, options?) returns a table (SplatData<L>). The splats are in the bundle named after the layout. A file with a LoD tree adds a lodTree bundle, and a file with spherical harmonics adds an SH bundle (extSh by default). Clustered SH in RAD files is expanded to per-splat SH on the worker.

loadSplatFile(source, options?) takes the same options and returns { splats, shPalette? } (LoadedSplats<L>). The only difference: clustered SH stays a palette. shPalette is an ShPalette, and the table's shLabel bundle indexes it (Spherical harmonics). A palette uses far less memory: 2 bytes per splat plus the palette, against 48 to 60 bytes per splat at SH3. Pass shPalette on to GpuShPalette.upload, writeSplats, and Axes.convert.

RDX, RAD, and PLY are detected by the magic number in their first bytes, and SPZ by a gzip header, SPZ 4's NGSP header, or its extension. A compressed PLY is detected as "ply": the PLY reader tells the two kinds apart by their header.

writeSplats#

writeSplats(data, format, options?) returns the file's bytes. format is "ply", "compressed-ply", "spz", "rad", or "rdx" (a SplatFormat). PLY, compressed PLY, SPZ, and RAD write the splat bundle in any layout, the SH bundle, and the lodTree where the format supports one. They write PBR data (normals, roughness, metallic) only with pbr: true. RDX writes every bundle marked serialize: true as it is, including ext splats' PBR bits.

On a worker, writeSplats transfers the table's arrays (and the palette's) to the worker and puts them back in place afterwards, so the table and its bundle objects are usable again when the promise settles, even if the write fails. Do not use the table while a write is running, and take its arrays from its bundles again afterwards: the ones held before were detached. For the same reason writeSplats takes no signal: an aborted write would leave the arrays on the worker.

Where the work runs#

• Both paths run the same functions, so they give the same results.
• Bytes passed to a worker are transferred: the caller's buffer is detached.
• The shared pool is WorkerPool.default, made on first use with up to 4 workers (Workers).

What each format keeps#

PLY, SPZ, and RAD decode directly into the requested layout. RDX returns every bundle it saved (RDX files) and converts its splats when they are stored in a different layout.

• Spherical harmonics load into an SH bundle beside the splats (Spherical harmonics). The sh option picks the codec: "ext" (default), "packed", or false to skip SH (the degree is then recorded in meta.ignoredShDegree). RDX keeps its stored codec unless sh is given.
• RAD's clustered SH (Spark's build-lod --cluster-sh) loads through loadSplatFile as an ShPalette plus an shLabel bundle. With more than 65,536 entries it loads as per-splat SH. RDX does not store palettes yet; writers expand them.
• Writers include the SH bundle by default (sh: true). Format limits apply: compressed PLY clamps values to ±4 and SPZ to ±1 (Sutro has a few coefficients up to ±4.9). RAD's s8 keeps every value, but uses a coarser step in chunks with outliers.
• RAD files that reference external chunk files are rejected.
• Point-cloud PLYs (positions and colors only) load as small round splats, 0.001 units across.

SPZ#

Niantic's SPZ (nianticlabs/spz) has two containers. SpzFile reads both.

• Version 2 stores rotations as x, y, z in 3 bytes with w >= 0, which loses precision near 180 degrees. Versions 3 and 4 use 4 bytes (smallest-three). Some files put version 4 in the gzip container; that is version 3's layout and loads the same way.
• Both containers store the same bytes per splat. SH: 8-bit codes, (b - 128) / 128, coefficient-major RGB. LoD tree: u16 child counts, then u32 child starts. PBR: Oct24 normals (0 means none), unorm8 roughness, unorm8 metallic. These are the bits an ext splat stores, so PBR values round-trip.
• SPZ 4 stores the LoD tree and PBR in Radix vendor records ("RX": 0x52580001 and 0x52580002), each a zstd frame of the bytes above. It never sets flags 0x40 or 0x80, so upstream's reader skips these records with a warning and loads the rest.
• Upstream records are read from both containers. 0xADBE0002 (safe orbit camera) goes to meta.safeOrbitCamera as { elevationMin, elevationMax, radiusMin } (radians, scene units). 0xADBE0003 is the stored coordinate system. Other record types are skipped and listed in meta.skippedExtensions. Version 4 writes the safe orbit back; the gzip writer writes no upstream records.
• meta.container is "gzip" or "ngsp"; meta.version is the header's version.
• SpzFile.unpack(input, { sh? }) returns the header and raw byte columns (SpzUnpacked) without decoding them. input is bytes or a ReadableStream. gzip is inflated as bytes arrive, SPZ 4 streams are decompressed one at a time, and with sh: false the SH stream (last in SPZ 4) is never read.
• SPZ 4 headers get upstream's checks: the table of contents follows the header, stream counts and sizes match the header, no bytes follow the last stream, and the point count is at most 1024 × file bytes / 9.

zstd#

SPZ 4 compresses with zstd (Zstd.compress, Zstd.decompress). Radix uses the first of these that is available: Node's zlib (compressing at zstdLevel, default 12), the browser's CompressionStream / DecompressionStream("zstd") (no browser has them yet), then fzstd to decode and Radix's own encoder to encode. Radix's encoder codes literals only, with Huffman codes.

Sizes against version 3 (gzip), over 2 GB of columns from the splats viewer's samples and SharedTestModels' SH files:

SPZ 4 does not make files much smaller, so version 3 stays the default. Write version 4 for readers that need it.

Coordinate systems#

SPZ names axes like upstream: three letters for the directions of +x, +y, and +z. For example "RUB" (right, up, back: three.js and SPZ's default), "RDF" (common in PLY files), and "RFU" (z up). Axes.SYSTEMS lists all 16 in SPZ's numbering. A file without a coordinate-system record is "RUB".

• By default a file loads as stored, as in Spark and upstream's UNSPECIFIED. meta.coordinateSystem names its axes.
• With coordinateSystem set, the reader converts while decoding. With M the signed permutation between the two systems, centers and normals become M p, rotations become M R Mᵀ (scales are permuted to match), and each SH band is multiplied by its own matrix. Flips only change signs. Quarter turns (between z-up and y-up systems) mix the coefficients within each band.
• Axes does the same outside the readers. Axes.converter(from, to) converts single values (vec, quat, scales, cov, splat, sh). Axes.convert(data, to, { from?, shPalette? }) converts a whole table in place, in any layout. Axes.matrix(from, to) returns M.
• Upstream flips the sign of SH coefficient 23 (the last in band 4) when y flips. That is a bug: its basis function, x⁴ - 6x²y² + y⁴, is even in every axis. Radix keeps the sign, so degree-4 conversions that flip y differ from upstream at that coefficient.
• A quarter turn can push SH coefficients past SPZ's ±1 range, so writing in a turned system clamps a few (541 of the seashell sample's 194k splats).

Compressed PLY#

SuperSplat and PlayCanvas's splat-transform write a quantized PLY, usually named .compressed.ply. It is valid PLY syntax but not the standard 3DGS layout, so it has its own writer, CompressedPlyFile.write (or writeSplats(data, "compressed-ply")). PlyFile.read reads both kinds; CompressedPlyFile.read is the same function.

The file has a chunk element with one row per 256 splats: the box of their centers (min_x to max_z), the range of their log scales (min_scale_x to max_scale_z) and, in current files, the range of their colors (min_r to max_r; older files have none, and colors then span 0 to 1). The vertex element holds four uint words per splat:

An optional sh element holds spherical harmonics as one uchar per value, channel-major (f_rest_{c * N + k}), mapped as splat-transform does: ((b + 0.5) / 256 - 0.5) * 8, with 0 and 255 at the ends, so values span ±4. They load into the SH bundle like the float ones. A compressed file loads with meta.compressed set to true.

The writer writes the 18-property chunks, an sh element when the data has SH (in the same order as the vertices), and no LoD tree. Log scales are clamped to ±20, as splat-transform does. With the default sort: true the splats come back in a different order than the table's.

SplatFiles and the per-format classes#

These run the same steps on the current thread, without workers:

Types: LoadedSplats, LoadSplatsOptions, SplatFormat, SplatLoadOptions, SplatRequestInit, SplatWriteOptions, SpzWriteOptions, SpzUnpacked, SpzExtension, CoordinateSystem, AxesConverter, SplatSource, WorkerChoice, Progress, ProgressStage, and BytesInput (Uint8Array, ArrayBuffer, or a ReadableStream).

Gotchas#

• loadSplats and loadSplatFile transfer the bytes you pass to the worker. Pass a copy to keep the original.
• A clustered RAD loaded with loadSplats and saved as RAD is written per splat, and is larger. To keep the clusters, load it with loadSplatFile and pass shPalette to writeSplats.
• A file whose format has no LoD tree loads without one. Radix does not build trees.
• writeSplats(data, "rdx") writes every serialized bundle, including bundles of an app's own; mark derived data serialize: false.

Source: docs/files.md