gaussian-splat-lite 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -7,28 +7,34 @@ 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, 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 `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 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).
+- 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 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 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 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`.
+- 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 delayed cache memory reclamation in `gsl-build-lod` when reserving memory for worker threads.
+- Fixed `gsl-build-lod` briefly using more memory than `--memory-budget` when starting worker threads.
 
 ## [1.4.3] - 2026-10-25
 
@@ -703,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/bin/rad/cluster.js

@@ -12,12 +12,15 @@ import { PagedArray } from "./storage.js";
 const MAX_CODES = 65536;
 // Training reads SAMPLE_SHARE of the splats, and at least SAMPLES_PER_CODE
 // per entry; larger models train on a sample by weight, and only the final
-// assignment reads all. Entries start at evenly spaced training splats,
-// best at heavy ones: on Elevator (3.9M splats after LOD) 16 per entry fit
-// better than all splats, and on C-NorthSouth (111M) 5% fit 8.5% closer
-// than 16 per entry, for 5% more conversion time.
-const SAMPLES_PER_CODE = 16;
-const SAMPLE_SHARE = 0.05;
+// assignment reads all. Entries start at evenly spaced training splats.
+// With codebooks shrunk to keep 16 per entry at 5%, renders of Elevator and
+// JunkShop came 5–14% closer to the uncompressed SH at 10% than at 5%; on
+// C-NorthSouth (111M splats after LOD) clustering took about 185 s, not 170.
+// On Elevator (3.9M splats after LOD), 64 per entry, here all splats, came
+// 5.8% closer than 16 at full detail, with 41% fewer pixels off by more than
+// 32 levels in LOD views, in 18 s instead of 6 s.
+const SAMPLES_PER_CODE = 64;
+const SAMPLE_SHARE = 0.1;
 // Splats per job of a thread, and per call of the kernel.
 const JOB = 4096;
 const BATCH = 1024;
