gaussian-splat-lite 1.2.0 → 1.2.1

package/docs/Architecture.md

@@ -2,7 +2,9 @@
 
 [Back to documentation](../README.md#documentation)
 
-[`src/index.ts`](../src/index.ts) defines the public exports. Applications use `SplatMesh` for models and one `GaussianSplatRenderer` for the scene. This guide describes the internal module boundaries and resource lifetimes; see the [README](../README.md#quick-start) for setup.
+This guide is for contributors. It describes internal module boundaries, backend differences, and resource lifetimes. To use the library, start from the [README](../README.md#quick-start) and the API pages it lists; those pages describe behavior, and this one explains how it is implemented.
+
+[`src/index.ts`](../src/index.ts) defines the public exports. Applications use `SplatMesh` for models and one `GaussianSplatRenderer` for the scene.
 
 ## Source layout
 
@@ -21,11 +23,13 @@
 | `rust/gaussian-splat-rs/src/` | WASM bridges, typed-array output, LOD selection, sorting, and raycasting |
 | `src/runtime/` | Worker RPC, pooling, transferables, and WASM initialization |
 | `src/utils/` | Numeric conversion, spatial transforms, and Three.js helpers |
-| `src/rendering/` | Shared updates and sorting handoffs |
+| `src/rendering/` | Shared updates, sorting handoffs, backend selection, and stochastic blue noise |
 | `src/rendering/tsl/` | Shared TSL generation, projection, drawing, and view uniforms |
 | `src/rendering/webgpu/` | Compute projection, projected caches, GPU sorting, and indirect drawing |
 | `src/rendering/webgl/` | GLSL materials, texture generation, and CPU ordering uploads |
 | `src/rendering/webgl-fallback/` | WebGPURenderer WebGL2 raster generation and ordering uploads |
+| `src/capture/` | Optional offscreen targets, readback, cube captures, and PMREM filtering |
+| `src/addons/` | Temporal anti-aliasing: `TAAPass` for WebGLRenderer, `TAANode` for WebGPURenderer, and their shared state |
 
 ## Rendering boundaries
 
@@ -34,6 +38,7 @@ The renderer combines visible models using Three.js transforms, visibility, and
 | Owner | Responsibility |
 | --- | --- |
 | `GaussianSplatRenderer` | Scene updates, accumulator handoff, and sorting |
+| `SplatCapture` | Independent capture Splat state, offscreen targets, readback, and PMREM |
 | `SplatAccumulator` | Scene mappings, versions, camera-relative origin, and WebGL texture generation |
 | WebGPU backend | Compute projection, caches, GPU sorting, and indirect drawing |
 | WebGL backend | GLSL materials, ordering textures, and texture generation |
@@ -44,11 +49,49 @@ For sorted rendering, native WebGPU keeps ordering and visible counts on the GPU
 
 In `webgpu/`, `ProjectedSplats.ts` coordinates projection and sorting, `ProjectionCache.ts` owns projected storage, and `RadixSort.ts` owns sort passes. WebXR uses the eyes' mean pose for generation and sorting, with separate projections for each eye. Both WebGL backends share `webgl/OrderingTexture.ts` for allocation and disposal, while keeping their own upload and binding paths.
 
+`backend.ts` selects the backend from the renderer type and its public `coordinateSystem`, which distinguishes native WebGPU from WebGL fallback. It chooses the blend space for each output: the working color space by default, `renderer.outputColorSpace` when WebGLRenderer draws to the canvas, and the target texture's color space when it draws to an XR-style target.
+
+Projected Splat support is capped at the viewport's short side, in projection space scaled by `focalAdjustment`, in both the TSL projection program and the GLSL vertex shader. The quad and its UV extent shrink by the same ratio, preserving the Gaussian profile.
+
+Errors from automatic updates are caught and logged once per message; a draw whose preparation fails is skipped. Explicit `update()` calls rethrow to the caller. `frameCallbacks` is an internal flag for a second renderer on the same scene, so each `SplatMesh.onFrame` runs once per frame.
+
 Resource rules:
 
 - Wait for outstanding GPU compilation before disposing the sorter; preserve compute nodes when resizing resources or changing source meshes.
 - Keep color conversion and XR output handling with the backend that owns them.
 
+### Stochastic rendering
+
+Sorted and stochastic draws compile separate shaders without mode branches. A mode change takes effect at the next update boundary, after the current draw; both WebGL backends also wait for the matching accumulator and sort, and `stochasticActive` reports the mode being drawn. Stochastic draws use the opaque list with depth testing and writing.
+
+Coverage uses a tileable 32-frame spatiotemporal blue-noise atlas (`blueNoise.ts`, generated by `scripts/generate-blue-noise.js`) on all backends. Each Splat keeps its own spatial offset and temporal phase, so consecutive samples follow the atlas's time axis instead of choosing unrelated offsets. The temporal sequence is optimized for exponential history accumulation and wraps after 32 samples. `stochasticSample` advances once per scene render, and every view in that render shares it.
+
+Seeds exist only for stochastic draws: WebGL accumulators omit the seed layer in sorted rendering, and native WebGPU allocates its seed buffer on demand. Front-to-back stochastic ordering uses 16-bit keys. With unsorted stochastic rendering, `shrinkResources()` releases the sort worker and ordering.
+
+## Capture boundaries
+
+[SplatCapture](SplatCapture.md) is optional; the core renderer allocates no capture resources.
+
+- **Independent Splat state.** The helper owns an internal `GaussianSplatRenderer` with `autoUpdate` and stochastic rendering off, sharing the display renderer's timer, loaded Splat data, and model-owned SDF edit textures. Its accumulators, sorting, and projection resources are separate, so display ordering and camera state are untouched. Global and model-local edits apply to captures and follow their latest values. `frameCallbacks` is off, leaving `onFrame` to the display renderer.
+- **Stencil captures.** 2D and cube targets follow the Three.js renderer's stencil setting, with no separate capture option; a 2D target without a depth buffer gets no stencil, since Three.js attaches stencil only with depth. The intermediate target uses a depth-stencil attachment when stencil is enabled. With stencil, native depth is 32-bit float only for a reversed depth buffer or a float output depth texture, and only when the device has `depth32float-stencil8`; otherwise it is 24-bit. The scene's stencil masking applies before copying its color and depth to the output.
+- **Options.** Quality, sorting, and material options are copied from the supplied renderer at the start of each capture. The active Splat material's stencil comparison and write settings are copied as well. Cube captures force radial sorting. The internal renderer takes the capture camera's layer mask.
+- **Two phases.** Preparation awaits `update()` on a filtered scene view (`sceneView.ts`), which excludes hidden models from traversal without changing visibility and collects edits with the original scene's visibility. If the display updates shared models during a pending sort, preparation runs again; appearance-only changes reuse the ordering. The draw is synchronous: other Splat renderers' layer masks are cleared, `hideObjects` are hidden, and the internal renderer joins the scene. `withCaptureState()` saves and restores the render target, cube face, mip level, XR setting, automatic clearing, and MRT. Nothing stays changed across an `await`, and everything is restored when drawing throws.
+- **Ordering.** Captures on one helper are queued and run in call order. The camera or `worldCenter` is copied when the call is made. `renderReadTarget()` and `renderEnvMap()` read or filter inside the same queued task, before a later capture can redraw the target.
+- **Cube captures.** Splat data is prepared at `worldCenter` with a 90° camera, then six faces render with automatic updates off. Both WebGL backends share one radial CPU sort across the faces; native WebGPU projects, compacts, and sorts for each face while drawing. Every capture runs `update()`, whose version checks reuse valid data and ordering, so 1.1.8's `update` option is not offered. Mipmaps are generated after the sixth face. Filtered and unfiltered cubes use separate targets, reallocated when size, clipping planes, or the renderer's stencil setting change.
+- **Color.** `WebGLCapture` renders into an intermediate flagged as an XR-style target, 8-bit unless the output is float, so materials convert to the output color space before blending as on the canvas; a full-screen pass then converts to the target's storage space and copies depth. `WebGPUCapture` renders in the working color space, then applies the renderer's output transform and converts to storage space. On both, float outputs keep their type so values stay unclamped, and the intermediate takes the output's sample count, so multisampling applies to the scene and not to the final pass.
+- **Readback.** `pixels.ts` returns packed RGBA8 with the bottom row first on every backend, removing native WebGPU's 256-byte row padding and flipping its top-left origin. Supersampled targets are box-filtered on the CPU. Cube faces are normalized to the WebGL cube render target layout: native WebGPU stores +X and −X swapped and reads each face rotated 180°.
+- **Ownership.** `dispose()` releases the internal renderer, 2D and cube targets, readback buffers, and the PMREM generator. Each texture from `renderEnvMap()` belongs to the caller; disposing it also releases its PMREM render target.
+
+## Temporal anti-aliasing boundaries
+
+[TAAPass and TAANode](TAAPass.md) are derived from Three.js TRAA, without a velocity attachment: reprojection uses scene depth and camera motion only, so object motion is not tracked.
+
+- `taaShared.ts` owns the state both share: a 32-entry Halton(2, 3) jitter sequence, jittered and unjittered projections, previous-frame matrices, the history index, sizing, and reset. It supports custom projections, scaled rigs, reversed depth, and logarithmic depth.
+- Each implementation captures the scene itself into a half-float target with a depth texture and resolves between two history targets, with no history copies. The resolve applies depth rejection away from edges, neighborhood clipping, and luminance-aware blending.
+- The camera's projection is jittered only during capture. Native Splat projection reads the unjittered matrix through `getTAAProjection()`, so projection and sorting results are reused while only the jitter changes.
+- `TAAPass` flags its capture target as an XR-style target, so Three.js converts materials to `renderer.outputColorSpace` before blending, matching canvas blending. Tone mapping is disabled during capture. The final copy decodes the sRGB transfer into the composer's working-space buffer, the inverse of `OutputPass`, so the two round-trip at any alpha; as the last pass it presents the output-space image unchanged. An output color space change resets history.
+- `TAANode` is a TSL node updated once per render. It captures and accumulates in `ColorManagement.workingColorSpace`, leaving tone mapping and output conversion to `RenderPipeline`. A working color space change resets history.
+
 ## Decoder boundaries
 
 PLY, SPZ, SOG, and RAD decode in `gaussian-splat-lib` and publish through `SplatReceiver`. This core library has no JavaScript or WASM dependency. `gaussian-splat-rs` adapts browser inputs and writes the output into JS typed arrays through `SplatsData`.
@@ -69,6 +112,7 @@ The [postDecode](PostDecode.md) API builds expressions on the calling thread and
 | --- | --- |
 | `program.ts` / `builder.ts` | Public API, program identity, typed expressions, and patch validation |
 | `protocol.ts` | Opcodes, packed layouts, and shared types without builder or runtime dependencies |
+| `optimizer.ts` | Fusion of single-use arithmetic intermediates before compilation |
 | `compiler.ts` | Conditional flow, dependencies, packed instructions, and attribute snapshots |
 | `registers.ts` | Runtime register allocation and values carried between condition stages |
 | `operations.ts` / `runtime.ts` | Packed input reads, block execution, conditions, and output writes |
@@ -81,7 +125,8 @@ Loaders own transport and parsing; schedulers own selection, fades, publication,
 
 - `StreamWorkerPool.run()` queues worker leases, assigns task IDs, links cancellation, counts downloads, and balances loading-manager notifications. Each loader has its own pool; format-specific callbacks retain SOG caches or release RAD decoder slots.
 - `IndexedSplats` shares texture storage and selected-index reads between `RadPagedSplats` and `SogRegionSplats`. Slot assignment and scene attachment remain with the format-specific scheduler and batch classes.
-- `streamOptions.ts` owns shared defaults, validation, and statistics. `StreamByteBudget` bounds pending copies separately from active loads; ready data has no per-update byte allowance.
+- `StreamCameras.ts` owns the registered cameras and their resolutions, and expands a WebXR `ArrayCamera` into its eye views once they have a projection and viewport.
+- `streamOptions.ts` owns shared defaults, validation, retry classification, and statistics. `StreamByteBudget` bounds pending copies separately from active loads; ready data has no per-update byte allowance.
 
 `splatBudget` controls selected detail, not total memory. Resident-byte estimates exclude pending copies and WASM memory, which are reported separately; resident storage has no byte cap. Pending copies allow 8 MiB per concurrent load (32 MiB by default), enlarged for an indivisible RAD page; one oversized item can proceed alone. This bounds the waiting queue, not the bytes published or uploaded per frame.
 

package/docs/GaussianSplatRenderer.md

@@ -2,83 +2,81 @@
 
 [Back to documentation](../README.md#documentation)
 
-Renders all visible `SplatMesh` objects in a scene. One instance can display multiple models.
+Draws every visible `SplatMesh` in a scene. Add one to the scene; a single instance displays all your models.
 
-```ts
-new GaussianSplatRenderer(options: GaussianSplatRendererOptions)
+```js
+import { GaussianSplatRenderer } from "gaussian-splat-lite";
+
+const splatRenderer = new GaussianSplatRenderer({ renderer });
+scene.add(splatRenderer);
 ```
 
-## Basic options
+With `WebGPURenderer`, call `await renderer.init()` before creating it. Create your Three.js renderer with `antialias: false`: multisampling slows Splats down without improving them.
 
-| Option | Type | Default | Description |
-| --- | --- | --- | --- |
-| `renderer` | `WebGPURenderer \| THREE.WebGLRenderer` | Required | Three.js renderer; call `await renderer.init()` first when using WebGPURenderer |
-| `onDirty` | `() => void` | `undefined` | Called when the image needs a redraw |
-| `premultipliedAlpha` | `boolean` | `true` | Use premultiplied alpha for blending |
-| `timer` | `THREE.Timer` | New internal timer | Optional shared timer; update it yourself when supplied |
-| `autoUpdate` | `boolean` | `true` | Update visible Splats when rendering |
-| `preUpdate` | `boolean` | `true` | Update before rendering on WebGL; XR updates follow the render pass. Unused on native WebGPU |
+Every option except `renderer` and `timer` is also a property, so you can change it at any time.
 
-## Quality and appearance options
+## Basic options
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `maxStdDev` | `number` | `Math.sqrt(8)` | Control the extent of each Splat; lower values crop its outer edges |
-| `minPixelRadius` | `number` | `1` | Skip Splats smaller than this screen radius in pixels |
-| `maxPixelRadius` | `number` | `256` | Limit Splat screen radius in pixels, independently of `focalAdjustment` |
-| `minAlpha` | `number` | `0.5 / 255` | Hide parts more transparent than this value |
-| `preBlurAmount` | `number` | `0.3` | Enlarge and soften Splats |
-| `blurAmount` | `number` | `0` | Add smoothing with an opacity adjustment |
-| `clipXY` | `number` | `1.25` | Allow centers slightly outside the view; `1` clips at its edge |
-| `focalAdjustment` | `number` | `2` | Adjust projected size; higher values generally look sharper |
+| `renderer` | `WebGPURenderer \| THREE.WebGLRenderer` | Required | Your Three.js renderer |
+| `onDirty` | `() => void` | `undefined` | Called when the image needs a redraw; see [on-demand rendering](#on-demand-rendering) |
+| `autoUpdate` | `boolean` | `true` | Update Splats automatically on each render. Set to `false` to call `update()` yourself |
+| `preUpdate` | `boolean` | `true` | On WebGL, update before drawing so changes show in the same frame. In WebXR, updates run after drawing. Not used on native WebGPU |
+| `timer` | `THREE.Timer` | New internal timer | Share your own timer with [`onFrame`](SplatMesh.md#scene-integration) animations; update it yourself when supplied |
+| `premultipliedAlpha` | `boolean` | `true` | Blend with premultiplied alpha |
 
-## Sorting and material options
+## Quality options
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `sortRadial` | `boolean` | `false` | Sort by distance when `true`, or by camera depth when `false` |
-| `fastSort` | `boolean` | `true` | Lower-precision back-to-front sorting; does not affect stochastic rendering |
-| `minSortIntervalMs` | `number` | `0` | Minimum time between WebGL sorts; unused on native WebGPU |
-| `stochastic` | `boolean` | `false` | Enable stochastic rendering; use temporal anti-aliasing to smooth its noise |
-| `autoAdvanceStochasticSample` | `boolean` | `true` | Change the noise pattern on each render while stochastic rendering is active, including WebXR |
-| `stochasticSort` | `boolean` | `true` | Sort stochastic Splats from front to back; set to `false` to skip sorting |
-| `transparent` | `boolean` | `true` | Enable transparent blending in sorted rendering |
-| `depthTest` | `boolean` | `true` | Respect depth from other geometry |
-| `depthWrite` | `boolean` | `false` | Write depth directly; normally leave off for transparent Splats |
-
-Native WebGPU sorts before drawing. On WebGL, the current sort order stays in use until a new sort is ready.
-
-Automatic update errors are caught and logged once per error message, preventing unhandled promise rejections. If draw preparation fails, that draw is skipped so rendering can continue. Explicit `update()` calls report errors to the caller.
+| `maxStdDev` | `number` | `Math.sqrt(8)` | How far each Splat extends from its center. Lower values trim its soft outer edge and render faster; `Math.sqrt(4)` to `Math.sqrt(9)` looks acceptable |
+| `minPixelRadius` | `number` | `1` | Skip Splats smaller than this radius in screen pixels |
+| `minAlpha` | `number` | `1 / 255` | Hide the parts of a Splat more transparent than this |
+| `preBlurAmount` | `number` | `0.3` | Enlarge and soften Splats. Use `0` for models trained with anti-aliasing |
+| `blurAmount` | `number` | `0` | Soften Splats while adjusting their opacity to compensate. For models trained with anti-aliasing, use `0.3` together with `preBlurAmount: 0` |
+| `clipXY` | `number` | `1.25` | How far outside the view a Splat's center may be before the Splat is skipped; `1` cuts exactly at the edge |
+| `focalAdjustment` | `number` | `2` | Adjust the size of Splats on screen; higher values generally look sharper |
 
-See [Stochastic rendering](StochasticRendering.md) for setup and temporal anti-aliasing.
+A Splat's radius on screen is limited automatically to the short side of the viewport.
 
-### WebXR and multiple views
+## Sorting and blending options
 
-WebXR uses the eyes' mean pose for generation and sorting, with a separate projection for each eye. Splats on either eye's layers are visible in both eyes. Eye poses are read directly from Three.js's world matrices, preserving the camera rig transform.
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `sortRadial` | `boolean` | `false` | Sort by distance from the camera instead of by depth. Depth suits most models; distance is steadier while the camera rotates |
+| `fastSort` | `boolean` | `true` | Faster, lower-precision sorting. Has no effect on stochastic rendering |
+| `minSortIntervalMs` | `number` | `0` | Minimum time between sorts on WebGL. Not used on native WebGPU |
+| `transparent` | `boolean` | `true` | Blend Splats as transparent objects |
+| `encodeLinear` | `boolean` | `undefined` | Convert model colors from sRGB to linear before blending; `false` keeps their sRGB values. Chosen automatically when unset |
+| `depthTest` | `boolean` | `true` | Let other geometry hide the Splats behind it |
+| `depthWrite` | `boolean` | `false` | Write Splat depth. Normally leave off, because most of a Splat is transparent |
 
-With `autoUpdate = true`, render normally with your application camera; Three.js updates the XR camera when rendering.
+On native WebGPU, Splats are sorted before every draw. On WebGL, sorting finishes in the background: after the view changes, the previous order stays on screen until the new one is ready.
 
-For multiple views outside WebXR, use separate cameras. Non-XR `ArrayCamera` rendering is not supported: `update()` throws, and other draws skip Splats and log an error. For independent sorting, give each camera its own Splat renderer on a separate layer.
+## Stochastic rendering options
 
-### Color management
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `stochastic` | `boolean` | `false` | Use stochastic rendering; smooth its noise with temporal anti-aliasing |
+| `stochasticSort` | `boolean` | `true` | Sort Splats from front to back in stochastic rendering; `false` skips sorting |
+| `autoAdvanceStochasticSample` | `boolean` | `true` | Change the noise pattern on every render, including in WebXR |
 
-Built-in materials handle model color conversion. Use your Three.js renderer's output color-space settings to control the final image.
+See [Stochastic rendering](StochasticRendering.md) for setup.
 
-## Common properties and methods
+## Properties and methods
 
 | API | Description |
 | --- | --- |
-| `update({ scene, camera })` | Refresh the scene and camera state; returns `Promise<void>` |
-| `shrinkResources({ scene, camera })` | Reduce retained rendering resources after scene changes |
-| `clearSplats()` | Clear the current Splat display without removing scene objects |
+| `update({ scene, camera })` | Bring the Splats up to date with the scene and camera; returns a promise. Only needed with `autoUpdate = false` |
+| `shrinkResources({ scene, camera })` | Update, then release memory that is no longer needed, for example after removing large models; returns a promise |
+| `clearSplats()` | Clear the Splats from the display without removing models from the scene |
 | `dispose()` | Release this renderer's resources |
-| `stochasticActive` | Read whether stochastic rendering is still active while switching modes |
-| `stochasticSample` | Noise pattern index; defaults to 0. Each value selects an independent pattern. Disable `autoAdvanceStochasticSample` to control it yourself |
-| `synchronousSort` | Read whether sorting finishes before drawing: `true` on native WebGPU |
-
-`premultipliedAlpha`, `transparent`, `depthTest`, and `depthWrite` are also writable properties with the behavior listed above.
+| `stochasticActive` | Read-only. Whether stochastic rendering is currently being drawn; it changes shortly after you set `stochastic` |
+| `stochasticSample` | Noise pattern index, `0` by default. Set `autoAdvanceStochasticSample = false` to control it yourself |
+| `synchronousSort` | Read-only. `true` when Splats are always sorted before they are drawn, as on native WebGPU |
 
-For manual updates after scene or camera changes:
+To update manually after the scene or camera changes:
 
 ```js
 splatRenderer.autoUpdate = false;
@@ -86,9 +84,25 @@ await splatRenderer.update({ scene, camera });
 renderer.render(scene, camera);
 ```
 
+Errors during automatic updates are logged to the console, once per message, and rendering continues. Errors from your own `update()` calls are thrown to you.
+
+## WebXR and multiple views
+
+WebXR needs no extra setup: render with your application camera as usual. A Splat model on either eye's layers is visible in both eyes.
+
+For several views outside WebXR, render each one with its own camera. `ArrayCamera` is supported only in WebXR: elsewhere `update()` throws, and automatic draws skip the Splats and log an error. If each view needs its own sort order, give each camera its own Splat renderer on a separate layer.
+
+## Color and postprocessing
+
+Model colors are converted for you. Control the final image with your Three.js renderer's output color space, as for any other scene.
+
+Set `encodeLinear` to choose the conversion yourself. For example, to blend Splats in sRGB next to a linear scene, render them into their own target with `encodeLinear: false`, then unpremultiply that layer, convert it to linear, and premultiply it again before compositing.
+
+For temporal anti-aliasing and effects such as Bloom, see [TAAPass and TAANode](TAAPass.md). To render offscreen, read pixels back, or build cube and environment maps, use [SplatCapture](SplatCapture.md).
+
 ## On-demand rendering
 
-Connect `onDirty` and `OrbitControls` to the same render scheduler. This example assumes `renderer`, `scene`, and `camera` already exist; use it in place of the earlier Splat renderer setup and render loop.
+To render only when something changes, connect `onDirty` and your controls to the same render request. This example assumes `renderer`, `scene`, and `camera` already exist:
 
 ```js
 import { OrbitControls } from "three/addons/controls/OrbitControls.js";
@@ -124,12 +138,14 @@ const splat = new SplatMesh({ url: "/assets/model.spz" });
 scene.add(splat);
 requestRender();
 await splat.initialized;
-requestRender(); // Loading may finish after the render scheduler becomes idle.
+requestRender(); // Loading may finish after the last requested render.
 ```
 
+Request a render yourself after changing a model:
+
 ```js
 splat.opacity = 0.5;
 requestRender();
 ```
 
-See the [overview](Architecture.md) for the main loading and rendering workflow.
+See the [quick start](../README.md#quick-start) for a complete setup.

package/docs/PostDecode.md

@@ -2,9 +2,7 @@
 
 [Back to documentation](../README.md#documentation)
 
-Changes each Splat while loading PLY/SPZ/SOG/RAD files. Use `define()` to describe the changes, then pass the result as `postDecode`.
-
-`define()` runs its callback immediately, so mistakes in the expression throw right away; the result is then applied to each Splat while loading.
+Changes every Splat of a model while it loads: move it, scale it, recolor it, or adjust its opacity. Describe the change once with `postDecode.define()`, then pass the result as the `postDecode` option of `SplatMesh` or `Splats`. It works for PLY, SPZ, SOG, and RAD files.
 
 ```ts
 import { postDecode, SplatFileType, SplatMesh } from "gaussian-splat-lite";
@@ -22,38 +20,55 @@ const mesh = new SplatMesh({
 await mesh.initialized;
 ```
 
-Also accepted by `Splats`. The example shifts the model and gives it a warmer tint. All `postDecode` transforms preserve Splat count and order; [spatial reordering](Splats.md#data-rules) runs afterward.
+This example shifts the model and gives it a warmer tint.
+
+Your callback runs once, right away, to record the calculation; it does not run for each Splat. That has two consequences:
+
+- Build the calculation with the `op` functions. A JavaScript `if` or `+` cannot see individual Splats.
+- Mistakes in the calculation throw immediately from `define()`, not later during loading.
+
+A transform never adds, removes, or reorders Splats. The [reordering done by loading](Splats.md#data-rules) happens afterwards.
 
-## Logical input
+To change a model after it has loaded, use [SplatMesh properties](SplatMesh.md#properties) or [SDF edits](SplatEdit.md) instead.
+
+## Splat fields
+
+Read these from `splat`:
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `splat.position` | `vec3` | xyz center |
-| `splat.scale` | `vec3` | Linear scale along each axis |
-| `splat.quaternion` | `quaternion` | xyzw rotation |
-| `splat.opacity` | `float` | Model opacity, including values above 1 |
-| `splat.alpha` | `float` | Alpha from 0 (transparent) to 1 (opaque) |
+| `splat.position` | `vec3` | Center, xyz |
+| `splat.scale` | `vec3` | Size along each axis |
+| `splat.quaternion` | `quaternion` | Rotation, xyzw |
+| `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 degree-1-through-3 RGB coefficients |
+| `splat.sh.coefficient(index)` | `vec3` | One of the 15 view-dependent color coefficients |
 
-`splat.sh.map((coefficient, { degree }) => ...)` builds expressions for all 15 coefficients; only those present in the source are updated.
+`splat.sh.map((coefficient, { degree }) => ...)` builds a calculation for all 15 coefficients at once. Only the ones the model has are updated.
 
-## Patch output
+## Returning changes
 
-Return any subset of `position`, `scale`, `quaternion`, `opacity`, `alpha`, `color`, or `sh`. Omitted fields stay unchanged. Use `when` to apply changes only to matching Splats; when false, the entire Splat stays byte-for-byte unchanged.
+Return any of `position`, `scale`, `quaternion`, `opacity`, `alpha`, `color`, or `sh`. Fields you leave out stay as they are.
 
-- Negative `opacity` values become zero. Values above 1 use an extended kernel shape and saturate at the codec's maximum shape.
-- `alpha` is clamped to `[0, 1]`, preserving other opacity state. Output either `opacity` or `alpha`, never both.
-- Quaternions are normalized. Invalid or zero-length results preserve the original.
-- Position and scale updates keep sorting centers synchronized.
+Add `when` to change only the Splats that match a condition. Splats that do not match stay exactly as loaded:
 
-`when` short-circuits nested `and`, `or`, and `not` expressions, so put cheap, selective conditions first. For example, `op.or(A, op.and(B, C))` means `A || (B && C)`.
+```ts
+const transform = postDecode.define(({ splat, op }) => ({
+  when: op.lt(op.component(splat.position, 1), 0), // Only Splats below y = 0.
+  alpha: 0,
+}));
+```
 
-Expressions use float32 precision. Programs are limited to 4096 instructions, and compiled conditions to 4096 flow nodes; exceeding either limit throws. Output uses the `Splats` packed codecs, so stored values may be quantized. SH NaN channels become zero without affecting other channels' shared exponent.
+Rules for the values you return:
 
-## External attributes
+- Return `opacity` or `alpha`, never both. `alpha` is limited to 0–1. A negative `opacity` becomes 0, and values above 1 are allowed up to a fixed maximum.
+- Quaternions are normalized for you. An invalid or zero-length result keeps the original rotation.
+- Values are stored in a compact format, so what you read back later can differ slightly from what you calculated.
 
-Inside `define(({ splat, op, attribute }) => ...)`, bind per-Splat data with `attribute()`:
+## External data
+
+Inside `define(({ splat, op, attribute }) => ...)`, use `attribute()` to bring in your own per-Splat data, such as a weight or label for each Splat:
 
 ```ts
 const weights = attribute({
@@ -67,21 +82,22 @@ const weights = attribute({
 ```
 
 - `data` accepts any `ArrayBufferView`, including `DataView`; `byteOffset` is relative to that view.
-- `components` accepts 1–4. Formats: `f32`, `f16`, `u8`, `unorm8`, `i8`, `snorm8`, `u16`, `unorm16`, `i16`, `snorm16`, `u32`, `i32`.
-- Attribute data is read when a load starts. Changing it afterwards affects only later loads.
-- Match attributes to Splats in their original file order, including for RAD files. If an attribute array is shorter than the model, only the matching prefix is changed.
-
-## Expression operations
-
-Use `op` to calculate per-Splat values; JavaScript `if` does not evaluate individual Splats.
+- `components` can be 1 to 4. Formats: `f32`, `f16`, `u8`, `unorm8`, `i8`, `snorm8`, `u16`, `unorm16`, `i16`, `snorm16`, `u32`, `i32`.
+- Order the data like the Splats in the original file, for RAD files too. If it is shorter than the model, only the Splats it covers are changed.
+- The data is read when a load starts. Changing it afterwards affects only later loads.
 
-- arithmetic: `add`, `sub`, `mul`, `div`, `min`, `max`, `pow`, `clamp`, `mix`, `neg`, `abs`, `sqrt`, `log`, `exp`, `floor`, `ceil`, `round`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, and `atan2`;
-- predicates: `isFinite`, `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `and`, `or`, `not`, and `select`;
-- vectors: `vec2`, `vec3`, `vec4`, `component`, `length`, `normalize`, `dot`, `cross`, and `maxComponentIndex`;
-- rotations: `quaternion`, `quatMul`, and `rotateVector`;
+## Operations
 
-A number can be combined with a vector, for example `op.mul(splat.scale, 2)`. Values from different `postDecode` programs cannot be combined.
+- **Arithmetic:** `add`, `sub`, `mul`, `div`, `min`, `max`, `pow`, `clamp`, `mix`, `neg`, `abs`, `sqrt`, `log`, `exp`, `floor`, `ceil`, `round`, `sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`
+- **Conditions:** `isFinite`, `eq`, `ne`, `lt`, `lte`, `gt`, `gte`, `and`, `or`, `not`, `select`
+- **Vectors:** `vec2`, `vec3`, `vec4`, `component`, `length`, `normalize`, `dot`, `cross`, `maxComponentIndex`
+- **Rotations:** `quaternion`, `quatMul`, `rotateVector`
 
-Comparisons and vector products do not accept a number in place of a vector: `eq` and `ne` compare values of the same type, `lt`, `lte`, `gt`, and `gte` compare numbers, `dot` takes two vectors of the same size, and `cross` takes two `vec3` values.
+Things to know:
 
-To change a model after loading, use [SplatMesh properties](SplatMesh.md#common-properties) or [region edits](SplatEdit.md).
+- A number can be combined with a vector: `op.mul(splat.scale, 2)`.
+- Comparisons and vector products need matching types. `eq` and `ne` compare two values of the same type; `lt`, `lte`, `gt`, and `gte` compare numbers; `dot` takes two vectors of the same size; `cross` takes two `vec3` values.
+- `op.or(A, op.and(B, C))` means `A || (B && C)`. Conditions stop as soon as the answer is known, so put cheap conditions that rule out many Splats first.
+- Values from different `define()` calls cannot be combined.
+- Calculations use 32-bit floats.
+- Very large calculations throw: the limit is 4096 operations.

package/docs/RadStreamScheduler.md

@@ -2,7 +2,7 @@
 
 [Back to documentation](../README.md#documentation)
 
-Loads large RAD scenes with detail that adapts as the camera moves. Supports RAD version 1 with levels of detail (LOD), as a single `.rad` file or split files with `.radc` companions. Works on WebGPU and WebGL2 without a Spark runtime.
+Shows large RAD scenes by loading only the detail the camera needs, and updating it as the camera moves. It supports RAD version 1 files with levels of detail (LOD), either as a single `.rad` file or split into a header and `.radc` pages. It works on WebGPU and WebGL2, and needs no Spark runtime.
 
 ```js
 import { RadStreamScheduler } from "gaussian-splat-lite";
@@ -21,7 +21,7 @@ renderer.setAnimationLoop(() => {
   renderer.render(scene, camera);
 });
 
-// Requires update() to keep running.
+// Resolves when the first data is on screen. update() must be running.
 await streaming.firstRenderable;
 
 // When removing the model:
@@ -29,11 +29,23 @@ await streaming.firstRenderable;
 // streaming.group.removeFromParent();
 ```
 
-Use `streaming.group` to position, rotate, scale, or hide the scene. Streamed models support SDF edits and picking; their data is read-only.
+The three steps that matter:
 
-Resolution is in CSS pixels, without the device pixel ratio, so a scene selects the same detail on standard and high-DPI displays. Register several cameras to load detail for all of them; they share one selection at the greatest detail any of them needs.
+1. Add `streaming.group` to the scene. Move, rotate, scale, or hide the scene through this group.
+2. Register the camera and its resolution.
+3. Call `streaming.update()` before every render.
 
-In WebXR, register `renderer.xr.getCamera()` in place of your camera. Detail is selected for each eye at the headset's resolution, so no resolution is needed:
+Streamed models support [SDF edits](SplatEdit.md) and [picking](SplatMesh.md#raycasting). Their data is read-only.
+
+## Cameras and resolution
+
+Detail depends on how large the scene appears, so each camera needs a resolution. It is in CSS pixels, without the device pixel ratio, so a scene loads the same detail on standard and high-DPI displays. Set it again whenever the canvas is resized.
+
+Register several cameras to load detail for all of them. They share one selection, at the highest detail any of them needs.
+
+### WebXR
+
+Register `renderer.xr.getCamera()` in place of your camera. Detail is chosen for each eye at the headset's resolution, so no resolution is needed:
 
 ```js
 const xrCamera = renderer.xr.getCamera();
@@ -53,50 +65,48 @@ renderer.setAnimationLoop(() => {
 });
 ```
 
-Ordinary camera matrices are updated by the scheduler. The XR camera's matrices are read directly from Three.js, so detail selection before rendering may use the previous frame's pose.
-
-For original Splat IDs, use the picking hit's [`sourceIndex`](SplatMesh.md#raycasting).
-
 ## Options
 
 | Option | Default | Description |
 | --- | --- | --- |
 | `url` / `file` / `fileBytes` | Exactly one required | URL, `Blob`/`File`, or complete `Uint8Array`/`ArrayBuffer` |
-| `resolveFile` | Relative URL resolution | Companion-page resolver: `(filename, signal) => URL \| Blob \| Uint8Array \| ArrayBuffer`, optionally asynchronous |
-| `group` | New `THREE.Group` | Parent group for moving, rotating, scaling, or hiding the scene |
-| `splatBudget` | `3_000_000` | Maximum selected Splat count before transition overlap |
-| `cooldownMs` | `2000` | Milliseconds to retain unused pages after fade-out; `0` releases eligible pages immediately |
-| `fadeDurationMs` | `200` | Initial visibility and LOD fade duration in milliseconds; `0` switches immediately |
-| `maxConcurrentLoads` | `4` | Maximum simultaneous loads |
-| `manager` | `THREE.DefaultLoadingManager` | Loading manager and URL modifiers |
-| `requestHeader` / `withCredentials` | `{}` / `false` | Request settings; sensitive settings are not forwarded to other origins |
-| `onChange` | — | Request a redraw when data or visibility changes |
-| `onError` | Console error | Failure callback: `(error, url)` |
+| `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 |
+| `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 |
+| `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)` |
 
-Existing detail stays visible while replacement detail loads. Fades can temporarily exceed `splatBudget`; use `fadeDurationMs: 0` to switch immediately. Cached data also uses memory, so the budget is not a total memory limit.
+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.
 
-Ready pages are written during `update()` without a per-update byte limit. Loading concurrency and pending decode memory remain bounded.
-
-## Common properties and methods
+## Properties and methods
 
 | API | Description |
 | --- | --- |
-| `group` | Parent group for moving, rotating, scaling, or hiding the scene |
-| `splatBudget` | Positive safe integer; change it at runtime to adjust detail, even while the camera is stationary |
-| `initialized` | Resolves when scene setup is ready; rejects invalid or unsupported input |
-| `firstRenderable` | Resolves when the first data becomes visible, or the scene is empty; rejects if the first data cannot be loaded. Keep calling `update()` while waiting |
-| `setCamera(camera)` / `deleteCamera(camera)` | Add or remove a camera that selects detail; `hasCamera(camera)` and `cameras` list them |
-| `setResolution(camera, width, height)` | Set a registered camera's render size in CSS pixels; also accepts a `THREE.Vector2` |
-| `setResolutionFromRenderer(camera, renderer)` | Set a registered camera's resolution from `renderer.getSize()` |
-| `update()` | Update detail, loading, fades, and cleanup for the registered cameras; throws if none are registered |
-| `getBoundingBox()` | Approximate bounds in group coordinates; empty until the first data loads |
-| `getGlobalIndex(mesh, renderedIndex)` | Convert a picking result to a stable node index in the RAD file |
-| `stats` | Visible and retained Splat data, loading progress, and memory estimates; not total browser memory |
-| `dispose()` | Cancel loading and release scene resources; pending readiness promises reject with `AbortError` |
-
-For on-demand rendering, use `onChange` to request redraws and keep calling `update()` each animation tick so loading, retries, fades, and cleanup progress.
-
-Cooldown uses elapsed time, independent of update frequency. Pending LOD decisions defer expired-page cleanup so newly needed pages can be reused. Each accepted decision updates demand before cleanup, even during camera movement; existing page pins still apply.
+| `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 |
+| `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 |
+| `setResolution(camera, width, height)` | Set a registered camera's size in CSS pixels; also accepts a `THREE.Vector2` |
+| `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` | Numbers for monitoring, such as `visibleSplats`, `loadingChunks`, `downloadedBytes`, and `residentBytes`. Memory figures are estimates, not total browser memory |
+| `dispose()` | Stop loading and release the scene. Pending `initialized` and `firstRenderable` promises reject with `AbortError` |
+
+### On-demand rendering
+
+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()`.
+
+### 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:
 
 ```js
 const hits = raycaster.intersectObject(streaming.group, true);
@@ -108,6 +118,8 @@ if (hits.length && hits[0].index !== undefined) {
 
 ## Error recovery
 
-Temporary download failures and lost decoder workers are retried automatically, waiting longer after each attempt, up to 30 seconds. Retryable HTTP errors are 408, 425, 429, and 5xx. Invalid data, out-of-memory errors, and other HTTP errors are reported to `onError` and not retried. Each retry calls `onChange`, so on-demand render loops resume loading once the connection returns.
+Temporary download failures are retried automatically, waiting longer after each attempt, up to 30 seconds. This covers network errors and HTTP 408, 425, 429, and 5xx responses. Each retry calls `onChange`, so an on-demand render loop resumes loading when the connection returns.
+
+Invalid data, out-of-memory errors, and other HTTP errors are reported to `onError` and are not retried.
 
-If LOD selection or preparation fails, or the LOD worker is lost during page loading, `onError` is called and the scene keeps its current detail but stops refining; create a new scheduler to try again.
+If the scheduler can no longer choose detail after an internal failure, it calls `onError` and keeps showing its current detail without refining further. Create a new scheduler to try again.