gaussian-splat-lite 0.1.16 → 1.0.1

package/CHANGELOG.md

@@ -7,6 +7,83 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-09-11
+
+### Added
+
+- Added runtime `splatBudget` updates to `RadStreamScheduler` and `SogStreamScheduler`. Assigning a positive safe integer requests a new LOD selection even for stationary views, discards results computed for an older budget, and preserves displayed coverage through loading and fades.
+
+### Changed
+
+- Changed streamed SOG LOD selection to distance-based priorities with a level multiplier of 1.5, using camera-to-bounds distance instead of region size or authored errors.
+- Changed streamed SOG refinement to use the finest cached LOD up to the target. Gaps of at least four levels load a midpoint; smaller gaps and coarsening load the target directly. Regions without usable coverage start at the coarsest LOD.
+- Reworked RAD LOD scoring to prepare camera position and projection bounds once per view, using camera pixel scale and inverse object-space center distance for perspective and orthographic cameras. Nodes inside the actual viewport receive full priority, accounting for zoom and view offsets; off-screen priority tapers toward 5%, with 5% retained behind the camera. Non-invertible transforms are rejected.
+- Changed RAD LOD radius estimates from the largest axis scale to the arithmetic mean of the three axis scales, lowered the base pixel threshold from `2` to `1`, and reduced hysteresis from 15% to 5%.
+- Reduced RAD traversal work by marking child ranges per page, skipping per-node work on leaf-only pages, and pruning refinements that cannot fit the remaining budget while preserving single-child refinements and stable source order.
+- Kept RAD selection baselines in the LOD worker and referenced them by ID, avoiding per-request copies of the displayed cut. Combined changed-page detection and fade preparation into one pass, skipped fade-buffer allocation for unchanged cuts, and included retained worker selections in resident-byte statistics.
+- Moved streamed RAD page downloads and local page reads into decoding workers, keeping application URL and file resolution on the calling thread. Preserved Range validation and checked resource versions and lengths across parallel responses before publication; local inputs send only the requested page.
+- Reduced RAD streaming replies to packed render records and a scalar root radius, transferring tree arrays to the LOD worker without duplicate copies or unused sort centers on the main thread. Updated pending-byte estimates and removed the unreachable non-LOD radius fallback.
+- Simplified internal RAD selection clearing and removed unused duplicate-index fade handling, keeping prepared selection commits and shared fade groups.
+- Unified RAD/SOG load lifecycle handling in `StreamWorkerPool`, including worker leases, task IDs, cancellation, download accounting, and balanced `LoadingManager` notifications, while retaining separate pools and format-specific cache ownership.
+- Reduced SOG streaming transfers and pending-copy reservations with tightly packed region records that omit per-region texture padding and duplicate sort centers.
+- Reduced streamed SOG metadata to four fields per LOD, keeping the spatial tree and a float32 upgrade-ratio table in the LOD worker. Memory statistics include both threads' retained arrays.
+- Shared ordering texture allocation, resizing and disposal between the WebGL backends while preserving their partial-upload paths; removed unused native WebGPU CPU-ordering members.
+- Optimized `postDecode` by combining single-use multiply/add and add/multiply expressions while preserving intermediate float32 rounding and operand order, caching decoded scale values on demand, and combining related packed-field and sort-center writes.
+- Compacted native WebGPU projection output into visible slots and repurposed the source-index buffer for stable coverage seeds, preserving the 32-byte projected record layout without an extra seed texture.
+- Kept RAD validation and assembly helpers and TSL texture-layout constants local to their modules by removing unused exports.
+- Set viewer camera damping to `0.1`.
+
+### Removed
+
+- Removed unused `SplatEdits.sdfFloatData` and `editFloatData` fields. Float views can be created from the current `sdfData.buffer` and `editData.buffer` when needed.
+- Removed the unused `debugFlag` uniform and its automatic updates. Custom shaders that use it must now define and update their own uniform.
+- Removed `utils.threeMrtArray`; all supported Three.js versions provide array-based multiple render targets.
+- Removed the unused `mode` tag from the internal serialized `postDecode` condition format.
+
+### Fixed
+
+- Stabilized stochastic color and depth coverage when streamed LOD selections or combined mesh ranges are remapped. All three rendering backends now derive sampling seeds from mesh identity and physical source records, preventing unchanged Splats from receiving new noise patterns after remapping.
+- Removed camera-rotation-dependent scale inflation from RAD LOD scoring.
+- Corrected viewer overlay stacking so the drop overlay and toast messages appear above other controls.
+
+## [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
@@ -43,7 +120,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
 
@@ -193,7 +270,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.16...HEAD
+[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.0.1...HEAD
+[1.0.1]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.0.0...v1.0.1
+[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

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.
+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,110 @@ 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, or `SogStreamScheduler` for SOG scenes. 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
-```
-
-Start the local PLY/SPZ viewer with:
-
-```sh
 npm run dev
 ```
 
-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.
+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.
 
-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.