@@ -587,8 +590,8 @@ class Grouper {
 // weighted k-means as Spark does: entries start at evenly spaced splats,
 // each of `iterations` moves them to the weighted mean of their splats, an
 // entry without any stays, and a final pass labels each splat with its
-// nearest entry. Weights are area × opacity. Training uses 5% of the
-// splats, at least 16 per entry, sampled in proportion to their weights;
+// nearest entry. Weights are area × opacity. Training uses 10% of the
+// splats, at least 64 per entry, sampled in proportion to their weights;
 // with many entries, passes search only groups of them. Returns the
 // entries, `count` rows of `dims` SH coefficients, and the labels.
 export async function clusterSh(splats, iterations, module) {

package/docs/BuildRad.md

@@ -59,9 +59,9 @@ gsl-build-lod scene.ply --cluster-sh=20
 gsl-build-lod scene.ply --no-cluster-sh
 ```
 
-By default, SH coefficients are stored as a shared codebook of up to 65,536 entries, and each splat stores the index of its entry. This can substantially reduce SH data for large models; the savings depend on the splat count and SH values. Models with at most 65,536 splats after LOD still store one codebook entry per splat plus labels, so the file may grow. Each splat's view-dependent color comes from its nearest entry, so highlights and reflections can lose some detail. Positions, shapes, base colors and LOD are unchanged. Use `--no-cluster-sh` to disable the codebook.
+By default, SH coefficients are stored as a shared codebook of up to 65,536 entries, and each splat stores the index of its entry. This can substantially reduce SH data for large models; the savings depend on the splat count and SH values. Models with at most 65,536 splats after LOD still store one codebook entry per splat plus an index for each splat, so the file may grow. Each splat's view-dependent color comes from its nearest entry, so highlights and reflections can lose some detail. Positions, shapes, base colors and LOD are unchanged. Use `--no-cluster-sh` to disable the codebook.
 
-The codebook is refined in 10 iterations by default; `--cluster-sh=<n>` sets another number. Clustering runs on as many CPU cores as the memory target leaves room for and usually takes less time than the rest of the conversion. When there are more than 1,048,576 splats after LOD, the iterations use a sample that favors large, opaque splats: 1,048,576 splats or 5% of them, whichever is larger. Only the final assignment visits every splat. With 16,384 or more entries, each iteration and the final assignment compare a splat only with the entries in the groups of similar entries nearest to it; a few splats then get an entry that is nearly, but not exactly, the nearest.
+The codebook is refined in 10 iterations by default; `--cluster-sh=<n>` sets another number. Clustering runs on as many CPU cores as the memory target leaves room for and usually takes less time than the rest of the conversion.
 
 Models without SH, or converted with `--max-sh 0`, are written without a codebook.
 

package/docs/RadStreamScheduler.md

@@ -57,7 +57,7 @@ const streaming = new RadStreamScheduler({
 });
 ```
 
-All inputs use the coordinates stored in their files, relative to `streaming.group`. Detail is chosen across the combined scene, and the inputs share the splat budget, loading concurrency, and both memory budgets. Memory is reserved at the highest SH degree among the inputs, limited by `maxSh`; lower-SH inputs use the same per-Splat storage. Inputs may use different chunk sizes, up to 65,536 Splats per chunk.
+All inputs use the coordinates stored in their files, relative to `streaming.group`. Detail is chosen across the combined scene, and the inputs share the splat budget, loading concurrency, and both memory budgets. Inputs with different SH degrees all use the memory of the highest one, up to `maxSh`.
 
 Each entry accepts the single-input loading options, including `resolveFile`, `manager`, `requestHeader`, and `withCredentials`; options omitted from an entry inherit the scheduler's settings. `sources` must be nonempty. Use separate schedulers for inputs that need independent transforms or budgets.
 
@@ -105,7 +105,7 @@ renderer.setAnimationLoop(() => {
 | `maxResidentGpuBytes` | 1 GiB | GPU memory budget for cached data, in bytes. Set a positive integer when creating the scheduler |
 | `fadeDurationMs` | `200` | Duration of the fade when the scene first appears and when detail changes; `0` switches instantly |
 | `cooldownMs` | `2000` | How long unused detail stays ready for reuse; it can be released sooner when either memory budget is reached. `0` releases it at once |
-| `maxConcurrentLoads` | `4` | Maximum number of simultaneous loads, regardless of page size. |
+| `maxConcurrentLoads` | `4` | Maximum number of simultaneous loads |
 | `manager` | `THREE.DefaultLoadingManager` | Three.js loading manager, including its URL modifiers |
 | `requestHeader` / `withCredentials` | `{}` / `false` | Request settings. Sensitive settings are not sent to other origins |
 | `onChange` | — | Called when the scene needs a redraw |
@@ -137,7 +137,7 @@ Unused detail is released after `cooldownMs`, including while hidden, and loads
 
 Request a redraw from `onChange`, and keep calling `update()` on every animation tick, also when you skip the render. Loading, retries, and fades only make progress inside `update()`.
 
-Each scheduler has a 24 MiB allowance for source texture layers waiting for GPU upload. Repeated `update()` calls do not renew it; rendering submits the queued layers and makes room for more data. Keep rendering while waiting for `firstRenderable`, even before any batches are visible. This allowance does not cap total CPU/GPU memory or uploads from other schedulers.
+New data reaches the screen only when you render, so keep rendering while waiting for `firstRenderable`, even before anything is visible.
 
 ### Picking
 

package/docs/SogStreamScheduler.md

@@ -114,7 +114,7 @@ In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown f
 
 Request a redraw from `onChange`, and keep calling `update()` on every animation tick, also when you skip the render. Loading, retries, and fades only make progress inside `update()`.
 
-Each scheduler has a 24 MiB allowance for source texture layers waiting for GPU upload. Repeated `update()` calls do not renew it; rendering submits the queued layers and makes room for more data. A region larger than the allowance proceeds when no upload bytes are pending. Keep rendering while waiting for `firstRenderable`, even before any batches are visible. This allowance does not cap total CPU/GPU memory or uploads from other schedulers.
+New data reaches the screen only when you render, so keep rendering while waiting for `firstRenderable`, even before anything is visible.
 
 ## Error recovery
 

package/docs/SplatLoader.md

@@ -17,6 +17,7 @@ scene.add(splat);
 ```
 
 Set `loader.maxSh` before loading to limit decoded and stored SH to degree `0`–`4` (default `4`).
+
 The callback form matches the usual Three.js pattern:
 
 ```js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaussian-splat-lite",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "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",