gaussian-splat-lite 1.4.2 → 1.4.3

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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 +680,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/bin/build-lod.js

@@ -24,6 +24,8 @@ 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)
   --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)
@@ -62,6 +64,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 +89,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 ||
@@ -120,7 +133,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 +145,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();

package/bin/rad/parallel.js

@@ -9,13 +9,12 @@ import {
 import { Lookup, NONE } from "./grid.js";
 import { HALF, halfBits } from "./math.js";
 import {
-  EMPTY,
   INVALID,
-  KEEP,
   LATER,
   Merger,
   SH_DIMS,
   Similarities,
+  filterRecord,
   refresh,
   validRecord,
 } from "./splats.js";
@@ -231,14 +230,15 @@ export class Pool {
     this.run(COPY, count, 1024);
   }
 
-  // Refreshes and checks `count` splats from `base` in place, setting KEEP,
-  // INVALID, EMPTY or LATER in `results`; see Splats.retain().
-  check(splats, base, count) {
+  // Refreshes, checks and optionally crops `count` splats from `base` in
+  // place, storing their filter states in `results`; see Splats.retain().
+  check(splats, base, count, withinDist) {
     this.share({
       splatRecords: splats.records.directory,
       splatSh: splats.sh
         .slice(0, splats.maxSh)
         .map((column) => column.directory),
+      withinDist,
     });
     Atomics.store(this.control, BASE, base);
     this.run(CHECK, count, 1024);
@@ -370,6 +370,7 @@ class Task {
     if (state.column)
       this.column = new SharedColumn(views, state.column, Uint16Array);
     if (state.splatRecords) {
+      this.withinDist = state.withinDist;
       this.splatRecords = new SharedColumn(
         views,
         state.splatRecords,
@@ -450,7 +451,7 @@ class Task {
       for (let d = 0; d < dims; d++)
         if (!Number.isFinite(HALF[row[at + d]])) return INVALID;
     }
-    return record[3] > 0 && record[14] > 0 ? KEEP : EMPTY;
+    return filterRecord(record, this.withinDist);
   }
 
   copy(from, to) {

package/bin/rad/splats.js

@@ -20,8 +20,9 @@ export const SH_DIMS = [9, 15, 21];
 export const KEEP = 0;
 export const INVALID = 1;
 export const EMPTY = 2;
+export const CROPPED = 3;
 // A worker found a page that is not cached.
-export const LATER = 3;
+export const LATER = 4;
 
 // Sets a record's feature size and area from its scales and opacity.
 export function refresh(record) {
@@ -45,6 +46,16 @@ export function validRecord(record) {
   return true;
 }
 
+// Classifies a valid record after refresh(), including optional cropping.
+export function filterRecord(record, withinDist) {
+  if (record[3] <= 0 || record[14] <= 0) return EMPTY;
+  if (!withinDist) return KEEP;
+  const [x, y, z, radius] = withinDist;
+  return Math.hypot(record[0] - x, record[1] - y, record[2] - z) > radius
+    ? CROPPED
+    : KEEP;
+}
+
 export class Splats {
   constructor(workspace, maxSh) {
     this.workspace = workspace;
@@ -52,6 +63,7 @@ export class Splats {
     this.inputSh = 0;
     this.length = 0;
     this.invalid = 0;
+    this.cropped = 0;
     this.records = new PagedArray(workspace, Float32Array);
     this.sh = SH_DIMS.map(() => new PagedArray(workspace, Uint16Array));
     // The two children of the i-th merged splat are entries 2i and 2i + 1 of
@@ -127,9 +139,11 @@ export class Splats {
 
   // Skips empty splats and counts invalid ones in `invalid`: NaN or infinite
   // values, including a zero rotation, which the decoder normalizes to NaN.
-  // Workers refresh and check blocks of splats in place; the main thread
+  // Optionally keeps only centers within [x, y, z, radius], counting the
+  // otherwise usable splats outside this sphere in `cropped`.
+  // Workers refresh, check and crop blocks of splats; the main thread
   // checks those they leave, and moves kept splats after skipped ones.
-  retain(pool) {
+  retain(pool, withinDist) {
     const progress = new Progress("Filtering splats", this.length);
     const { results } = pool;
     const block = results.length;
@@ -143,6 +157,7 @@ export class Splats {
     ];
     let count = 0;
     this.invalid = 0;
+    this.cropped = 0;
     for (let base = 0; base < this.length; base += block) {
       const size = Math.min(block, this.length - base);
       for (const [column, stride] of columns)
@@ -151,24 +166,26 @@ export class Splats {
           (base + size) * stride,
           column === this.records,
         );
-      pool.check(this, base, size);
+      pool.check(this, base, size, withinDist);
       for (let i = 0; i < size; i++) {
         const index = base + i;
         let state = results[i];
-        if (state === LATER) {
+        const later = state === LATER;
+        if (later) {
           this.read(index, record);
           refresh(record);
           state = !this.valid(index, record, rows)
             ? INVALID
-            : record[3] > 0 && record[14] > 0
-              ? KEEP
-              : EMPTY;
-          if (state === KEEP) this.records.write(index * 16, record);
+            : filterRecord(record, withinDist);
         }
         if (state === INVALID) this.invalid++;
+        if (state === CROPPED) this.cropped++;
         if (state !== KEEP) continue;
+        if (count !== index || later) {
+          if (!later) this.read(index, record);
+          this.records.write(count * 16, record);
+        }
         if (count !== index) {
-          this.records.write(count * 16, this.read(index, record));
           for (let band = 0; band < this.maxSh; band++) {
             const dims = SH_DIMS[band];
             this.sh[band].read(index * dims, rows[band]);