gaussian-splat-lite 1.2.0 → 1.2.2

package/docs/TAAPass.md

@@ -1,105 +1,104 @@
-# TAAPass
+# TAAPass and TAANode
 
 [Back to documentation](../README.md#documentation)
 
-Temporal anti-aliasing for **WebGLRenderer**. Import `TAAPass` from `gaussian-splat-lite`. For **WebGPURenderer**, including its WebGL2 fallback, use the library's [TAANode](#webgpurenderer-tsl-version).
+Temporal anti-aliasing (TAA) blends each frame with the ones before it. It smooths edges and the noise of [stochastic rendering](StochasticRendering.md). Use the version that matches your renderer:
 
-The pass is based on Three.js TRAA and needs no velocity texture. Camera motion is supported; independent object motion and changes to individual Splats are not tracked.
+| Renderer | Use |
+| --- | --- |
+| `WebGLRenderer` | [`TAAPass`](#taapass-webglrenderer) with `EffectComposer` |
+| `WebGPURenderer`, on WebGPU or its WebGL2 fallback | [`TAANode`](#taanode-webgpurenderer) with `RenderPipeline` |
 
-## Constructor
+Both render the scene themselves and need no velocity buffer or other scene setup.
 
-```ts
-import { TAAPass } from "gaussian-splat-lite";
+## Before you start
 
-const taa = new TAAPass(scene, camera);
-```
+- **One camera.** A `PerspectiveCamera` or `OrthographicCamera`, including custom projections, scaled camera rigs, reversed depth, and logarithmic depth. WebXR is not supported.
+- **Camera movement only.** Moving objects and changes to individual Splats are not tracked, and may leave a faint trail.
+- **Stencil follows your renderer.** Create the Three.js renderer with `stencil: true` and stencil masks work as they do without TAA, including the stencil settings on your Splat renderer's `material`.
+- **Reset after a jump.** Call `taa.reset()` after a camera cut or after replacing the scene. Resizing resets automatically.
+- **Keep rendering while the image settles.** With on-demand rendering, render several more frames after each change. The viewer renders 32.
 
-`scene` is a Three.js `Scene`, and `camera` is a `PerspectiveCamera` or `OrthographicCamera`. The pass renders the scene itself and manages camera jitter internally. It supports one non-XR camera.
+## TAAPass (WebGLRenderer)
 
-## WebGLRenderer setup
-
-This example assumes an existing `renderer`, `scene`, and `camera`. If smoothing [stochastic rendering](StochasticRendering.md), also set `splatRenderer.stochastic = true`. The repository's `examples/viewer/viewerTAA.js` uses this same setup.
+This example assumes an existing `renderer`, `scene`, and `camera`. `TAAPass` takes the place of `RenderPass`, and Three.js's `OutputPass` finishes the image for display.
 
 ```js
 import { TAAPass } from "gaussian-splat-lite";
+import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
 
 const taa = new TAAPass(scene, camera);
+const output = new OutputPass();
+const composer = new EffectComposer(renderer);
+composer.addPass(taa);
+composer.addPass(output);
 
 renderer.setAnimationLoop(() => {
   // Update controls / animation here.
-  taa.render(renderer);
+  composer.render();
 });
 
-// On resize: update the renderer size and camera projection.
+// On resize: update the renderer size and camera projection,
+// then call composer.setSize(width, height) in CSS pixels.
 // On a camera cut or scene replacement: taa.reset().
 // On cleanup:
 // renderer.setAnimationLoop(null);
+// composer.dispose();
+// output.dispose();
 // taa.dispose();
 ```
 
-`TAAPass` renders the scene and presents the result directly; no composer is needed. To add linear effects such as Bloom, see [Color space](#color-space).
-
-The pass follows the canvas size. Call `reset()` after a camera cut or scene replacement; resizing clears history automatically. For on-demand rendering, keep rendering for several frames after each change; the viewer uses 32.
-
-### EffectComposer and offscreen rendering
-
-For a postprocessing chain, add the pass to an `EffectComposer`:
-
-```js
-import { EffectComposer } from "three/addons/postprocessing/EffectComposer.js";
+Dispose the passes as well as the composer when you are done. The repository's `examples/viewer/viewerTAA.js` uses this setup.
 
-const composer = new EffectComposer(renderer);
-composer.addPass(taa);
-// Render with composer.render(); update composer.setSize() on resize.
-```
-
-`TAAPass` replaces `RenderPass` and follows the composer's size. Its result is ready for display, so do not add `OutputPass` unless using linear effects as described below. Dispose both `taa` and `composer` when finished.
+### Add effects
 
-To render offscreen directly, pass a target; the pass follows its size:
+Insert Bloom and similar effects between `TAAPass` and `OutputPass`:
 
 ```js
-taa.render(renderer, target);
+import { Vector2 } from "three";
+import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
+
+const bloom = new UnrealBloomPass(
+  renderer.getSize(new Vector2()), 0.6, 0.4, 0.8,
+);
+composer.insertPass(bloom, 1);
+// On cleanup: bloom.dispose().
 ```
 
-Without a target, the pass follows the canvas size. Call `taa.dispose()` when finished.
+The order is `TAAPass → effects → OutputPass`. Effects work on the smoothed image.
 
-### Color space
+### Use depth in effects
 
-By default, `accumulateInOutputSpace = true`: the pass renders and accumulates in `renderer.outputColorSpace`, so Splats look the same as when drawn directly to the canvas. The result is ready for display. Adding `OutputPass` would convert the colors a second time.
-
-For Bloom and other linear effects, set `accumulateInOutputSpace = false` and finish the chain with `OutputPass`:
+`taa.depthTexture` gives later effects the scene depth of the current frame. Set it up once when building the chain:
 
 ```js
-import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
+depthEffect.uniforms.tDepth.value = taa.depthTexture;
+depthEffect.uniforms.captureProjection.value = taa.projectionMatrix;
 
-taa.accumulateInOutputSpace = false;
+const composer = new EffectComposer(renderer);
 composer.addPass(taa);
-// Add Bloom or other linear effects here.
+composer.addPass(depthEffect);
 composer.addPass(new OutputPass());
 ```
 
-In this mode, Splats blend in linear space, which makes partially transparent areas slightly brighter than direct canvas rendering.
+Here `depthEffect` is your own pass that reads those uniforms. Both objects stay the same across frames and resizes.
 
-### Depth effects
+This depth is not smoothed, and it is rendered with a small per-frame camera offset. Convert it with `taa.projectionMatrix`, not `camera.projectionMatrix`. Treat both as read-only.
 
-`taa.depthTexture` exposes the current scene capture's depth for subsequent effects. When building the chain, bind it once and run the effect after `TAAPass`:
+### Render to your own target
 
-```js
-depthEffect.uniforms.tDepth.value = taa.depthTexture;
-depthEffect.uniforms.captureProjection.value = taa.projectionMatrix;
+To get the smoothed image offscreen, pass a render target; the pass follows the target's size:
 
-const composer = new EffectComposer(renderer);
-composer.addPass(taa);
-composer.addPass(depthEffect);
+```js
+taa.render(renderer, target);
 ```
 
-Here `depthEffect` is a custom pass that consumes those uniforms. Both objects stay the same across frames and resizes, so bind them once.
-
-The depth is the current frame's raw depth, rendered with camera jitter and not temporally smoothed. Use `taa.projectionMatrix` to decode it, not `camera.projectionMatrix`, which no longer includes the jitter. Treat both as read-only.
+The result is in the working color space, without tone mapping. Calling `taa.render(renderer)` without a target is not supported; use `EffectComposer` to draw to the screen.
 
-## WebGPURenderer TSL version
+## TAANode (WebGPURenderer)
 
-`TAANode` implements the same camera/depth reprojection, 32-frame Halton jitter, depth rejection, neighborhood clipping, and luminance-aware blending for native WebGPU and WebGPURenderer's WebGL2 fallback. It captures the scene itself and uses two history targets, with no velocity attachment or history copies.
+Use this setup on both WebGPU and the WebGL2 fallback, after `await renderer.init()`:
 
 ```js
 import { TAANode } from "gaussian-splat-lite";
@@ -107,36 +106,62 @@ import { RenderPipeline } from "three/webgpu";
 
 const taa = new TAANode(scene, camera);
 const pipeline = new RenderPipeline(renderer, taa);
-pipeline.render();
-// On a camera cut / scene replacement: taa.reset().
+
+renderer.setAnimationLoop(() => {
+  // Update controls / animation here.
+  pipeline.render();
+});
+
+// On a camera cut or scene replacement: taa.reset().
 // On cleanup: pipeline.dispose(); taa.dispose();
 ```
 
-Chain TSL effects from the node or `taa.getTextureNode()`. Accumulation stays in the working color space; `RenderPipeline` applies tone mapping and output conversion at the end. `accumulateInOutputSpace` and the classic `Pass` properties apply only to `TAAPass`.
+The pipeline follows the renderer's size by itself.
+
+Chain effects from the node or from `taa.getTextureNode()`. For Bloom, create the pipeline like this instead:
+
+```js
+import { bloom } from "three/addons/tsl/display/BloomNode.js";
+
+const color = taa.getTextureNode();
+const pipeline = new RenderPipeline(renderer, color.add(bloom(color, 0.6, 0.4, 0.8)));
+```
 
-`TAANode` exposes the same `depthThreshold`, `edgeDepthDiff`, `maxMotionLength`, `useSubpixelCorrection`, `depthTexture`, and `projectionMatrix`. Both implementations support one non-XR perspective or orthographic camera, including custom projections, scaled camera rigs, reversed depth, and logarithmic depth. They track camera movement, not independent object motion.
+`TAANode` has the same `depthTexture`, `projectionMatrix`, and tuning properties as `TAAPass`.
+
+## Color and tone mapping
+
+**`TAAPass`** shows Splats with the same colors as `WebGLRenderer` drawing straight to the canvas.
+
+- `OutputPass` applies the renderer's tone mapping and exposure to the whole image, Splats included. Drawing straight to the canvas does not tone-map Splats.
+- If `TAAPass` is the last enabled pass, it shows its image as it is, without tone mapping.
+- On a transparent canvas, tone mapping and effects are approximate where pixels are partly transparent. Opaque pixels are unaffected.
+
+**`TAANode`** follows `WebGPURenderer`'s color handling: `RenderPipeline` applies tone mapping and the output color space at the end. With Three.js's default linear working color space, partly transparent Splats look slightly brighter than on `WebGLRenderer`.
+
+Both keep colors brighter than white, so effects such as Bloom work as expected. Changing the renderer's output color space with `TAAPass`, or Three.js's working color space with `TAANode`, restarts the smoothing.
 
 ## Properties
 
 | Property | Default | Description |
 | --- | --- | --- |
-| `scene` | Constructor scene | Scene to render; call `reset()` when replacing it. |
-| `camera` | Constructor camera | Camera used for jitter and reprojection; call `reset()` when replacing it. |
-| `accumulateInOutputSpace` | `true` | Accumulate in the output color space for direct display. Set `false` for linear effects and finish with `OutputPass`. |
-| `depthTexture` | Read-only | Current frame's scene depth. |
-| `projectionMatrix` | Read-only | Jittered projection matching `depthTexture`. |
-| `depthThreshold` | `0.0005` | Reject non-edge history when the depth difference exceeds this value. |
-| `edgeDepthDiff` | `0.001` | Depth range within the 3×3 neighborhood that identifies an edge. |
-| `maxMotionLength` | `128` | Camera motion in pixels at which history loses all weight. |
-| `useSubpixelCorrection` | `true` | Increase current-frame weight for subpixel camera motion. |
-
-The standard Three.js `Pass` properties, including `enabled` and `renderToScreen`, also apply. `EffectComposer` sets `renderToScreen` for its last enabled pass.
+| `scene` | Constructor scene | Scene to render; call `reset()` when replacing it |
+| `camera` | Constructor camera | Camera to render with; call `reset()` when replacing it |
+| `depthTexture` | Read-only | Scene depth of the current frame |
+| `projectionMatrix` | Read-only | Projection that matches `depthTexture` |
+| `depthThreshold` | `0.0005` | Depth change above which a pixel's earlier frames are discarded |
+| `edgeDepthDiff` | `0.001` | Depth difference between neighboring pixels that marks an edge. Edges are exempt from `depthThreshold` |
+| `maxMotionLength` | `128` | Camera movement, in pixels, at which earlier frames are ignored entirely |
+| `useSubpixelCorrection` | `true` | Give the current frame more weight during very small camera movements |
+
+The defaults suit most scenes. `TAAPass` also has the standard Three.js `Pass` properties.
 
 ## Methods
 
 | Method | Description |
 | --- | --- |
-| `setSize(width, height)` | Resize in physical pixels. Called automatically; a size change clears history. |
-| `render(renderer, writeBuffer = null)` | Render the scene and resolve TAA to the canvas or a supplied target. Also called by `EffectComposer`. |
-| `reset()` | Clear history and restart the jitter sequence. |
-| `dispose()` | Release the pass's GPU resources. The scene is not disposed. |
+| `reset()` | Discard earlier frames and start smoothing again |
+| `dispose()` | Release the resources it holds. The scene is not disposed |
+| `setSize(width, height)` | Resize in physical pixels. Called for you; a size change resets |
+| `render(renderer, target)` | `TAAPass` only. Called for you by `EffectComposer` |
+| `getTextureNode()` | `TAANode` only. The smoothed image, for chaining effects |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaussian-splat-lite",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Three.js Gaussian Splatting renderer with WebGPU/WebGL2, GPU sorting, streaming LOD, and high-precision GIS/ECEF support. Supports PLY, SPZ, SOG and RAD.",
   "author": "William Liu <lyz15972107087@gmail.com>",
   "type": "module",

package/docs/SplatAccumulator.md

@@ -1,37 +0,0 @@
-# SplatAccumulator
-
-[Back to documentation](../README.md#documentation)
-
-Combines visible Splat models for rendering. `GaussianSplatRenderer` manages this automatically; most applications only need its `update()` method.
-
-For custom integrations, the methods below expose the combined scene data. `ensureGenerate()` and `generate()` support WebGL only.
-
-## Constructor
-
-```ts
-new SplatAccumulator()
-```
-
-## Common state
-
-| Property | Description |
-| --- | --- |
-| `numSplats` | Number of Splats in the combined data |
-| `maxSplats` | Allocated Splat capacity |
-| `mapping` | Models and their ranges in the combined data |
-| `version` | Combined data version |
-| `mappingVersion` | Model mapping version |
-| `viewOrigin` / `viewDirection` | Camera position and direction used for the current data |
-| `time` / `deltaTime` | Timer values used for per-frame mesh updates |
-
-## Common methods
-
-| API | Description |
-| --- | --- |
-| `getTextures()` | Return the combined Splat textures |
-| `generateMapping(splatCounts, compact?)` | Assign model ranges and return the required capacity; `compact` reduces unused space |
-| `ensureGenerate({ maxSplats, renderer?, shrinkResources?, stochasticSeeds? })` | Prepare storage for the requested capacity; optionally shrink unused resources or reserve storage for stochastic rendering |
-| `generate({ mesh, base, count, renderer })` | Update one model's range at its current world position |
-| `prepareGenerate({ renderer, scene, timer, camera, layerCamera?, previous })` | Collect visible models and prepare their updates; `layerCamera` (default `camera`) decides which layers are visible |
-| `checkVersions(mapping)` | Check whether data, model ranges, or sorting need updating |
-| `dispose()` | Release this accumulator's resources |