gaussian-splat-lite 1.4.2 → 1.5.0

package/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-27
+
+### Added
+
+- Added `sources` to `RadStreamScheduler` and `SogStreamScheduler` to stream several inputs with one detail selection. The inputs share the splat budget and loading concurrency; RAD inputs also share both memory budgets, and each uses as much memory per Splat as the highest SH degree among them, limited by `maxSh`. See [RAD streaming](docs/RadStreamScheduler.md#multiple-inputs) and [SOG streaming](docs/SogStreamScheduler.md#multiple-inputs).
+- Added an `environment` option to `SogStreamScheduler` and each of its `sources`. Set it to `false` to skip that input's environment.
+- Added `maxSh` to `RadStreamScheduler` and `SogStreamScheduler` to limit SH decoding, storage, and rendering. Set it at creation to `0`–`3` (default `3`) to reduce SH memory use; `0` keeps only the base color. RAD page budgets account for the reduced storage, and the built-in SOG loader skips higher-order SH assets at `0`.
+- Added a loading-time `maxSh` option to `SplatMesh` and `Splats`, and a `SplatLoader.maxSh` setting (`0`–`4`, default `4`). PLY, SPZ, SOG, and RAD loads omit higher SH bands from CPU arrays and GPU source textures.
+- Added default SH codebook compression to `gsl-build-lod`: up to 65,536 shared SH entries and a 16-bit index per splat. Compression can reduce file size at the cost of view-dependent detail; small models may grow. Use `--cluster-sh=<n>` to change the default 10 refinement iterations or `--no-cluster-sh` to store coefficients directly. Clustering uses CPU workers within the memory target. See [SH codebook](docs/BuildRad.md#sh-codebook).
+
+### Changed
+
+- Raised the minimum Node.js version to 22.12 for the package and `gsl-build-lod`.
+- `SplatMesh.maxSh` is now read-only and set through its constructor options, matching the streaming schedulers. Assigning `mesh.maxSh` now throws a `TypeError` in strict-mode code, including ES modules. Create a new mesh to change the limit. The viewer's Max SH control has been removed.
+- RAD streaming now uses fixed 65,536-splat page slots. Smaller chunks use a full slot; chunks larger than 65,536 splats are rejected during initialization.
+- RAD and SOG schedulers now create their own `THREE.Group`; the `group` constructor option has been removed. Add and transform `streaming.group` instead.
+- RAD and SOG streaming upload written texture layers before their batches are first displayed. Each scheduler limits pending source texture uploads to 24 MiB until rendering submits them, preventing skipped renders from accumulating larger uploads. A larger SOG region proceeds alone.
+- `gsl-build-lod` now quantizes SH in fixed `1/128` steps instead of using adaptive per-band ranges. Both codebook and direct output clip coefficients to `[-127/128, 127/128]`. With `--no-cluster-sh`, original SPZ splats retain their SH coefficients except `-1`, which clips to `-127/128`.
+
+### Fixed
+
+- Fixed delayed cache memory reclamation in `gsl-build-lod` when reserving memory for worker threads.
+
+## [1.4.3] - 2026-10-25
+
+### Added
+
+- Added `--within-dist <x,y,z,radius>` to `gsl-build-lod` to keep splat centers inside or on a sphere in input coordinates before building LOD. See [Building RAD files](docs/BuildRad.md).
+
+### Changed
+
+- Streamed SOG keeps surrounding regions in its detail budget, with less detail behind the camera and corrected distances for oversized regions. Added runtime-adjustable `lodBehindPenalty` (default `4`) and `lodDistanceShrink` (default `0.75`).
+
+### Removed
+
+- Removed raycast hit `sourceIndex`, `Splats.getSourceIndex()`, and `RadStreamScheduler.getGlobalIndex()`. Use `hit.object.splats.getSplat(hit.index)` to read the current hit; streamed indices can change when the visible detail changes.
+
+### Fixed
+
+- Streamed SOG waits for initial detail selection before rejecting `firstRenderable`, including when an empty environment finishes last.
+- Streamed SOG rejects `firstRenderable` when all required loads fail permanently, even while the camera keeps moving.
+- Streamed SOG retains displayed coverage when detail selection fails, stopping further loading while existing fades finish.
+
 ## [1.4.2] - 2026-10-24
 
 ### Changed
@@ -660,7 +703,8 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 - Initial public release of the Three.js Gaussian Splatting renderer.
 
-[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.2...HEAD
+[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.3...HEAD
+[1.4.3]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.2...v1.4.3
 [1.4.2]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.1...v1.4.2
 [1.4.1]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.0...v1.4.1
 [1.4.0]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.3.2...v1.4.0

package/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Development setup
 
-Requires Node.js 20.19+ or 22.12+ and Rust via `rustup`. `npm run build:wasm` installs the `wasm32-unknown-unknown` target if needed.
+Requires Node.js 22.12 or later and Rust via `rustup`. `npm run build:wasm` installs the `wasm32-unknown-unknown` target if needed.
 
 ```bash
 npm ci

package/README.md

@@ -180,7 +180,7 @@ const streaming = new SogStreamScheduler({
 
 ## Development
 
-Requires Node.js 20.19+ or 22.12+, Rust via `rustup`, and the `wasm32-unknown-unknown` target. `build:wasm` installs `wasm-pack` through Cargo if needed.
+Requires Node.js 22.12 or later, Rust via `rustup`, and the `wasm32-unknown-unknown` target. `build:wasm` installs `wasm-pack` through Cargo if needed.
 
 ```sh
 npm ci

package/bin/build-lod.js

@@ -7,6 +7,7 @@ import {
   parentPort,
   workerData,
 } from "node:worker_threads";
+import { clusterSh, codebookKernel } from "./rad/cluster.js";
 import { readInput } from "./rad/input.js";
 import { buildLod } from "./rad/lod.js";
 import { Pool } from "./rad/parallel.js";
@@ -24,6 +25,11 @@ Output: <input-stem>-lod.rad. Existing files are not overwritten.
 Options:
   --lod-base <base>      LOD spacing (default: 1.75, range: 1.1..16)
   --max-sh <0..3>        Maximum SH degree (default: 3)
+  --within-dist <x,y,z,radius>
+                        Keep splat centers within this sphere (input coordinates)
+  --cluster-sh[=<n>]     Store SH as a codebook of up to 65536 entries, refined
+                        in n iterations (default: enabled, 10 iterations)
+  --no-cluster-sh        Store SH coefficients without a codebook
   --rad-chunked          Write a .rad header and separate .radc files
   --memory-budget <GiB>  Target memory in GiB (default: 4, minimum: 1)
   --temp-dir <path>      Temporary file location (default: system temp)
@@ -32,13 +38,14 @@ Options:
 
 SH4 inputs are accepted; coefficients above --max-sh are discarded.
 The memory target covers the whole conversion, worker threads included.
-No compilation is required.`;
+Requires Node.js 22.12 or later. No compilation is required.`;
 
 function parse(args) {
   const options = {
     inputs: [],
     lodBase: 1.75,
     maxSh: 3,
+    clusterSh: 10,
     budget: 4 * GIB,
     chunked: false,
   };
@@ -53,6 +60,19 @@ function parse(args) {
       options.chunked = true;
       continue;
     }
+    if (arg === "--no-cluster-sh") {
+      options.clusterSh = undefined;
+      continue;
+    }
+    if (arg === "--cluster-sh" || arg.startsWith("--cluster-sh=")) {
+      const value = arg === "--cluster-sh" ? "10" : arg.slice(13);
+      options.clusterSh = value.trim() ? Number(value) : Number.NaN;
+      if (!Number.isSafeInteger(options.clusterSh) || options.clusterSh < 0)
+        throw new Error(
+          "--cluster-sh iterations must be a nonnegative integer",
+        );
+      continue;
+    }
     if (!arg.startsWith("-")) {
       options.inputs.push(arg);
       continue;
@@ -62,6 +82,7 @@ function parse(args) {
     const key = {
       "--lod-base": "lodBase",
       "--max-sh": "maxSh",
+      "--within-dist": "withinDist",
       "--memory-budget": "budget",
       "--temp-dir": "tempDir",
       "-o": "output",
@@ -86,6 +107,16 @@ function parse(args) {
     options.maxSh > 3
   )
     throw new Error("--max-sh must be an integer between 0 and 3");
+  if (options.withinDist !== undefined) {
+    const values = options.withinDist
+      .split(",")
+      .map((value) => (value.trim() ? Number(value) : Number.NaN));
+    if (values.length !== 4 || !values.every(Number.isFinite) || values[3] < 0)
+      throw new Error(
+        "--within-dist must be x,y,z,radius with finite numbers and a nonnegative radius",
+      );
+    options.withinDist = values;
+  }
   if (
     !Number.isFinite(options.budget) ||
     options.budget < GIB ||
@@ -100,7 +131,7 @@ function parse(args) {
   return options;
 }
 
-async function convert(input, options, cancelled) {
+async function convert(input, options, kernel, cancelled) {
   const output =
     options.output ??
     path.join(
@@ -120,7 +151,7 @@ async function convert(input, options, cancelled) {
     const splats = await readInput(input, options.maxSh, workspace);
     const count = splats.length;
     pool = new Pool(workspace, count);
-    splats.retain(pool);
+    splats.retain(pool, options.withinDist);
     console.log(
       `Read ${count} splats, SH${splats.inputSh}, in ${((performance.now() - start) / 1000).toFixed(2)}s`,
     );
@@ -132,8 +163,10 @@ async function convert(input, options, cancelled) {
       console.log(
         `Removed ${splats.invalid} splats with NaN or infinite values or a zero rotation`,
       );
-    const empty = count - splats.invalid - splats.length;
+    const empty = count - splats.invalid - splats.cropped - splats.length;
     if (empty) console.log(`Removed ${empty} empty splats`);
+    if (splats.cropped)
+      console.log(`Removed ${splats.cropped} splats outside --within-dist`);
     if (!splats.length) throw new Error("Input contains no usable splats");
     const leaves = splats.length;
     const lodStart = performance.now();
@@ -142,11 +175,24 @@ async function convert(input, options, cancelled) {
     console.log(
       `Built ${splats.length} LOD splats from ${leaves} leaves in ${((performance.now() - lodStart) / 1000).toFixed(2)}s`,
     );
+    let codebook;
+    if (kernel && !splats.maxSh)
+      console.log("No SH coefficients to cluster; writing without a codebook");
+    else if (kernel) {
+      const clusterStart = performance.now();
+      codebook = await clusterSh(splats, options.clusterSh, kernel);
+      // RAD encoding now reads only the codebook and labels.
+      for (const column of splats.sh) column.dispose();
+      console.log(
+        `Clustered SH into ${codebook.count} codes in ${((performance.now() - clusterStart) / 1000).toFixed(2)}s`,
+      );
+    }
     const bytes = await writeRad(
       splats,
       output,
       options.chunked,
       options.lodBase,
+      codebook,
     );
     console.log(
       `Wrote ${(bytes / 1048576).toFixed(2)} MiB in ${((performance.now() - start) / 1000).toFixed(2)}s total`,
@@ -158,11 +204,13 @@ async function convert(input, options, cancelled) {
 }
 
 async function run(options, cancelled) {
+  // Load the requested codebook kernel before converting any inputs.
+  const kernel = options.clusterSh === undefined ? undefined : codebookKernel();
   let failed = 0;
   for (const input of options.inputs) {
     if (Atomics.load(cancelled, 0)) return;
     try {
-      await convert(input, options, cancelled);
+      await convert(input, options, kernel, cancelled);
     } catch (error) {
       if (Atomics.load(cancelled, 0)) return;
       console.error(`${input}: ${error.message ?? error}`);
@@ -231,6 +279,9 @@ try {
       console[method] = (...args) => parentPort.postMessage({ method, args });
     await run(workerData.options, workerData.cancelled);
   } else {
+    const [major, minor] = process.versions.node.split(".").map(Number);
+    if (major < 22 || (major === 22 && minor < 12))
+      throw new Error("gsl-build-lod requires Node.js 22.12 or later");
     const options = parse(process.argv.slice(2));
     if (!options) console.log(help);
     else await start(options);