gaussian-splat-lite 0.1.15 → 1.0.0

package/CHANGELOG.md

@@ -7,6 +7,55 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-09-09
+
+### Added
+
+- Added `WebGPURenderer` support for native WebGPU, `forceWebGL`, and automatic WebGL2 fallback, using shared TSL shaders. Native WebGPU projects and culls Splats before 32-bit GPU sorting and indirect drawing; both WebGL backends use asynchronous Worker/WASM sorting. The new read-only `synchronousSort` property reports the backend's sorting mode.
+- Added `stochastic` and `autoStochastic` for sorting-free transparency, plus `renderDepth` for companion depth draws with stochastic alpha coverage. Automatic mode uses stochastic rendering during camera motion until a fresh sort is ready.
+- Added `StochasticResolvePass` for spatial noise reduction through direct scene composition, WebGL `EffectComposer`, or a custom render graph. Manual stochastic rendering and per-eye resolve support WebGL/WebGPU XR; automatic switching is disabled in XR.
+- Added SOG V1/V2 loading from ZIP bundles or directory metadata through the existing loading APIs, with HTTP Range access, concurrent property-image downloads, and grouped decoding.
+- Added Spark RAD version 1 loading for monolithic `.rad` files and split files with external `.radc` pages, including all property codecs and SH0–SH3/codebooks. Ordinary loading detects the RAD0 signature and extracts leaf records before applying `postDecode`.
+- Added `RadStreamScheduler` and `SogStreamScheduler` for camera-driven LOD and on-demand loading of RAD pages and Streamed SOG `lod-meta.json` scenes. Both support WebGL/WebGPU rendering, SDF edits, raycasting, visibility fades, LOD crossfades, cancellation, retries, and streaming statistics.
+- Added shared streaming controls for Splat budgets, upload allowance, load concurrency, and cooldown retirement. Defaults are 3,000,000 Splats, 8 MiB per update, four concurrent loads, 100 cooldown ticks, and 200 ms fades. LOD workers run separately from decoding workers and coalesce pending requests to the latest view; fixed source slots, compact visible indices, and partial uploads reduce repeated work.
+- Added `resolveFile` for local SOG companion images and RAD pages, accepting synchronous or asynchronous URL, Blob, or byte-array results with cancellation support.
+- Added an optional `AbortSignal` to `SplatLoader.loadAsync()`. Disposing loaded sources or replacing their initialization cancels pending downloads and decoding.
+- Added `Splats.extractRange()` to copy packed records, spherical harmonics, and sort centers into an independent source.
+- Added Splat record indices to raycast hits and `RadStreamScheduler.getGlobalIndex()` to map current batch indices to stable file-global RAD node indices.
+- Added viewer backend switching, output color-space and stochastic controls, WebGPU Inspector integration, and a toggleable grid with X/Z reference axes. The viewer accepts SOG/RAD files, streamed scene URLs, and multi-file selection or drop for local split assets.
+
+### Changed
+
+- Updated the Three.js peer dependency from `>=0.185.1` to `>=0.186.0`, pinned development to `0.186.0`, and removed compatibility workarounds fixed upstream.
+- Replaced `stream` and `streamLength` loading inputs with `file: Blob` (including `File`) in `Splats` and `SplatMesh`. PLY/SPZ files stream inside the worker; local SOG/RAD files use random reads. Existing `url` and `fileBytes` inputs remain available.
+- Changed the default `preBlurAmount` from `0` to `0.3` and `blurAmount` from `0.3` to `0`, expanding projected Splats without the previous blur opacity compensation. Set them to `0` and `0.3`, respectively, to restore the previous behavior.
+- Corrected `minPixelRadius` to use screen pixels independently of `focalAdjustment`. Its default remains `1`; divide previous values by `focalAdjustment` to preserve the old cutoff.
+- Increased the default `SplatMesh.minRaycastOpacity` from `0.1` to `0.15`.
+- Moved built-in Splat color conversion to vertex shaders and trimmed wide-kernel coverage using a conservative alpha bound while preserving the full-support visibility cutoff. Native WebGPU projection quantization can produce slight visual differences, and equal-depth Splats have no guaranteed source order.
+- Unified PLY/SPZ/SOG/RAD decoding around the platform-independent Rust library and shared receiver output, with thin WASM bridges. Reused PLY batches and SPZ decompression buffers, and reduced packed-buffer reads, writes, and temporary allocations.
+- Reorganized source code into data, loaders, runtime, scene, rendering, and utility modules while preserving existing package entry-point exports. Extracted offscreen capture, shared packed-data loading, and separate post-decode building, compilation and execution modules without changing public APIs. Simplified the README and API references, and added architecture and streaming guides.
+- Updated the viewer to use reversed depth buffers where supported and allow only one GPU frame in flight while retaining pending redraws and processing camera input. Replaced the bundled Lion model with Multi Material Splats by hybridherbst in SPZ v4 with SH3 data and CC BY 4.0 attribution.
+- Changed `npm run dev` to serve source directly through Vite, consolidated WASM builds into a cross-platform Node script, and split ES module and CommonJS bundle builds. Removed `build:watch` and the platform-specific WASM scripts.
+
+### Fixed
+
+- Corrected shared SH exponent selection in Rust and TypeScript so coefficients between powers of two no longer saturate at the lower power. Preserved finite color channels when another channel is NaN, and preserved the SH2 coefficient stored alongside SH1 when updating SH1. The packed layout and shader decoding are unchanged.
+- Rebuilt Splat textures when either source buffer, typed-array offset, or length changes, preventing stale GPU data.
+- Validated legacy SPZ gzip header and payload checksums, decoded sizes, trailers, and trailing data. Validated SPZ v4 Zstandard checksums and declared frame sizes against the stream table, rejecting corrupt or inconsistent files.
+- Corrected WebXR projection to use each eye's viewport dimensions instead of the full drawing buffer.
+- Recreated terminated WebGL sorting workers on the next sort and discarded late sorting results after renderer disposal.
+
+## [0.1.16] - 2026-09-03
+
+### Changed
+
+- Increased the default `SplatMesh.minRaycastOpacity` from `0.05` to `0.1`.
+- Accepted only the ellipsoid entry intersection, so rays starting inside a Splat or entering before the near plane no longer select its exit surface.
+
+### Fixed
+
+- Updated scene world matrices before Splat renderer updates read camera, mesh, and edit transforms, including explicit `update()` calls made before rendering.
+
 ## [0.1.15] - 2026-09-01
 
 ### Changed
