gaussian-splat-lite 1.3.0 → 1.3.2

package/dist/types/loaders/stream/sog-stream/sogLod.d.ts

@@ -9,7 +9,7 @@ export type SogLodRange = {
 };
 export type SogLodLeaf = {
   id: number;
-  /** Coarse to fine, with strictly increasing counts and decreasing levels. */
+  /** Coarse to fine, with strictly decreasing levels. */
   lods: SogLodRange[];
 };
 export type SogLodNode = {
@@ -25,8 +25,7 @@ export type SogLodFile = {
 export type SogLodManifest = {
   tree: SogLodNode;
   leaves: SogLodLeaf[];
-  /** Flattened in leaf/LOD order; each leaf's first entry is unused. */
-  upgradeRatios: number[];
+  lodLevels: number;
   files: SogLodFile[];
   environment?: string;
 };
@@ -38,14 +37,13 @@ export type SogLodIndex = {
   leafOffsets: Uint32Array;
   /** Per level: level, file, offset, count. */
   lods: Float64Array;
-  /** Best reachable distance-error reduction per added splat, in LOD order. */
-  upgradeRatios: Float32Array;
+  lodLevels: number;
   urls: string[];
   counts: Float64Array;
   environment?: string;
 };
 /** Scheduler metadata; the complete spatial tree stays in the LOD worker. */
-export type SogLodMetadata = Omit<SogLodIndex, "nodes" | "upgradeRatios"> & {
+export type SogLodMetadata = Omit<SogLodIndex, "nodes" | "lodLevels"> & {
   /** Root min XYZ and max XYZ. */
   bounds: Float64Array;
 };
@@ -63,7 +61,15 @@ export declare function parseSogLodManifest(
 ): SogLodManifest;
 export type SogVisibleLeaf = {
   leaf: SogLodLeaf;
-  weight: number;
+  /** World-space distance to the region, compensated for the camera's field of view. */
+  distance: number;
+};
+export type SogBudgetMode = "target" | "limit";
+export type SogLodOptions = {
+  budget: number;
+  splatBudgetMode: SogBudgetMode;
+  lodBaseDistance: number;
+  lodMultiplier: number;
 };
 /** Reuse cached refinements up to the target, then split gaps of four or more. */
 export declare function resolveSogLod(
@@ -77,9 +83,9 @@ export declare function resolveSogLod(
   /** Wait until range is attached before requesting the next LOD. */
   refinement?: boolean;
 };
-/** Distance bands within a splat budget, using a small heap. */
+/** Select distance bands, fitting their common base distance to the splat budget. */
 export declare function selectSogLods(
   visible: SogVisibleLeaf[],
-  budget: number,
-  manifest: Pick<SogLodIndex, "leafOffsets" | "upgradeRatios">,
+  lodLevels: number,
+  options: SogLodOptions,
 ): Map<number, SogLodRange>;

package/dist/types/loaders/stream/sog-stream/sogVisibility.d.cts

@@ -1,5 +1,5 @@
 import type * as THREE from "three";
-import type { SogLodIndex } from "./sogLod.cjs";
+import type { SogLodIndex, SogLodOptions } from "./sogLod.cjs";
 export type SogCamera = {
   modelView: number[];
   projection: number[];
@@ -11,6 +11,7 @@ export type SogView = {
   cameras: SogCamera[];
   shown: boolean;
 };
+export type SogLodRequest = SogLodOptions & { view: SogView };
 /**
  * Capture the cameras that see the group without traversing the manifest or
  * reducing matrix precision. WebXR selects detail from each eye's current pose and frustum.
@@ -31,13 +32,10 @@ export declare class SogVisibility {
   private readonly closest;
   private readonly inverseModelView;
   constructor(
-    manifest: Pick<
-      SogLodIndex,
-      "nodes" | "leafOffsets" | "lods" | "upgradeRatios"
-    >,
+    manifest: Pick<SogLodIndex, "nodes" | "leafOffsets" | "lods" | "lodLevels">,
   );
   private prepareCameras;
   private collect;
   /** Transfer only [leaf ID, LOD ordinal] pairs in loading priority order. */
-  select(view: SogView, budget: number): Uint32Array;
+  select(request: SogLodRequest): Uint32Array;
 }

package/dist/types/loaders/stream/sog-stream/sogVisibility.d.ts

@@ -1,5 +1,5 @@
 import type * as THREE from "three";
-import type { SogLodIndex } from "./sogLod.js";
+import type { SogLodIndex, SogLodOptions } from "./sogLod.js";
 export type SogCamera = {
   modelView: number[];
   projection: number[];
@@ -11,6 +11,7 @@ export type SogView = {
   cameras: SogCamera[];
   shown: boolean;
 };
+export type SogLodRequest = SogLodOptions & { view: SogView };
 /**
  * Capture the cameras that see the group without traversing the manifest or
  * reducing matrix precision. WebXR selects detail from each eye's current pose and frustum.
@@ -31,13 +32,10 @@ export declare class SogVisibility {
   private readonly closest;
   private readonly inverseModelView;
   constructor(
-    manifest: Pick<
-      SogLodIndex,
-      "nodes" | "leafOffsets" | "lods" | "upgradeRatios"
-    >,
+    manifest: Pick<SogLodIndex, "nodes" | "leafOffsets" | "lods" | "lodLevels">,
   );
   private prepareCameras;
   private collect;
   /** Transfer only [leaf ID, LOD ordinal] pairs in loading priority order. */
-  select(view: SogView, budget: number): Uint32Array;
+  select(request: SogLodRequest): Uint32Array;
 }

package/dist/types/loaders/stream/sog-stream/workerHandlers.d.cts

@@ -1,6 +1,6 @@
 import type { SplatResult } from "../../../data/defines.cjs";
 import type { SplatLoadArgs, SplatLoadStatus } from "../../loadTypes.cjs";
-import type { SogView } from "./sogVisibility.cjs";
+import type { SogLodRequest } from "./sogVisibility.cjs";
 export type SogChunkInfo = {
   numSplats: number;
   numSh: number;
@@ -63,11 +63,5 @@ export declare function createSogStreamHandlers(
     counts: Float64Array;
     environment?: string;
   };
-  selectSogLod: ({
-    view,
-    budget,
-  }: {
-    view: SogView;
-    budget: number;
-  }) => Uint32Array<ArrayBufferLike>;
+  selectSogLod: (request: SogLodRequest) => Uint32Array<ArrayBufferLike>;
 };

package/dist/types/loaders/stream/sog-stream/workerHandlers.d.ts

@@ -1,6 +1,6 @@
 import type { SplatResult } from "../../../data/defines.js";
 import type { SplatLoadArgs, SplatLoadStatus } from "../../loadTypes.js";
-import type { SogView } from "./sogVisibility.js";
+import type { SogLodRequest } from "./sogVisibility.js";
 export type SogChunkInfo = {
   numSplats: number;
   numSh: number;
@@ -63,11 +63,5 @@ export declare function createSogStreamHandlers(
     counts: Float64Array;
     environment?: string;
   };
-  selectSogLod: ({
-    view,
-    budget,
-  }: {
-    view: SogView;
-    budget: number;
-  }) => Uint32Array<ArrayBufferLike>;
+  selectSogLod: (request: SogLodRequest) => Uint32Array<ArrayBufferLike>;
 };

package/dist/types/loaders/stream/streamOptions.d.cts

@@ -10,7 +10,7 @@ export type StreamSchedulerOptions = {
   /** Milliseconds to retain unused data after fade-out; defaults to 2000. */
   cooldownMs?: number;
   fadeDurationMs?: number;
-  /** Active downloads/decodes. Ready copies use a separate bounded byte queue. */
+  /** Maximum simultaneous downloads/decodes; defaults to 4. */
   maxConcurrentLoads?: number;
   onChange?: () => void;
   onError?: (error: unknown, url: string) => void;
@@ -21,11 +21,17 @@ export type StreamStats = {
   residentMeshes: number;
   /** Decoded chunks, including cached chunks that are not currently drawn. */
   residentChunks: number;
-  /** Retained CPU and estimated GPU bytes, excluding pending copies and WASM. */
+  /** Retained CPU data, excluding pending copies and WASM memory. */
+  residentCpuBytes: number;
+  /** Estimated GPU storage for resident streaming data; excludes renderer buffers. */
+  residentGpuBytes: number;
+  /** Sum of residentCpuBytes and residentGpuBytes. */
   residentBytes: number;
-  /** Reserved or ready copies awaiting publication into source storage. */
+  /** Estimated in-flight or ready copies awaiting publication into source storage. */
   pendingBytes: number;
   loadingChunks: number;
+  /** Ready share of the current view's requested detail, from 0 to 1. Changes with the view. */
+  loadProgress: number;
   downloadedBytes: number;
   peakWasmMemoryBytes: number;
 };
@@ -36,11 +42,6 @@ export declare function streamSettings(options: StreamSchedulerOptions): {
   fadeDurationMs: number;
   maxConcurrentLoads: number;
 };
-/** Bound queued decode/extraction copies independently of per-update publication. */
-export declare function streamPendingLimit(
-  concurrency: number,
-  unitBytes?: number,
-): number;
 /** Format errors are permanent; transient failures retry with capped backoff. */
 export declare function streamRetryAt(error: unknown, failures: number): number;
 export declare function notifyStreamChange(

package/dist/types/loaders/stream/streamOptions.d.ts

@@ -10,7 +10,7 @@ export type StreamSchedulerOptions = {
   /** Milliseconds to retain unused data after fade-out; defaults to 2000. */
   cooldownMs?: number;
   fadeDurationMs?: number;
-  /** Active downloads/decodes. Ready copies use a separate bounded byte queue. */
+  /** Maximum simultaneous downloads/decodes; defaults to 4. */
   maxConcurrentLoads?: number;
   onChange?: () => void;
   onError?: (error: unknown, url: string) => void;
@@ -21,11 +21,17 @@ export type StreamStats = {
   residentMeshes: number;
   /** Decoded chunks, including cached chunks that are not currently drawn. */
   residentChunks: number;
-  /** Retained CPU and estimated GPU bytes, excluding pending copies and WASM. */
+  /** Retained CPU data, excluding pending copies and WASM memory. */
+  residentCpuBytes: number;
+  /** Estimated GPU storage for resident streaming data; excludes renderer buffers. */
+  residentGpuBytes: number;
+  /** Sum of residentCpuBytes and residentGpuBytes. */
   residentBytes: number;
-  /** Reserved or ready copies awaiting publication into source storage. */
+  /** Estimated in-flight or ready copies awaiting publication into source storage. */
   pendingBytes: number;
   loadingChunks: number;
+  /** Ready share of the current view's requested detail, from 0 to 1. Changes with the view. */
+  loadProgress: number;
   downloadedBytes: number;
   peakWasmMemoryBytes: number;
 };
@@ -36,11 +42,6 @@ export declare function streamSettings(options: StreamSchedulerOptions): {
   fadeDurationMs: number;
   maxConcurrentLoads: number;
 };
-/** Bound queued decode/extraction copies independently of per-update publication. */
-export declare function streamPendingLimit(
-  concurrency: number,
-  unitBytes?: number,
-): number;
 /** Format errors are permanent; transient failures retry with capped backoff. */
 export declare function streamRetryAt(error: unknown, failures: number): number;
 export declare function notifyStreamChange(

package/docs/PostDecode.md

@@ -43,9 +43,9 @@ Read these from `splat`:
 | `splat.opacity` | `float` | Opacity as stored in the model, which can be above 1 |
 | `splat.alpha` | `float` | Opacity from 0 (transparent) to 1 (opaque) |
 | `splat.color` | `vec3` | RGB color |
-| `splat.sh.coefficient(index)` | `vec3` | One of the 15 view-dependent color coefficients |
+| `splat.sh.coefficient(index)` | `vec3` | One of the 24 view-dependent color coefficients (indices 0–23, SH1–SH4) |
 
-`splat.sh.map((coefficient, { degree }) => ...)` builds a calculation for all 15 coefficients at once. Only the ones the model has are updated.
+`splat.sh.map((coefficient, { degree }) => ...)` builds a calculation for all 24 coefficients at once. Only the ones the model has are updated.
 
 ## Returning changes
 

package/docs/RadStreamScheduler.md

@@ -10,6 +10,9 @@ import { RadStreamScheduler } from "gaussian-splat-lite";
 const streaming = new RadStreamScheduler({
   url: "/models/scene.rad",
   splatBudget: 3_000_000,
+  splatBudgetTolerance: 0.1, // Allow up to 10% extra Splats; 0 forbids overshoot.
+  maxResidentCpuBytes: 2 * 1024 * 1024 * 1024, // 2 GiB
+  maxResidentGpuBytes: 1024 * 1024 * 1024, // 1 GiB
 });
 scene.add(streaming.group);
 streaming.setCamera(camera);
@@ -72,16 +75,21 @@ renderer.setAnimationLoop(() => {
 | `url` / `file` / `fileBytes` | Exactly one required | URL, `Blob`/`File`, or complete `Uint8Array`/`ArrayBuffer` |
 | `resolveFile` | Relative URLs | Supply the `.radc` pages of a split scene yourself: `(filename, signal) => URL \| Blob \| Uint8Array \| ArrayBuffer`, directly or as a promise |
 | `group` | New `THREE.Group` | Group that holds the scene |
-| `splatBudget` | `3_000_000` | Maximum number of Splats shown at once. Higher values show more detail and use more memory |
+| `splatBudget` | `3_000_000` | Target number of Splats. Higher values show more detail and use more memory |
+| `splatBudgetTolerance` | `0.1` | Allowed fractional overshoot of `splatBudget`. `0.1` allows up to 10% extra Splats; `0` keeps each new selection within `splatBudget`. Must be finite and nonnegative |
+| `maxResidentCpuBytes` | 2 GiB | CPU memory budget for cached data, in bytes. Set a positive integer when creating the scheduler |
+| `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 detail that is no longer shown stays in memory, ready for reuse; `0` releases it at once |
-| `maxConcurrentLoads` | `4` | Maximum number of loads in progress at the same time |
+| `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. |
 | `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 |
 | `onError` | Logs to the console | Called when loading fails: `(error, url)` |
 
-Detail that is already on screen stays there while its replacement loads. During a fade, old and new detail overlap, so the scene can briefly exceed `splatBudget`; use `fadeDurationMs: 0` to prevent this. The budget limits what is shown, not total memory: detail kept for reuse takes memory too.
+Detail already on screen stays visible while its replacement loads, if both memory budgets allow. At the limit, the scene may temporarily show less detail. During a fade, old and new detail overlap, so the visible count can briefly exceed the selection limit. Use both `splatBudgetTolerance: 0` and `fadeDurationMs: 0` to keep new selections and their transitions within `splatBudget`.
+
+Unused detail is released after `cooldownMs`, including while hidden, and loads again when needed.
 
 ## Properties and methods
 
@@ -89,6 +97,7 @@ Detail that is already on screen stays there while its replacement loads. During
 | --- | --- |
 | `group` | Group that holds the scene |
 | `splatBudget` | Change it at any time to adjust detail, even while the camera is still. Must be a positive integer |
+| `splatBudgetTolerance` | Change the allowed overshoot at any time without reloading. `0` forbids overshoot |
 | `initialized` | Resolves when the scene is set up; rejects for invalid or unsupported files |
 | `firstRenderable` | Resolves when the first data is on screen, or the scene is empty; rejects if the first data cannot be loaded. Keep calling `update()` while you wait |
 | `setCamera(camera)` / `deleteCamera(camera)` | Add or remove a camera that chooses detail. `hasCamera(camera)` and `cameras` report the registered ones |
@@ -97,7 +106,7 @@ Detail that is already on screen stays there while its replacement loads. During
 | `update()` | Advance detail selection, loading, and fades. Call it before every render; it throws if no camera is registered |
 | `getBoundingBox()` | Approximate box around the scene, in the group's coordinates; empty until the first data loads |
 | `getGlobalIndex(mesh, renderedIndex)` | Convert a picking hit into a node index that stays the same for the whole RAD file |
-| `stats` | Numbers for monitoring, such as `visibleSplats`, `loadingChunks`, `downloadedBytes`, and `residentBytes`. Memory figures are estimates, not total browser memory |
+| `stats` | Visible Splats, loading progress, and estimated CPU/GPU cache sizes (`residentCpuBytes` / `residentGpuBytes`) |
 | `dispose()` | Stop loading and release the scene. Pending `initialized` and `firstRenderable` promises reject with `AbortError` |
 
 ### On-demand rendering

package/docs/SogStreamScheduler.md

@@ -48,7 +48,10 @@ In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown f
 | --- | --- | --- |
 | `url` | Required | URL of the scene's `lod-meta.json` |
 | `group` | New `THREE.Group` | Group that holds the scene |
-| `splatBudget` | `3_000_000` | Target number of Splats shown at once, including the environment. Higher values show more detail and use more memory |
+| `splatBudget` | `3_000_000` | Splat budget, including the environment. Higher values allow more detail and use more memory |
+| `splatBudgetMode` | `"target"` | `"target"` adjusts the distance bands to fill the budget. `"limit"` uses the configured distance bands and only reduces detail when they exceed the budget |
+| `lodBaseDistance` | `100` | Base LOD distance in world units for `"limit"` mode, compensated for the camera's field of view. Higher values retain finer detail farther away. Must be finite and positive |
+| `lodMultiplier` | `2` | Distance multiplier between successive LOD levels in both modes. Must be finite and at least `1` |
 | `fadeDurationMs` | `200` | Duration of the fade when the scene first appears and when detail changes; `0` switches instantly |
 | `cooldownMs` | `2000` | How long detail that is no longer shown stays in memory, ready for reuse; `0` releases it at once |
 | `maxConcurrentLoads` | `4` | Maximum number of loads in progress at the same time |
@@ -58,22 +61,21 @@ In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown f
 | `onError` | Logs to the console | Called when loading fails: `(error, url)` |
 | `loadChunk` | Built-in loader | Load the scene's files yourself: `(url, signal) => Promise<Splats>` |
 
-The budget is a target, not a hard limit: the available detail levels, fades, and the environment can take the scene above it. It limits what is shown, not total memory: detail kept for reuse takes memory too.
-
-Some parts of a scene exist only at finer detail levels. They can be empty from far away and fade in as the camera approaches.
-
 ## Properties and methods
 
 | API | Description |
 | --- | --- |
 | `group` | Group that holds the scene |
 | `splatBudget` | Change it at any time to adjust detail. Must be a positive integer; includes the environment |
+| `splatBudgetMode` | Switch between `"target"` and `"limit"` without reloading |
+| `lodBaseDistance` | Change the base LOD distance in `"limit"` mode without reloading |
+| `lodMultiplier` | Change the distance spacing between LOD levels in both modes without reloading |
 | `initialized` | Resolves when the index is loaded; rejects for invalid input |
 | `firstRenderable` | Resolves when the first data is on screen, or the scene is empty; rejects if the first data cannot be loaded. Keep calling `update()` while you wait |
 | `setCamera(camera)` / `deleteCamera(camera)` | Add or remove a camera that chooses detail. `hasCamera(camera)` and `cameras` report the registered ones |
 | `update()` | Advance detail selection, loading, and fades. Call it before every render; it throws if no camera is registered |
 | `getBoundingBox()` | Box around the scene, in the group's coordinates; available once `initialized` resolves |
-| `stats` | Numbers for monitoring, such as `visibleSplats`, `visibleRegions`, `loadingChunks`, `downloadedBytes`, and `residentBytes`. Memory figures are estimates, not total browser memory |
+| `stats` | Visible Splats, loading progress, and estimated CPU/GPU cache sizes (`residentCpuBytes` / `residentGpuBytes`) |
 | `dispose()` | Stop loading and release the scene. Pending `initialized` and `firstRenderable` promises reject with `AbortError` |
 
 ### On-demand rendering

package/docs/SplatFileType.md

@@ -11,6 +11,8 @@ The model formats you can load:
 | `SplatFileType.SOG` | `"sog"` | `.sog`, or a SOG `meta.json` with its images |
 | `SplatFileType.RAD` | `"rad"` | `.rad` |
 
+PLY and SPZ support view-dependent color up to SH4 on WebGL, WebGPU, and the WebGL2 fallback. RAD and SOG support up to SH3. Models render all their available coefficients by default; set [`mesh.maxSh`](SplatMesh.md#properties) to limit the degree.
+
 The format is normally detected from the URL or `fileName`, so you rarely need this. Set it when the name does not show the format:
 
 ```js

package/docs/SplatMesh.md

@@ -59,7 +59,7 @@ Choose at most one of `url`, `file`, `fileBytes`, or `splats`; combining them th
 | `numSplats` | `number` | Current Splat count |
 | `recolor` | `THREE.Color(1, 1, 1)` | Color multiplier for the whole model |
 | `opacity` | `1` | Opacity multiplier for the whole model |
-| `maxSh` | `3` | Limit view-dependent color detail; `0` uses the base color only |
+| `maxSh` | `4` | Limit view-dependent color detail to SH0–SH4; `0` uses the base color only |
 | `edits` | `SplatEdit[] \| null` | Explicit list of [edits](SplatEdit.md) for this mesh |
 | `splats` | `Splats \| undefined` | The model's [Splats](Splats.md) data |
 | `needsUpdate` | `boolean` setter | Set to `true` to force a refresh |

package/docs/Splats.md

@@ -49,7 +49,7 @@ Calling `initialize()` again or `dispose()` cancels a load still in progress; it
 ## Data rules
 
 - **Indices are not file order.** Splats are reordered while loading. Use `getSourceIndex(index)`, or a picking hit's `sourceIndex`, to get the ID from the original file. Passing existing `Splats` to a mesh keeps their order.
-- **Reads return copies.** `getSplat()` returns new `center`, `scales`, `quaternion`, `opacity`, `color`, and `sh` values on each call; changing them does not change the model. `sh` holds 0, 3, 8, or 15 RGB coefficients, depending on the model's degree.
+- **Reads return copies.** `getSplat()` returns new `center`, `scales`, `quaternion`, `opacity`, `color`, and `sh` values on each call; changing them does not change the model. `sh` holds 0, 3, 8, 15, or 24 RGB coefficients, depending on the model's degree (SH0–SH4).
 - **`forEachSplat()` reuses its objects.** The same objects are passed for every Splat, so clone anything you want to keep after the callback returns.
 - **Streamed data is read-only.** Data from [RadStreamScheduler](RadStreamScheduler.md) or [SogStreamScheduler](SogStreamScheduler.md) cannot be reinitialized.
 - **Bounds live on the mesh.** Use [`mesh.getBoundingBox()`](SplatMesh.md#bounding-box).

package/package.json

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

package/dist/types/loaders/stream/StreamByteBudget.d.cts

@@ -1,7 +0,0 @@
-/** Bound pending copies while allowing one oversized item to make progress. */
-export declare class StreamByteBudget {
-  readonly limit: number;
-  used: number;
-  constructor(limit: number, used?: number);
-  reserve(bytes: number): boolean;
-}

package/dist/types/loaders/stream/StreamByteBudget.d.ts

@@ -1,7 +0,0 @@
-/** Bound pending copies while allowing one oversized item to make progress. */
-export declare class StreamByteBudget {
-  readonly limit: number;
-  used: number;
-  constructor(limit: number, used?: number);
-  reserve(bytes: number): boolean;
-}