gaussian-splat-lite 1.2.0 → 1.2.2

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.

package/docs/SogStreamScheduler.md

@@ -2,7 +2,7 @@
 
 [Back to documentation](../README.md#documentation)
 
-Loads large SOG `lod-meta.json` scenes with detail that adapts as the camera moves. 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 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).
 
 ```js
 import { SogStreamScheduler } from "gaussian-splat-lite";
@@ -15,65 +15,75 @@ scene.add(streaming.group);
 streaming.setCamera(camera);
 await streaming.initialized;
 
-// Call each animation tick, before rendering.
-streaming.update();
-renderer.render(scene, camera);
+renderer.setAnimationLoop(() => {
+  streaming.update();
+  renderer.render(scene, camera);
+});
+
+// Resolves when the first data is on screen. update() must be running.
+await streaming.firstRenderable;
 
 // When removing the model:
-streaming.dispose();
-streaming.group.removeFromParent();
+// streaming.dispose();
+// 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:
+
+1. Add `streaming.group` to the scene. Move, rotate, scale, or hide the scene through this group.
+2. Register the camera.
+3. Call `streaming.update()` before every render.
 
-Detail follows distance from the camera, so cameras need no resolution. Register several cameras to load detail for all of them; each region follows the nearest camera that sees it.
+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).
 
-In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown for [RadStreamScheduler](RadStreamScheduler.md). Detail is selected for each eye. Calling `update()` before rendering uses the previous frame's eye poses, and until the headset reports its first poses, the current detail and downloads are kept.
+## Cameras
 
-For original Splat IDs, use the picking hit's [`sourceIndex`](SplatMesh.md#raycasting).
+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.
+
+In WebXR, register `renderer.xr.getCamera()` in place of your camera, as shown for [RadStreamScheduler](RadStreamScheduler.md#webxr). Detail is chosen for each eye.
 
 ## Options
 
 | Option | Default | Description |
 | --- | --- | --- |
-| `url` | Required | Streamed SOG index URL |
-| `group` | New `THREE.Group` | Parent group for moving, rotating, scaling, or hiding the scene |
-| `splatBudget` | `3_000_000` | Target visible Splat count, including the environment |
-| `cooldownMs` | `2000` | Milliseconds to retain unused data after fade-out; `0` releases eligible data immediately |
-| `fadeDurationMs` | `200` | Visibility and LOD fade duration in milliseconds; `0` disables fades |
-| `maxConcurrentLoads` | `4` | Maximum simultaneous loads |
-| `manager` | `THREE.DefaultLoadingManager` | Loading manager and URL modifiers |
-| `requestHeader` / `withCredentials` | `{}` / `false` | Fetch settings; headers and credentials are not forwarded to cross-origin chunks |
-| `onChange` | — | Request a redraw when data or visibility changes |
-| `onError` | Console error | Chunk failure callback: `(error, url)` |
-| `loadChunk` | Built-in worker loader | Custom `(url, signal) => Promise<Splats>` loader |
-
-The Splat budget is a target: available detail levels, fades, and the environment can exceed it. Cached data also uses memory, so the budget is not a total memory limit.
+| `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 |
+| `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. Headers and credentials are not sent to files on other origins |
+| `onChange` | — | Called when the scene needs a redraw |
+| `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>` |
 
-Regions that disappear at coarser LODs can remain empty until selected for more detail. Empty levels do not load files; visible data fades out when a region returns to an empty level.
+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.
 
-Ready regions are attached during `update()` once their previous fade completes, without a per-update byte limit. Loading concurrency and pending extraction memory remain bounded.
+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.
 
-## Common properties and methods
+## Properties and methods
 
 | API | Description |
 | --- | --- |
-| `group` | Parent group for moving, rotating, scaling, or hiding the scene |
-| `splatBudget` | Positive safe integer including the environment; change it at runtime to adjust detail |
-| `initialized` | Resolves when the index is ready; rejects invalid input |
-| `firstRenderable` | Resolves when the first data becomes visible, or the scene is empty; rejects if the first data cannot be loaded or prepared. Keep calling `update()` while waiting |
-| `setCamera(camera)` / `deleteCamera(camera)` | Add or remove a camera that selects detail; `hasCamera(camera)` and `cameras` list them |
-| `update()` | Update detail, loading, fades, and cleanup for the registered cameras; throws if none are registered |
-| `getBoundingBox()` | Group-local index bounds, available after initialization |
-| `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` |
+| `group` | Group that holds the scene |
+| `splatBudget` | Change it at any time to adjust detail. Must be a positive integer; includes the environment |
+| `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 |
+| `dispose()` | Stop loading and release the scene. Pending `initialized` and `firstRenderable` 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.
+### On-demand rendering
 