@@ -32,7 +81,7 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ### Added
 
-- Added `tan`, `asin`, `atan`, and vector-aware `atan2(y, x)` operations to the experimental post-decode expression API.
+- Added `tan`, `asin`, `atan`, and vector-aware `atan2(y, x)` operations to the post-decode expression API.
 
 ## [0.1.12] - 2026-08-31
 
@@ -182,7 +231,9 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 - Initial public release of the Three.js Gaussian Splatting renderer.
 
-[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.15...HEAD
+[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.16...v1.0.0
+[0.1.16]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.15...v0.1.16
 [0.1.15]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.14...v0.1.15
 [0.1.14]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.13...v0.1.14
 [0.1.13]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v0.1.12...v0.1.13

package/CONTRIBUTING.md

@@ -1,62 +1,52 @@
 # Contributing
 
-Thanks for contributing to `gaussian-splat-lite`.
-
 ## Development setup
 
-Building the WebAssembly module requires Node.js 20.9 or newer, a Rust
-toolchain installed through `rustup`, and the `wasm32-unknown-unknown` target.
+Requires Node.js 20.9+, Rust via `rustup`, and the `wasm32-unknown-unknown` target.
 
 ```bash
 npm ci
 npm run build:wasm
+npm run dev
 ```
 
-Start the local viewer with `npm run dev`.
+Check WebGL2, WebGPU, and WebGPU · WebGL2 in the viewer. For depth changes, compare mesh occlusion and transparent edges; disable **Automatic stochastic** to expose **Force Splat depth**.
+
+See [Source architecture](docs/Architecture.md) for module responsibilities and backend boundaries.
 
 ## Validation
 
-Run the complete release check before opening a pull request:
+Before opening a pull request:
 
 ```bash
 npm run release:check
 ```
 
-This builds the WebAssembly module and example site, type-checks and lints the
-source, runs the tests, builds the package, and verifies the npm tarball.
+Builds WASM, the viewer, and the package; runs type checks, lint, tests, and npm package validation.
 
-When dependency updates introduce or change install scripts, review them and
-update the pinned `allowScripts` entries with `npm approve-scripts`.
+Review new or changed dependency install scripts and update `allowScripts` with `npm approve-scripts`.
 
 ## Pull requests
 
 - Keep changes focused on one problem.
-- Update the README and API docs when public behavior changes.
+- Update the relevant API docs when behavior changes; keep the README focused on setup and capabilities.
 - Add or update tests for behavior that can be exercised without WebGL.
-- Include a minimal reproduction and captures for rendering changes when
-  possible.
+- Include a minimal reproduction and captures for rendering changes where possible.
 - Add user-visible changes to the `Unreleased` section of `CHANGELOG.md`.
-- Do not commit generated `dist/`, `site-dist/`, Rust `target/`, or wasm-pack
-  `pkg/` directories.
+- Do not commit generated `dist/`, `site-dist/`, Rust `target/`, or wasm-pack `pkg/` directories.
 
 ## Maintainer releases
 
-The npm package is published by `.github/workflows/publish.yml` when a matching
-`v*` tag is pushed. The workflow rejects tags that do not match the version in
-`package.json`, skips versions already present on npm, and creates the GitHub
-release from `CHANGELOG.md`.
+Pushing a `v*` tag runs `.github/workflows/publish.yml`. It requires a matching `package.json` version, skips existing npm versions, and creates the GitHub release from `CHANGELOG.md`.
 
-Before the first automated release, make the GitHub repository public, then
-publish the package once from a maintainer account so that its npm settings
-exist:
+To publish manually from a maintainer account:
 
 ```bash
 npm run release:check
 npm publish --access public
 ```
 
-Then, using a current npm CLI, configure GitHub Actions as the trusted publisher
-for future releases:
+Configure GitHub Actions as the trusted publisher with a current npm CLI:
 
 ```bash
 npm trust github gaussian-splat-lite \
@@ -65,15 +55,10 @@ npm trust github gaussian-splat-lite \
   --allow-publish
 ```
 
-The same setting is available under the package's npm **Settings → Trusted
-Publisher** page. The workflow uses short-lived OIDC credentials, so no
-`NPM_TOKEN` repository secret is required after this setup.
+Alternatively, use npm **Settings → Trusted Publisher**. The workflow uses OIDC; no `NPM_TOKEN` secret is needed.
 
 For each release:
 
-1. Move the relevant changelog entries from `Unreleased` into a dated version
-   section.
-2. Update `package.json` and `package-lock.json` with
-   `npm version <version> --no-git-tag-version`.
-3. Run `npm run release:check`, commit the release changes, then create and push
-   `v<version>`.
+1. Move `Unreleased` entries into a dated version section.
+2. Run `npm version <version> --no-git-tag-version` to update both package files.
+3. Run `npm run release:check`, commit, then create and push `v<version>`.

package/NOTICE

@@ -5,6 +5,10 @@ This product includes software derived from SparkJS v2.1.0,
 Copyright © 2025 WORLD LABS TECHNOLOGIES, INC., licensed under the MIT
 License. See THIRD_PARTY_LICENSES.md for the complete license notice.
 
+This product includes software adapted from SuperSplat 3.0.0-alpha,
+Copyright (c) 2011-2026 PlayCanvas Ltd., licensed under the MIT License.
+See THIRD_PARTY_LICENSES.md for the complete license notice.
+
 This product includes ruzstd v0.7.3,
 Copyright © 2019 Moritz Borcherding, licensed under the MIT License.
 See THIRD_PARTY_LICENSES.md for the complete license notice.

package/README.md

@@ -6,34 +6,26 @@
 [![CI](https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/actions/workflows/ci.yml/badge.svg)](https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
+**Three.js Gaussian Splatting · WebGPU · Depth Rendering · Streaming**
+
 <p align="center">
   <img src="./Gaussian-Splat-Lite.svg" alt="Gaussian Splat Lite" width="1000">
 </p>
 
 </div>
 
-`Gaussian-Splat-Lite` is a lightweight 3D Gaussian Splatting renderer for Three.js. It is based on the overall architecture of [SparkJS](https://github.com/sparkjsdev/spark), simplified and adapted to retain a stable, general-purpose Gaussian Splat rendering pipeline while removing LoD, paging, dynamic shader graphs, and broad format compatibility layers. It also fixes SparkJS precision issues with large GIS/ECEF world coordinates and provides faster depth sorting and raycasting implementations.
-
-It works alongside standard Three.js scenes, cameras, meshes, and render loops, and supports unified generation, sorting, and blended rendering of multiple Splat objects.
+A lightweight 3D Gaussian Splatting renderer for **Three.js**, with **WebGPU/WebGL2**, **depth rendering for scene occlusion**, and **large-scene streaming**. Load PLY/SPZ/SOG/RAD files into standard Three.js scenes, stream RAD and SOG scenes with camera-driven LOD, and render multiple Splat objects together.
 
 ## Features
 
-- Native integration with the Three.js scene graph and rendering pipeline
-- Multiple `SplatMesh` objects rendered with correct global sorting
-- `.ply` and `.spz` file support
-- URL, in-memory byte, and standard `ReadableStream` inputs
-- Rust/WebAssembly file decoding, depth sorting, and raycasting
-- 3DGS rendering with configurable anti-aliasing
-- Spherical harmonics, offscreen rendering, and environment-map rendering
-- SDF-based color and opacity editing
-- Camera-relative rendering for large GIS/ECEF world coordinates
-- TypeScript declarations, ESM, and CommonJS builds
-
-## Requirements
-
-- A modern browser with WebGL2, WebAssembly, Web Workers, and ES modules
-- Three.js `0.185.1` or newer
-- Correct CORS headers when loading Splat files from another origin
+| Focus | What you get |
+| --- | --- |
+| **WebGPU / WebGL2** | Shared Three.js scene API with GPU sorting on native WebGPU and asynchronous Worker/WASM sorting on both WebGL2 backends |
+| **Depth Rendering** | Separate unsorted depth draw with stochastic coverage at transparent edges |
+| **Large-scene streaming** | RAD tree LOD and SOG `lod-meta.json` scenes with camera-driven selection, on-demand loading, worker decoding, caching, and opacity crossfades for smooth LOD changes on both backends |
+| **Stochastic rendering** | Sorting-free rendering for responsive camera movement, with optional spatial resolve to reduce noise |
+| **SDF edits** | Region-based color and opacity editing without moving Splats |
+| **Data and precision** | PLY/SPZ/SOG/RAD from URLs, files, or bytes; camera-relative rendering for large GIS/ECEF coordinates |
 
 ## Installation
 
@@ -41,44 +33,42 @@ It works alongside standard Three.js scenes, cameras, meshes, and render loops,
 npm install gaussian-splat-lite three
 ```
 
+Requires Three.js `>=0.186.0`.
+
 ## Quick start
 
+`SplatMesh` is a scene object. One `GaussianSplatRenderer` handles generation, sorting, and drawing for all visible Splat objects.
+
+### WebGPU
+
 ```js
 import * as THREE from "three";
+import { WebGPURenderer } from "three/webgpu";
 import { GaussianSplatRenderer, SplatMesh } from "gaussian-splat-lite";
 
+const renderer = new WebGPURenderer({ antialias: false });
+await renderer.init(); // Initialize before constructing GaussianSplatRenderer.
+renderer.setPixelRatio(window.devicePixelRatio);
+renderer.setSize(window.innerWidth, window.innerHeight);
+document.body.appendChild(renderer.domElement);
+
 const scene = new THREE.Scene();
 const camera = new THREE.PerspectiveCamera(
-  60,
-  window.innerWidth / window.innerHeight,
-  0.1,
-  1000,
+  60, window.innerWidth / window.innerHeight, 0.1, 1000,
 );
 camera.position.set(0, 0, 3);
 
-const renderer = new THREE.WebGLRenderer({
-  antialias: false,
-  powerPreference: "high-performance",
+const splatRenderer = new GaussianSplatRenderer({
+  renderer,
+  renderDepth: true, // Add Splat depth after the sorted color draw.
 });
-renderer.setPixelRatio(window.devicePixelRatio);
-renderer.setSize(window.innerWidth, window.innerHeight);
-document.body.appendChild(renderer.domElement);
-
-// One GaussianSplatRenderer is normally enough for each Three.js renderer.
-const splatRenderer = new GaussianSplatRenderer({ renderer });
 scene.add(splatRenderer);
 
 const splat = new SplatMesh({ url: "/assets/scene.spz" });
 scene.add(splat);
-
-// Wait before reading loaded data such as the count or bounding box.
 await splat.initialized;
-console.log(`Loaded ${splat.numSplats} splats`);
-
-renderer.setAnimationLoop(() => {
-  renderer.render(scene, camera);
-});
 
+renderer.setAnimationLoop(() => renderer.render(scene, camera));
 window.addEventListener("resize", () => {
   camera.aspect = window.innerWidth / window.innerHeight;
   camera.updateProjectionMatrix();
@@ -86,206 +76,114 @@ window.addEventListener("resize", () => {
 });
 ```
 
-`GaussianSplatRenderer` is itself a Three.js scene object. It collects visible `SplatMesh` objects, generates GPU data, sorts the combined collection, and draws it. Application code continues to use the standard `renderer.render(scene, camera)` call; it does not need to issue a separate draw call for each Splat.
+### WebGL2
 
-Some PLY/SPZ data uses a `+Y`-down, `+Z`-forward convention. If a model appears upside down or faces the wrong direction, rotate the object without changing its decoded data:
+`WebGPURenderer` automatically falls back to its WebGL2 backend when WebGPU is unavailable. To force this backend while keeping TSL materials:
 
 ```js
-splat.quaternion.set(1, 0, 0, 0); // Rotate 180 degrees around X.
+const renderer = new WebGPURenderer({ antialias: false, forceWebGL: true });
+await renderer.init();
 ```
 
-## Loading data
-
-### From a URL
+For the classic WebGL renderer, replace the WebGPU renderer creation and initialization with:
 
 ```js
-const splat = new SplatMesh({
-  url: "/assets/model.ply", // .spz is also supported.
-  onProgress: (event) => {
-    if (event.lengthComputable) {
-      console.log(`${Math.round((event.loaded / event.total) * 100)}%`);
-    }
-  },
-  onLoad: (mesh) => console.log(mesh.numSplats),
-});
-
-scene.add(splat);
-await splat.initialized;
+const renderer = new THREE.WebGLRenderer({ antialias: false });
 ```
 
-### From a File or ReadableStream
+Keep the rest of the example, including `renderDepth`.
 
-This form is suitable for file pickers, drag and drop, and large local files. The data is decoded locally by WebAssembly and is not automatically uploaded anywhere.
+## Streaming large scenes
 
-```js
-import { SplatFileType, SplatMesh } from "gaussian-splat-lite";
-
-const file = fileInput.files[0];
-const fileType = file.name.toLowerCase().endsWith(".spz")
-  ? SplatFileType.SPZ
-  : SplatFileType.PLY;
-
-const splat = new SplatMesh({
-  fileName: file.name,
-  fileType,
-  stream: file.stream(),
-  streamLength: file.size,
-  onProgress: ({ loaded, total }) => console.log(loaded, total),
-});
+Use `RadStreamScheduler` for RAD files with a LOD tree, or `SogStreamScheduler` for SOG scenes indexed by `lod-meta.json`. Both work with the same `GaussianSplatRenderer` on WebGPU and WebGL2, loading and retaining data as the camera moves.
 
-scene.add(splat);
-await splat.initialized;
-```
-
-Complete in-memory file data can also be supplied:
+For RAD, replace the `SplatMesh` loading and animation loop in the quick start with:
 
 ```js
-const bytes = new Uint8Array(await file.arrayBuffer());
-const splat = new SplatMesh({
-  fileBytes: bytes,
-  fileType: SplatFileType.SPZ,
-});
-```
+import { RadStreamScheduler } from "gaussian-splat-lite";
 
-**`Experimental`** Decoded values can be transformed in the worker with a
-serializable, per-Splat expression. The library continues to own packed arrays
-and encoding:
+const streaming = new RadStreamScheduler({
+  url: "/assets/scene.rad",
+  splatBudget: 3_000_000,
+  fadeDurationMs: 200, // Smooth LOD transitions (default).
+});
+scene.add(streaming.group);
+await streaming.initialized;
 
-```js
-import { postDecode } from "gaussian-splat-lite";
+const size = new THREE.Vector2();
+renderer.setAnimationLoop(() => {
+  renderer.getDrawingBufferSize(size);
+  streaming.update(camera, { width: size.x, height: size.y });
+  renderer.render(scene, camera);
+});
 
-const transform = postDecode.define(({ splat, op }) => ({
-  position: op.add(splat.position, [1, 0, 0]),
-  color: op.mul(splat.color, [1, 0.8, 0.8]),
-}));
+// The update loop must be running before awaiting the first visible data.
+await streaming.firstRenderable;
 
-const splat = new SplatMesh({ fileBytes: bytes, postDecode: transform });
+// When removing the model:
+// streaming.dispose();
+// streaming.group.removeFromParent();
 ```
 
-See [`postDecode`](docs/PostDecode.md) for external attributes, opacity,
-quaternions, scale, and spherical harmonics.
-
-When the input URL does not have a recognizable extension, specify `fileType` explicitly or provide a `.ply` / `.spz` name through `fileName`.
-
-### Creating Splats in code
+For streamed SOG, use this constructor and call `streaming.update(camera)` before rendering each frame; the group and readiness lifecycle are the same:
 
 ```js
-import * as THREE from "three";
-import { SplatMesh } from "gaussian-splat-lite";
-
-const splat = new SplatMesh({
-  maxSplats: 100,
-  constructSplats: (data) => {
-    data.pushSplats([{
-      center: new THREE.Vector3(0, 0, 0),
-      scales: new THREE.Vector3(0.2, 0.1, 0.1),
-      quaternion: new THREE.Quaternion(),
-      opacity: 1, // Raw opacity; 0..1 alpha, >1 LoD coverage (max 1000).
-      color: new THREE.Color(0x4f8cff),
-      sh: [], // Optional: 0, 3, 8, or 15 coefficients for SH0/1/2/3.
-    }]);
-  },
-});
-
-scene.add(splat);
-await splat.initialized;
-```
-
-## Core concepts and public API
-
-| API | Purpose |
-| --- | --- |
-| [`GaussianSplatRenderer`](docs/GaussianSplatRenderer.md) | Integrates with Three.js and generates, sorts, and draws every visible Splat |
-| [`SplatMesh`](docs/SplatMesh.md) | A transformable, visible, and raycastable Gaussian Splat scene object |
-| [`SplatLoader`](docs/SplatLoader.md) | A Three.js Loader-style PLY/SPZ decoder |
-| [`Splats`](docs/Splats.md) | The built-in mutable Splat source, with decoded reads and aligned batch mutation |
-| [`SplatEdit`](docs/SplatEdit.md) / [`SplatEditSdf`](docs/SplatEdit.md) | SDF-region RGBA editing objects |
-| [`SplatAccumulator`](docs/SplatAccumulator.md) | A low-level generation buffer used by the renderer; normally internal |
-| [`SplatFileType`](docs/SplatFileType.md) | File type enum containing `PLY` and `SPZ` |
-| [`postDecode`](docs/PostDecode.md) | **`Experimental`** Serializable per-Splat expressions executed inside the decode worker |
-
-## Large world coordinates / GIS / ECEF
-
-The renderer keeps large translations separate from float32 local coordinates. Rendering subtracts the camera origin while values are still JavaScript double-precision numbers, and sorting stores one float64 world origin per `SplatMesh` alongside its float32 local centers. This happens automatically and does not move scene objects or change the world-coordinate behavior of `SplatMesh`, Raycaster, or SDF edits.
-
-Source Splat centers should still remain local to their mesh wherever possible. Precision already lost by storing absolute ECEF coordinates in a float32 source cannot be recovered during rendering.
-
-## Manual updates and animation
+import { SogStreamScheduler } from "gaussian-splat-lite";
 
-By default, the renderer automatically detects object-count, transform, appearance, and camera changes. Use `onFrame` for per-frame animation:
-
-```js
-const splat = new SplatMesh({
-  url: "/assets/model.spz",
-  onFrame: ({ mesh, time }) => {
-    mesh.rotation.y = time * 0.2;
-  },
+const streaming = new SogStreamScheduler({
+  url: "/assets/scene/lod-meta.json",
+  splatBudget: 3_000_000,
+  fadeDurationMs: 200, // Smooth LOD transitions (default).
 });
 ```
 
-When automatic updates are disabled, call `update()` after the scene or camera changes:
+## Depth Rendering
 
-```js
-const splatRenderer = new GaussianSplatRenderer({
-  renderer,
-  autoUpdate: false,
-});
-
-await splatRenderer.update({ scene, camera });
-renderer.render(scene, camera);
-```
+**`renderDepth` adds a dedicated depth draw while keeping sorted color blending.** Both WebGPU and WebGL2 support it.
 
-## Offscreen rendering
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `renderDepth` | `false` | Adds Splat depth for geometry drawn later, including transparent meshes |
+| `stochastic` | `false` | Forces sorting-free stochastic rendering with direct depth writes |
+| `autoStochastic` | `false` | Uses stochastic rendering during motion and enables companion depth on sorted frames |
 
-```js
-const captureRenderer = new GaussianSplatRenderer({
-  renderer,
-  target: {
-    width: 1920,
-    height: 1080,
-    superXY: 2,
-  },
-});
-scene.add(captureRenderer);
+With default depth settings, the companion draw uses unsorted Splats on non-stochastic frames and samples alpha coverage so transparent edges do not become solid. Stochastic frames already write their own depth.
 
-await captureRenderer.update({ scene, camera });
-const rgba = await captureRenderer.renderReadTarget({ scene, camera });
-// rgba is a 1920 * 1080 * 4 Uint8Array.
-```
+## Documentation
 
-If the same scene also contains a `GaussianSplatRenderer` used for canvas display, control the instances with `layers` or `visible` as appropriate so that both are not rendered as ordinary scene objects during the same pass.
+- [GaussianSplatRenderer](docs/GaussianSplatRenderer.md) — Rendering, sorting, depth, resolve, and XR.
+- [SplatMesh](docs/SplatMesh.md) — Loading, transforms, animation, and raycasting.
+- [SplatLoader](docs/SplatLoader.md) — File loading.
+- [RadStreamScheduler](docs/RadStreamScheduler.md) — Spark RAD decoding, tree LOD and on-demand paging.
+- [SogStreamScheduler](docs/SogStreamScheduler.md) — Streamed SOG, camera-driven LOD and caching.
+- [Splats](docs/Splats.md) — Data access and updates.
+- [SplatFileType](docs/SplatFileType.md) — PLY/SPZ/SOG/RAD formats.
+- [SplatEdit / SplatEditSdf](docs/SplatEdit.md) — Color and opacity editing.
+- [postDecode](docs/PostDecode.md) — Per-Splat transformations during decoding.
+- [SplatAccumulator](docs/SplatAccumulator.md) — Low-level GPU buffers.
 
 ## Development
 
-Building from source requires Node.js 20.9 or newer, a Rust toolchain installed through `rustup`, and the `wasm32-unknown-unknown` target. `build:wasm` installs `wasm-pack` through Cargo when it is not already available.
+Requires Node.js 20.9+, Rust via `rustup`, and the `wasm32-unknown-unknown` target. `build:wasm` installs `wasm-pack` through Cargo if needed.
 
 ```sh
-npm install
+npm ci
 npm run build:wasm
-npm run build
-npm test
+npm run dev
 ```
 
-Start the local PLY/SPZ viewer with:
+Open the URL printed by Vite (normally `http://localhost:8080/`) and drop a `.ply`, `.spz`, `.sog`, or `.rad` file into the viewer, choose a local file, or load one from an HTTP(S) URL. For split SOG, select or drop `meta.json` together with its `.webp` images; for split RAD, include the header and its `.radc` pages. Files are decoded locally. Choose **WebGL2 / WebGPU / WebGPU · WebGL2** in the viewer to compare backends; disable automatic stochastic mode to expose the **Force Splat depth** control.
 
-```sh
-npm run dev
-```
+The viewer enables `reversedDepthBuffer` for depth precision on WebGPU and both WebGL2 backends. WebGL2 uses it when `EXT_clip_control` is available.
 
-Open the local URL printed by Vite, normally `http://localhost:8080/`. Drag a `.ply` or `.spz` file onto the viewer, or use its file picker. Files are decoded locally and are not uploaded.
+For streaming, load a RAD file or enter a SOG `lod-meta.json` URL. The viewer streams RAD files with a LOD tree automatically and falls back to ordinary loading when no tree is present. Move the camera to see LOD selection and on-demand loading.
 
-Other useful commands:
+See [Contributing](CONTRIBUTING.md#validation) for validation and release commands. `npm run build` emits ESM, CommonJS, TypeScript declarations, and source maps in `dist/`.
 
-```sh
-npm run build:watch
-npm run check
-npm run lint
-npm run format
-npm run release:check
-```
+## Acknowledgements
 
-The package build emits ESM and CommonJS bundles in `dist/`, together with TypeScript declarations and source maps.
+The overall architecture of Gaussian Splat Lite draws on [Spark](https://github.com/sparkjsdev/spark) and [SuperSplat](https://github.com/playcanvas/supersplat).
 
 ## License
 
-Gaussian Splat Lite is licensed under the [Apache License 2.0](LICENSE). Required attribution notices are provided in [NOTICE](NOTICE), and bundled third-party licenses are listed in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
+Licensed under [Apache 2.0](LICENSE). See [NOTICE](NOTICE) and [third-party licenses](THIRD_PARTY_LICENSES.md) for attribution.

package/THIRD_PARTY_LICENSES.md

@@ -26,6 +26,32 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
+## SuperSplat 3.0.0-alpha
+
+Gaussian Splat Lite includes software adapted from SuperSplat 3.0.0-alpha.
+
+MIT License
+
+Copyright (c) 2011-2026 PlayCanvas Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
 ## ruzstd 0.7.3
 
 Gaussian Splat Lite includes ruzstd 0.7.3 in its WebAssembly build.
@@ -51,3 +77,36 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+## SOG decoding dependencies
+
+The WebAssembly build includes image-webp 0.2.4, png 0.17.16,
+serde/serde_core 1.0.229, and serde_json 1.0.151 under the MIT license.
+
+png: Copyright (c) 2015 nwin
+
+MIT License
+
+Permission is hereby granted, free of charge, to any
+person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the
+Software without restriction, including without
+limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions
+of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
+TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
+PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
+SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.