gaussian-splat-lite 1.4.2 → 1.4.3

package/docs/RadStreamScheduler.md

@@ -107,7 +107,6 @@ Unused detail is released after `cooldownMs`, including while hidden, and loads
 | `setResolutionFromRenderer(camera, renderer)` | Set a registered camera's size from `renderer.getSize()` |
 | `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` | 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` |
 
@@ -117,13 +116,14 @@ Request a redraw from `onChange`, and keep calling `update()` on every animation
 
 ### Picking
 
-Hits from a streamed scene refer to the detail that is currently shown. Use `getGlobalIndex()`, or the hit's [`sourceIndex`](SplatMesh.md#raycasting), for an ID that does not change:
+Hits from a streamed scene refer to the detail that is currently shown. Read the hit Splat before the streaming selection updates, since its index can change:
 
 ```js
 const hits = raycaster.intersectObject(streaming.group, true);
 if (hits.length && hits[0].index !== undefined) {
-  const nodeIndex = streaming.getGlobalIndex(hits[0].object, hits[0].index);
-  console.log(nodeIndex, hits[0].point);
+  const hit = hits[0];
+  const splat = hit.object.splats.getSplat(hit.index);
+  console.log(splat, hit.point);
 }
 ```
 

package/docs/SogStreamScheduler.md

@@ -2,7 +2,7 @@
 
 [Back to documentation](../README.md#documentation)
 
-Shows large SOG `lod-meta.json` scenes by loading only the detail the camera needs, and updating it as the camera moves. It supports version 1 and older unversioned indexes, on WebGPU and WebGL2. For an ordinary `.sog` file or `meta.json`, use [SplatMesh](SplatMesh.md).
+Shows large SOG `lod-meta.json` scenes with camera-driven detail, keeping coarser surroundings ready as the camera turns. It supports version 1 and older unversioned indexes, on WebGPU and WebGL2. For an ordinary `.sog` file or `meta.json`, use [SplatMesh](SplatMesh.md).
 
 ```js
 import { SogStreamScheduler } from "gaussian-splat-lite";
@@ -34,11 +34,15 @@ The three steps that matter:
 2. Register the camera.
 3. Call `streaming.update()` before every render.
 
-Streamed models support [SDF edits](SplatEdit.md) and [picking](SplatMesh.md#raycasting). Their data is read-only. For a Splat's original ID, use the picking hit's [`sourceIndex`](SplatMesh.md#raycasting).
+Streamed models support [SDF edits](SplatEdit.md) and [picking](SplatMesh.md#raycasting). Their data is read-only. Read a hit with `hit.object.splats.getSplat(hit.index)` before the streaming selection updates.
 
 ## Cameras
 
-Detail depends on distance from the camera, so cameras need no resolution. Register several cameras to load detail for all of them; each part of the scene follows the nearest camera that sees it.
+Detail depends on distance and camera direction, so cameras need no resolution. Regions outside the view remain part of the same budget, with less detail behind the camera. This keeps surrounding content ready for turns, at the cost of some detail in the current view. Register several cameras to load detail for all of them; each region follows the camera requesting the finest detail.
+
+Oversized region bounds are reduced toward the scene's median region size when measuring LOD distance. This prevents large background regions from receiving excessive detail just because an edge is close to the camera. Geometry, rendering bounds, and picking are unaffected by this distance correction.
+
+### WebXR
 
 In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown for [RadStreamScheduler](RadStreamScheduler.md#webxr). Detail is chosen for each eye.
 
@@ -52,6 +56,8 @@ In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown f
 | `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` |
+| `lodBehindPenalty` | `4` | Effective distance multiplier directly behind a camera, increasing smoothly from `1` at its sides. With the default LOD multiplier, `4` shifts rear detail by two distance bands. `1` disables directional bias. Must be finite and at least `1` |
+| `lodDistanceShrink` | `0.75` | Fraction of a region's excess half-size above the scene median removed when measuring distance, independently on each axis. Higher values reduce detail in oversized regions; `0` disables the correction. Must be finite and between `0` and `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 |
@@ -70,6 +76,8 @@ In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown f
 | `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 |
+| `lodBehindPenalty` | Change how strongly detail behind the camera is reduced, in both modes, without reloading |
+| `lodDistanceShrink` | Change the distance correction for oversized regions, 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 |
@@ -88,4 +96,6 @@ Temporary download failures are retried automatically, waiting longer after each
 
 Invalid data, out-of-memory errors, and other HTTP errors are reported to `onError` and are not retried. Parts of the scene that are already on screen stay visible when loading more detail fails.
 
-If the scheduler can no longer choose detail after an internal failure, it calls `onError` and disposes itself. Create a new scheduler to try again.
+`firstRenderable` waits for the initial detail selection before deciding that all needed loads have failed permanently. An environment failure alone does not reject it while scene selection is pending.
+
+If detail selection fails, the scheduler calls `onError`, stops loading, and retains the last displayed coverage while its fades finish. Create a new scheduler to try again, and call `dispose()` before discarding the old one.

package/docs/SplatMesh.md

@@ -127,9 +127,9 @@ if (intersections.length > 0) {
 ```
 
 - The model needs `raycastable: true`, the default. Picking may return nothing while the model is still being set up.
-- Each hit has an `index`, for reading the Splat from the current data, and a `sourceIndex`, its ID in the original file (`SplatIntersection` in TypeScript).
+- Each hit contains `distance`, `point`, `object`, and `index` (`SplatIntersection` in TypeScript). Read the hit Splat with `hit.object.splats.getSplat(hit.index)`.
 - Values of `minRaycastOpacity` below `0.01` have limited effect: areas that transparent may not be pickable.
-- Streamed models can be picked. Hits ignore their display fades, and an `index` can change as the shown detail changes. For RAD, `sourceIndex` is the node index within the whole file; for streamed SOG, it is the index within the chunk file the hit Splat was loaded from.
+- Streamed models can be picked. Hits ignore their display fades. An `index` belongs to the hit object's current data and can change as the shown detail changes; read the Splat before the streaming selection updates.
 
 ## Scene integration
 

package/docs/Splats.md

@@ -10,7 +10,6 @@ Wait for loading to finish before reading:
 await splat.initialized;
 const data = splat.splats;
 const item = data.getSplat(0);
-const sourceIndex = data.getSourceIndex(0);
 ```
 
 ## Options
@@ -39,7 +38,6 @@ Choose at most one of `url`, `file`, or `fileBytes`; combining them throws.
 | `getNumSplats()` / `getNumSh()` | Splat count, and the level of view-dependent color (spherical harmonics degree) the model has |
 | `getByteLength()` | Memory used by the data, in bytes |
 | `getSplat(index, includeSh?)` | Read one Splat; pass `false` to skip its view-dependent color |
-| `getSourceIndex(index)` | The Splat's ID in the original file |
 | `forEachCenter(callback)` | Visit only the center of every Splat, for example to build a spatial index |
 | `forEachSplat(callback)` | Visit every Splat |
 | `dispose()` | Cancel loading and release the data |
@@ -48,7 +46,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.
+- **Indices address the current data.** Splats are reordered while loading, so indices may differ from file order. Passing existing `Splats` to a mesh keeps their order. Streamed indices can change when the visible detail changes.
 - **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.

package/package.json

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