-Cooldown uses elapsed time, independent of update frequency. Expired data releases during updates or after accepted LOD decisions once no longer needed. Pending decisions defer cleanup so newly needed data can be reused; each accepted decision permits cleanup even during camera movement.
+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()`.
 
 ## 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. Parts of the scene that are already on screen stay visible when loading more detail fails.
 
-Regions already on screen stay visible when loading more detail fails. If detail selection itself fails, `onError` is called and the scheduler disposes itself; create a new one to try again.
+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.

package/docs/SplatCapture.md

@@ -0,0 +1,147 @@
+# SplatCapture
+
+[Back to documentation](../README.md#documentation)
+
+Renders a scene and its Splats offscreen: into a render target, as pixels you can read back, as a cube map, or as an environment map for reflections. It works with `WebGLRenderer` and with `WebGPURenderer` on both WebGPU and its WebGL2 fallback.
+
+```js
+import { SplatCapture } from "gaussian-splat-lite";
+
+const capture = new SplatCapture({
+  splatRenderer, // The GaussianSplatRenderer already in your scene.
+  target: { width: 1920, height: 1080 },
+});
+
+const rgba = await capture.renderReadTarget({ scene, camera });
+// Uint8Array of 1920 × 1080 × 4 bytes, bottom row first.
+```
+
+Captures do not disturb what is on screen. Your render loop can keep running while one is in progress, and the display keeps its own camera and settings.
+
+[SDF edits](SplatEdit.md) apply to captures as they do on screen, whether they are attached to the scene or to a model.
+
+Coming from 1.1.8? These were methods and options of `GaussianSplatRenderer`. They keep the same names on `SplatCapture`, except the cube captures' `update` option, which is gone: every capture shows the current scene and reuses earlier work while nothing has changed.
+
+## Render to a target
+
+Pass `target` to capture 2D images. It accepts the options below plus `THREE.RenderTargetOptions`, except `stencilBuffer`, which follows the Three.js renderer.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `width` / `height` | Required | Image size in pixels |
+| `superXY` | `1` | Supersampling, an integer from 1 to 4. The scene renders at `superXY` times the size on each axis and is averaged down when read back |
+| `doubleBuffer` | `false` | Alternate between two targets, so `capture.target` keeps a finished image while the next one renders |
+
+`width` and `height` multiplied by `superXY` can be at most 8192.
+
+| Method | Description |
+| --- | --- |
+| `renderTarget({ scene, camera })` | Render the view and return the `THREE.RenderTarget` holding it |
+| `readTarget()` | Read the latest render as RGBA bytes |
+| `renderReadTarget({ scene, camera })` | Do both in one call |
+
+`capture.target` always holds the latest finished render. Use `capture.target.texture` as a texture; its size includes supersampling.
+
+Pixels come back as a `Uint8Array` of `width × height × 4` bytes, bottom row first, in the same layout on every renderer. The array is reused by later reads, so copy it with `rgba.slice()` if you need to keep it.
+
+Targets are 8-bit RGBA in sRGB unless you say otherwise:
+
+- `samples` antialiases the meshes in the scene.
+- Stencil masking follows the Three.js renderer's stencil setting. Stencil settings on your Splat renderer's `material` apply to the Splats in the capture too.
+- `type: THREE.HalfFloatType` or `THREE.FloatType` keeps values above 1. Such targets can be rendered but not read back; reading requires 8-bit RGBA.
+
+2D captures also keep the scene's depth in the target.
+
+## Cube maps and environment maps
+
+```js
+const cube = await capture.renderCubeMap({
+  scene,
+  worldCenter: new THREE.Vector3(0, 1, 0),
+  size: 256,
+  hideObjects: [reflectiveMesh],
+});
+const faces = await capture.readCubeTargets(); // Six RGBA arrays.
+
+const envMap = await capture.renderEnvMap({
+  scene,
+  worldCenter: reflectiveMesh.getWorldPosition(new THREE.Vector3()),
+  hideObjects: [reflectiveMesh],
+});
+capture.recurseSetEnvMap(reflectiveMesh, envMap);
+```
+
+`target` is not needed when you only capture cube or environment maps.
+
+| Method | Description |
+| --- | --- |
+| `renderCubeMap(options)` | Render the six directions around a point and return a `THREE.CubeTexture` |
+| `readCubeTargets()` | Read the latest cube map as six RGBA arrays |
+| `renderEnvMap(options)` | Render a cube map and filter it into an environment map ready for `material.envMap` |
+| `recurseSetEnvMap(root, envMap)` | Assign an environment map to every `MeshStandardMaterial` under `root` |
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `scene` | Required | Scene to capture |
+| `worldCenter` | Required | Capture position in world space |
+| `size` | `256` | Size of each face in pixels, up to 8192 |
+| `near` / `far` | `0.1` / `1000` | Clipping distances |
+| `hideObjects` | `[]` | Objects to leave out of the capture, such as the mesh that will show the reflection. Their children, Splat models included, are left out too, except SDF edits, which still apply. They stay visible on screen |
+| `filter` | `false` | `renderCubeMap()` only. Capture linear color with mipmaps, for filtering the cube map into an environment map yourself |
+
+Cube faces are read in +X, −X, +Y, −Y, +Z, −Z order, with the same layout on every renderer. Each side face starts with its top (+Y) row.
+
+Cube and environment captures show the objects on Three.js layer 0.
+
+## Moving reflections
+
+To keep a reflection up to date while an object moves, start a capture from your render loop without awaiting it, and keep showing the previous environment map until the next one is ready. Run one capture at a time. For a `MeshStandardMaterial` with `WebGLRenderer`:
+
+```js
+let reflectionPending = false;
+let nextCaptureTime = 0;
+
+renderer.setAnimationLoop((time) => {
+  // Update the sphere's position and other animation here.
+  if (!reflectionPending && time >= nextCaptureTime) {
+    reflectionPending = true;
+    nextCaptureTime = time + 100; // Adjust the update interval for your scene.
+    capture.renderEnvMap({
+      scene,
+      worldCenter: sphere.getWorldPosition(new THREE.Vector3()),
+      hideObjects: [sphere],
+      size: 256,
+    }).then((envMap) => {
+      const previous = sphere.material.envMap;
+      capture.recurseSetEnvMap(sphere, envMap);
+      previous?.dispose();
+    }).catch(console.error).finally(() => {
+      reflectionPending = false;
+    });
+  }
+  renderer.render(scene, camera);
+});
+```
+
+With `WebGPURenderer`, use a `MeshStandardNodeMaterial` and assign one `pmremTexture(envMap)` node to `material.envNode`. For each later capture, set that node's `.value` to the new environment map, then dispose the old one.
+
+Each capture draws the scene six times, so update reflections less often than you render.
+
+## Good to know
+
+- **Await the result.** Every render and read method returns a promise.
+- **The view is fixed when you call.** A capture uses the camera or `worldCenter` as it was at the call, even if it moves before the capture finishes.
+- **Captures run in order.** A call made while another capture is in progress waits for it.
+- **Splat settings follow your renderer.** Captures use the quality and blending options of the `splatRenderer` you passed in.
+- **Stencil follows your renderer.** 2D, cube, and environment captures enable their stencil buffers when the Three.js renderer does. No capture option is needed. A 2D target created with `depthBuffer: false` has no stencil buffer either.
+- **Captures always use sorted rendering,** also when the display uses [stochastic rendering](StochasticRendering.md).
+- **Colors match the screen.** Splats blend as they do when the same renderer draws to the canvas, and the image is stored in the target's color space. Environment maps are linear.
+- **Animation does not advance.** Captures do not call [`onFrame`](SplatMesh.md#scene-integration); only your display renders do.
+- **Visibility and layers apply.** Models appear according to their visibility and the capture camera's layers.
+
+## Cleanup
+
+`capture.dispose()` releases the targets, cube maps, and other memory the capture holds. It does not dispose your Splat renderer or models.
+
+- The cube texture from `renderCubeMap()` belongs to the capture. Later calls redraw the same texture, or replace it when `size`, `near`, `far`, or the renderer's stencil setting change. `renderEnvMap()` leaves it untouched unless you captured it with `filter: true`.
+- Environment maps from `renderEnvMap()` belong to you. Call `envMap.dispose()` when you are done with one.

package/docs/SplatEdit.md

@@ -1,8 +1,10 @@
-# SDF color and opacity editing
+# SplatEdit and SplatEditSdf
 
 [Back to documentation](../README.md#documentation)
 
-SDF edits change color and opacity within a shape without moving or deleting Splats. Attach an edit to a `SplatMesh` to affect only that mesh:
+Recolor, fade, or hide the part of a model that lies inside a shape, such as a sphere or a box. Splats are not moved or deleted, so an edit can be changed or removed at any time. The shapes are signed distance fields (SDFs), which is where the class names come from.
+
+A `SplatEdit` holds the settings, and one or more `SplatEditSdf` shapes say where it applies. Attach the edit to a `SplatMesh` to affect only that mesh:
 
 ```js
 import * as THREE from "three";
