gaussian-splat-lite 1.3.2 → 1.4.0

package/dist/types/data/RadPagedSplats.d.cts

@@ -1,7 +1,7 @@
 import { IndexedSplats } from "./IndexedSplats.cjs";
 import type { ReorderedSplatResult } from "./defines.cjs";
 export type RadPagedSplatsOptions = {
-  /** Maximum records in one decoded chunk. Defaults to Spark's 65,536. */
+  /** Maximum records in one decoded chunk. Defaults to 65,536. */
   pageSize?: number;
   pageCount: number;
   numSh: number;

package/dist/types/data/RadPagedSplats.d.ts

@@ -1,7 +1,7 @@
 import { IndexedSplats } from "./IndexedSplats.js";
 import type { ReorderedSplatResult } from "./defines.js";
 export type RadPagedSplatsOptions = {
-  /** Maximum records in one decoded chunk. Defaults to Spark's 65,536. */
+  /** Maximum records in one decoded chunk. Defaults to 65,536. */
   pageSize?: number;
   pageCount: number;
   numSh: number;

package/dist/types/loaders/rad/radFormat.d.cts

@@ -7,7 +7,7 @@ export type RadChunkRange = {
   count?: number;
   filename?: string;
 };
-/** Spark RAD version 1 directory. Child references use file-global indices. */
+/** RAD version 1 directory. Child references use file-global indices. */
 export type RadMeta = {
   version: number;
   type: "gsplat";
@@ -43,7 +43,7 @@ export type RadDecodedChunk = PostDecodeSplatData & {
   lodRadii?: Float32Array;
 };
 export declare function unpackRadChunk(decoded: RadDecodedChunk): RadChunkData;
-/** Without chunkSize, Spark treats the dataset as one chunk. */
+/** Without chunkSize, the dataset is treated as one chunk. */
 export declare function getRadChunkSpan(
   meta: RadMeta,
   index: number,

package/dist/types/loaders/rad/radFormat.d.ts

@@ -7,7 +7,7 @@ export type RadChunkRange = {
   count?: number;
   filename?: string;
 };
-/** Spark RAD version 1 directory. Child references use file-global indices. */
+/** RAD version 1 directory. Child references use file-global indices. */
 export type RadMeta = {
   version: number;
   type: "gsplat";
@@ -43,7 +43,7 @@ export type RadDecodedChunk = PostDecodeSplatData & {
   lodRadii?: Float32Array;
 };
 export declare function unpackRadChunk(decoded: RadDecodedChunk): RadChunkData;
-/** Without chunkSize, Spark treats the dataset as one chunk. */
+/** Without chunkSize, the dataset is treated as one chunk. */
 export declare function getRadChunkSpan(
   meta: RadMeta,
   index: number,

package/docs/BuildRad.md

@@ -0,0 +1,91 @@
+# Building RAD files
+
+[Back to documentation](../README.md#documentation)
+
+Convert PLY or SPZ models into RAD files with levels of detail (LOD), ready for [RAD streaming](RadStreamScheduler.md). Requires Node.js 20.19+ on the 20.x branch, or 22.12+. No compilation is required.
+
+```sh
+npm install --global gaussian-splat-lite
+gsl-build-lod scene.ply
+```
+
+This writes `scene-lod.rad` beside the input. Large models can take a long time to convert.
+
+To run without a global installation:
+
+```sh
+npx --package gaussian-splat-lite gsl-build-lod scene.ply
+```
+
+From a repository checkout, first build the decoder with `npm run build:wasm:lod` (requires Rust), then use `npm run build-lod -- <input>` with the same options. The full `npm run build:wasm` command also builds the decoder.
+
+## Inputs and output
+
+Inputs must be `.ply` or `.spz` files. Splats with NaN or infinite values, or a zero rotation, are skipped, and the conversion reports how many.
+
+```sh
+# Convert several files, each to its own RAD file.
+gsl-build-lod room.ply garden.spz
+
+# Choose an output path for a single input.
+gsl-build-lod scene.ply -o output/scene.rad
+
+# Keep only the base color, reducing file size and memory use.
+gsl-build-lod scene.ply --max-sh 0
+```
+
+The output directory must exist. Existing output files, including matching `.radc` files when using `--rad-chunked`, are never overwritten. Choose a different output name or remove the old files before converting again. Output files are first written under hidden temporary names in the output directory and receive their final names only after all of them are complete. Failed conversions return a nonzero exit code and remove their output files; if a file cannot be removed, a warning shows its path.
+
+The output keeps up to SH3. SH4 inputs are accepted and converted to SH3 or the level chosen with `--max-sh`. Higher SH levels retain more view-dependent color and increase file size. Conversion is lossy, so colors and shape can differ slightly from the source.
+
+## LOD spacing
+
+```sh
+gsl-build-lod scene.ply --lod-base 1.75
+```
+
+`--lod-base` controls the spacing between detail levels (default `1.75`, range `1.1`–`16`). Smaller values produce more intermediate levels and usually larger files; larger values produce fewer levels and usually smaller files. This setting does not discard input splats.
+
+## Memory and temporary storage
+
+```sh
+gsl-build-lod scene.ply --memory-budget 16 --temp-dir /fast-disk/rad-temp
+```
+
+`--memory-budget` sets a target in GiB (default `4`, minimum `1`, fractional values accepted). Values such as `16` are supported when enough RAM is available. Lower targets may make conversion slower and require more temporary disk space; output quality is unchanged. If conversion reports insufficient memory, increase this value.
+
+The target covers the whole conversion, worker threads included: the converter measures its memory as it runs and keeps within it. Leave room for the operating system and other applications.
+
+`--temp-dir` chooses where temporary working files are stored; the default is the system temporary directory. Use a fast disk with enough free space, as temporary files can be much larger than the input. Each conversion keeps them in its own `gsl-build-rad-*` folder there, which is removed when the conversion finishes or fails; if it cannot be removed, a warning shows its path.
+
+## Split files
+
+```sh
+gsl-build-lod scene.ply --rad-chunked
+```
+
+This writes `scene-lod.rad` plus `scene-lod-0.radc`, `scene-lod-1.radc`, and so on.
+
+Host all files together in the same directory and load the `.rad` file. A single `.rad` file also supports streaming; its server must support HTTP Range requests.
+
+```js
+import { RadStreamScheduler } from "gaussian-splat-lite";
+
+const streaming = new RadStreamScheduler({
+  url: "/models/scene-lod.rad",
+});
+```
+
+See [RadStreamScheduler](RadStreamScheduler.md) for the complete loading and display example.
+
+## Options
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `--lod-base <base>` | `1.75` | LOD spacing, from `1.1` to `16`; smaller values retain more detail levels. |
+| `--max-sh <0..3>` | `3` | Highest SH degree to keep, limited by the input. |
+| `--memory-budget <GiB>` | `4` | Target memory use in GiB, at least `1`; for example `16`. |
+| `--temp-dir <path>` | System temp directory | Location for temporary files; created if needed. |
+| `--rad-chunked` | Disabled | Write a header and separate `.radc` files. |
+| `-o <path>` or `--output <path>` | `<input-stem>-lod.rad` | Output path; requires exactly one input. |
+| `-h` or `--help` | — | Show command help. |

package/docs/RadStreamScheduler.md

@@ -2,7 +2,9 @@
 
 [Back to documentation](../README.md#documentation)
 
-Shows large RAD scenes by loading only the detail the camera needs, and updating it as the camera moves. It supports RAD version 1 files with levels of detail (LOD), either as a single `.rad` file or split into a header and `.radc` pages. It works on WebGPU and WebGL2, and needs no Spark runtime.
+Shows large RAD scenes by loading only the detail the camera needs, and updating it as the camera moves. It supports RAD version 1 files with levels of detail (LOD), either as a single `.rad` file or split into a header and `.radc` pages. It works on WebGPU and WebGL2.
+
+To convert your own models, see [Building RAD files](BuildRad.md).
 
 ```js
 import { RadStreamScheduler } from "gaussian-splat-lite";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaussian-splat-lite",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Three.js Gaussian Splatting renderer with WebGPU/WebGL2, GPU sorting, streaming LOD, and high-precision GIS/ECEF support. Supports PLY, SPZ, SOG and RAD.",
   "author": "William Liu <lyz15972107087@gmail.com>",
   "type": "module",
@@ -8,6 +8,9 @@
   "main": "./dist/gaussian-splat-lite.cjs",
   "module": "./dist/gaussian-splat-lite.module.js",
   "types": "./dist/types/index.d.mts",
+  "bin": {
+    "gsl-build-lod": "./bin/build-lod.js"
+  },
   "exports": {
     ".": {
       "import": {
@@ -27,9 +30,11 @@
     "build:site": "vite build --config vite.site.config.js",
     "build:types": "node scripts/check-declarations.js && node scripts/build-types.js",
     "build:wasm": "node rust/build_wasm.js",
+    "build:wasm:lod": "node rust/build_wasm.js --lod",
+    "build-lod": "node bin/build-lod.js",
     "check": "node scripts/check-js.js && tsc --noEmit && node scripts/check-declarations.js",
     "check:rust": "cargo fmt --manifest-path rust/Cargo.toml --all -- --check",
-    "clean": "rm -rf dist/ node_modules/ rust/target/ rust/gaussian-splat-rs/pkg/",
+    "clean": "rm -rf dist/ bin/decoder/ node_modules/ rust/target/ rust/gaussian-splat-rs/pkg/",
     "dev": "vite --config vite.site.config.js --host",
     "format": "biome format .",
     "format:fix": "biome format . --fix",
@@ -44,6 +49,7 @@
     "test:rust": "cargo test --manifest-path rust/Cargo.toml --workspace --locked"
   },
   "files": [
+    "bin",
     "dist",
     "docs",
     "CHANGELOG.md",
@@ -76,7 +82,7 @@
     "publint": "0.3.24",
     "three": "0.186.0",
     "typescript": "^5.7.3",
-    "vite": "^6.0.11",
+    "vite": "^6.4.4",
     "vite-plugin-arraybuffer": "^0.1.4",
     "vite-plugin-glsl": "^1.3.1"
   },