gaussian-splat-lite 1.4.3 → 1.5.1

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.5.1] - 2026-10-27
+
+### Changed
+
+- `gsl-build-lod` SH codebooks now match the original view-dependent color of large models more closely. Conversion takes slightly longer.
+
+## [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; inputs with different SH degrees all use the memory of the highest one, up to `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 memory use; `0` keeps only the base color, and streamed SOG then also skips downloading SH data.
+- Added a loading-time `maxSh` option to `SplatMesh` and `Splats`, and a `SplatLoader.maxSh` setting (`0`–`4`, default `4`). Lower values reduce memory use.
+- Added SH codebook compression to `gsl-build-lod`, on by default: splats share up to 65,536 SH entries. This can make large files much smaller at the cost of some view-dependent detail; small models may grow. Use `--cluster-sh=<n>` to change the default 10 refinement iterations or `--no-cluster-sh` to store SH without a codebook. Clustering stays within `--memory-budget`. 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 no longer accepts files with chunks of more than 65,536 splats. Files from `gsl-build-lod` are unaffected.
+- 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 streamed data now reaches the GPU only when you render. Keep rendering, not just calling `update()`, while waiting for `firstRenderable`.
+- With `--no-cluster-sh`, `gsl-build-lod` now keeps the view-dependent color of SPZ inputs almost exactly.
+
+### Fixed
+
+- Fixed `gsl-build-lod` briefly using more memory than `--memory-budget` when starting worker threads.
+
 ## [1.4.3] - 2026-10-25
 
 ### Added
@@ -680,7 +709,9 @@ 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.3...HEAD
+[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.3...v1.5.0
 [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

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";
@@ -26,6 +27,9 @@ Options:
   --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)
@@ -34,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,
   };
@@ -55,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;
@@ -113,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(
@@ -157,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`,
@@ -173,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}`);
@@ -246,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);