@@ -29,52 +31,57 @@ edit.add(sphere);
 splat.add(edit);
 ```
 
-To affect all editable meshes, attach it to the scene:
+To affect every editable mesh, attach it to the scene instead:
 
 ```js
 scene.add(edit);
 ```
 
+A mesh created with `editable: false` ignores edits. Edits also work on [streamed scenes](RadStreamScheduler.md).
+
 ## SplatEdit options
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `name` | `string` | Generated | Object name |
-| `rgbaBlendMode` | `SplatEditRgbaBlendMode` | `MULTIPLY_RGBA` | Multiply, replace, or add to the assigned color and opacity channels |
-| `sdfSmooth` | `number` | `0` | Soften the join between shapes |
-| `softEdge` | `number` | `0` | Soften the region boundary |
-| `invert` | `boolean` | `false` | Affect the outside instead of the inside |
-| `sdfs` | `SplatEditSdf[]` | `null` | Explicit shape list; SDFs can instead be child objects |
-
-## SplatEdit methods
+| `rgbaBlendMode` | `SplatEditRgbaBlendMode` | `MULTIPLY_RGBA` | How the shapes' color and opacity combine with the model's; see [blend modes](#blend-modes) |
+| `softEdge` | `number` | `0` | Soften the edge of the edited region; `0` gives a hard edge |
+| `sdfSmooth` | `number` | `0` | Blend neighboring shapes into each other smoothly |
+| `invert` | `boolean` | `false` | Affect the outside of the shapes instead of the inside |
+| `sdfs` | `SplatEditSdf[]` | `null` | Explicit list of shapes, instead of using child objects |
 
-| API | Description |
-| --- | --- |
-| `addSdf(sdf)` | Add a shape to the explicit `sdfs` list without duplicates |
-| `removeSdf(sdf)` | Remove a shape from the explicit `sdfs` list |
+Shapes are normally children of the edit: use `edit.add(sdf)` and `edit.remove(sdf)`. If you set an explicit `sdfs` list, it is used instead of the children; manage it with `edit.addSdf(sdf)`, which skips duplicates, and `edit.removeSdf(sdf)`.
 
-An explicit `sdfs` list takes precedence over child objects. For child shapes, use `edit.add(sdf)` and `edit.remove(sdf)`.
+Edits apply in the order they were created. Change `edit.ordering` to reorder them.
 
-## RGBA blend modes
+## Blend modes
 
 | Mode | Description |
 | --- | --- |
-| `MULTIPLY_RGBA` | Multiplies each assigned channel by the corresponding SDF value |
-| `SET_RGBA` | Replaces each assigned channel with the corresponding SDF value |
-| `ADD_RGBA` | Adds the corresponding SDF value to each assigned channel |
+| `MULTIPLY_RGBA` | Multiply the model's color and opacity by the shape's values |
+| `SET_RGBA` | Replace the model's color and opacity with the shape's values |
+| `ADD_RGBA` | Add the shape's values to the model's color and opacity |
 
-Unassigned channels stay unchanged. For example, `color: { r: 1, g: 0.5 }` with `SET_RGBA` replaces only R and G. A `THREE.Color` assigns all RGB channels; `opacity` assigns alpha. Set a channel to `undefined` to unassign it.
+Only the channels a shape assigns are affected. A `THREE.Color` assigns red, green, and blue; `opacity` assigns alpha. For example, `color: { r: 1, g: 0.5 }` with `SET_RGBA` replaces only red and green. Set a channel to `undefined` to stop assigning it.
 
 ## SplatEditSdf options
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `type` | `SplatEditSdfType` | `SPHERE` | SDF shape |
-| `invert` | `boolean` | `false` | Affect the outside instead of the inside |
-| `opacity` | `number` | Unassigned | Opacity applied inside the shape; leave unassigned to preserve it |
-| `color` | `THREE.Color \| { r?: number; g?: number; b?: number }` | Unassigned | Color applied inside the shape; unassigned channels stay unchanged |
-| `radius` | `number` | `0` | Radius used by sphere, cylinder, capsule, and related shapes |
+| `type` | `SplatEditSdfType` | `SPHERE` | Shape |
+| `color` | `THREE.Color \| { r?: number; g?: number; b?: number }` | Unassigned | Color applied inside the shape |
+| `opacity` | `number` | Unassigned | Opacity applied inside the shape |
+| `radius` | `number` | `0` | Radius of a sphere, cylinder, capsule, and similar shapes |
+| `invert` | `boolean` | `false` | Affect the outside of this shape instead of the inside |
 
 Shapes (`SplatEditSdfType`): `ALL`, `PLANE`, `SPHERE`, `BOX`, `ELLIPSOID`, `CYLINDER`, `CAPSULE`, `INFINITE_CONE`.
 
-Move, rotate, and scale shapes with normal Three.js transforms, including transforms inherited from parents. `BOX` and `ELLIPSOID` take their half-size from `scale`, and `CAPSULE` takes its length from `scale.y`; scaling these shapes does not change their `radius`. Other shapes, including `SPHERE`, scale as a whole. A shape scaled to zero on any axis has no effect, even when inverted. With uneven scaling, soft edges are approximate. Edits apply in creation order; use `edit.ordering` to change it.
+## Placing and sizing shapes
+
+Move, rotate, and scale shapes like any Three.js object, including through their parents.
+
+- `BOX` and `ELLIPSOID` take their half-size from `scale`.
+- `CAPSULE` takes its length from `scale.y`.
+- For those three shapes, scaling does not change `radius`. Other shapes, `SPHERE` included, scale as a whole.
+- A shape scaled to zero on any axis has no effect, even when inverted.
+- With uneven scaling, soft edges are approximate.

package/docs/SplatFileType.md

@@ -2,18 +2,16 @@
 
 [Back to documentation](../README.md#documentation)
 
-Supported formats for ordinary model loading:
-
-```ts
-enum SplatFileType {
-  PLY = "ply",
-  SPZ = "spz",
-  SOG = "sog",
-  RAD = "rad",
-}
-```
+The model formats you can load:
+
+| Name | Value | Files |
+| --- | --- | --- |
+| `SplatFileType.PLY` | `"ply"` | `.ply` |
+| `SplatFileType.SPZ` | `"spz"` | `.spz` |
+| `SplatFileType.SOG` | `"sog"` | `.sog`, or a SOG `meta.json` with its images |
+| `SplatFileType.RAD` | `"rad"` | `.rad` |
 
-Usually inferred from a `.ply`, `.spz`, `.sog`, `.rad`, or SOG `meta.json` URL or `fileName`. Otherwise, set it explicitly:
+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
 import { SplatFileType, SplatMesh } from "gaussian-splat-lite";
@@ -24,6 +22,6 @@ const splat = new SplatMesh({
 });
 ```
 
-`SplatMesh` and `Splats` accept this option for URL, file, and byte input. `SplatLoader.load()` and `loadAsync()` detect the format automatically.
+`SplatMesh` and `Splats` accept `fileType` for URLs, files, and bytes. `SplatLoader.load()` and `loadAsync()` always detect the format themselves.
 
-For a SOG `lod-meta.json` scene, use [SogStreamScheduler](SogStreamScheduler.md). For RAD scenes with levels of detail, use [RadStreamScheduler](RadStreamScheduler.md).
+Large scenes with levels of detail load through their own classes: [SogStreamScheduler](SogStreamScheduler.md) for a SOG `lod-meta.json`, and [RadStreamScheduler](RadStreamScheduler.md) for RAD.