gaussian-splat-lite 1.3.1 → 1.4.0

package/CHANGELOG.md

@@ -7,6 +7,33 @@ and this project follows [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.4.0] - 2026-10-21
+
+### Added
+
+- Added `gsl-build-lod` to convert PLY and SPZ models into streamable RAD files with LOD, without compilation. Supports batch conversion, split files, up to SH3, and configurable memory and temporary storage. See [Building RAD files](docs/BuildRad.md).
+
+### Changed
+
+- RAD files and gzip-compressed SPZ files (v1–v3) decode about 10% faster.
+
+### Fixed
+
+- Fixed incorrect orientation and unstable widths of thin Splats on WebGL, WebGPU, and the WebGL2 fallback.
+
+## [1.3.2] - 2026-10-18
+
+### Added
+
+- Added SH4 decoding for PLY and SPZ and rendering on WebGL, WebGPU, and the WebGL2 fallback. `Splats.getSplat()` and `postDecode` now expose all 24 view-dependent RGB coefficients.
+- Added a Max SH control to the viewer, from SH0 to SH4. Changes apply immediately to regular and streamed models; the default uses all available coefficients.
+
+### Changed
+
+- Renamed the `SplatExtra` fields `sh1`, `sh2`, `sh3a`, `sh3b`, `sh4a`, and `sh4b` to `shBlock0`–`shBlock5`, respectively. Update direct field access to use the new names.
+- `SplatMesh.maxSh` now defaults to `4`, so SH4 models render their full view-dependent color. Set it to `3` to limit rendering to the previous maximum degree.
+- SH4 SPZ models now use more memory because their full view-dependent color data is retained. `SplatMesh.maxSh` only limits rendering detail and does not reduce memory use.
+
 ## [1.3.1] - 2026-10-17
 
 ### Added
@@ -608,7 +635,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/v1.3.1...HEAD
+[Unreleased]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.3.2...v1.4.0
+[1.3.2]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.2.2...v1.3.0
 [1.2.2]: https://github.com/WilliamLiu-1997/Gaussian-Splat-Lite/compare/v1.2.1...v1.2.2

package/CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 ## Development setup
 
-Requires Node.js 20.19+ or 22.12+, Rust via `rustup`, and the `wasm32-unknown-unknown` target.
+Requires Node.js 20.19+ or 22.12+ and Rust via `rustup`. `npm run build:wasm` installs the `wasm32-unknown-unknown` target if needed.
 
 ```bash
 npm ci
@@ -14,6 +14,18 @@ Check WebGPU, WebGL2, and WebGPU · WebGL2 in the viewer. For rendering changes,
 
 Implementations and build scripts use JavaScript. Keep TypeScript declarations in adjacent `.d.ts` files and update them whenever the corresponding API changes. `src/index.js` and `src/index.d.ts` define the package's runtime and type exports.
 
+### RAD command-line tool
+
+See [Building RAD files](docs/BuildRad.md) for installation, conversion commands, and options.
+
+Before running the CLI from a checkout, and after changing the decoder, its dependencies, or its build settings, rebuild the decoder:
+
+```bash
+npm run build:wasm:lod
+```
+
+`npm run build:wasm` also builds the CLI decoder. The generated `bin/decoder/` files are ignored by Git and included in the npm package, so npm users can run the command without compiling anything. The release workflow builds them before packaging.
+
 ## Validation
 
 Before opening a pull request:
@@ -35,4 +47,4 @@ Review new or changed dependency install scripts and update `allowScripts` with
 - Add or update tests for behavior that can be exercised without WebGL.
 - Include a small reproduction and before/after images for rendering changes where possible.
 - Add user-visible changes to the `Unreleased` section of `CHANGELOG.md`; leave published version sections unchanged.
-- Do not commit generated `dist/`, `site-dist/`, Rust `target/`, or wasm-pack `pkg/` directories.
+- Do not commit generated `dist/`, `site-dist/`, `bin/decoder/`, Rust `target/`, or wasm-pack `pkg/` directories.

package/NOTICE

@@ -1,14 +1,22 @@
 Gaussian Splat Lite
 Copyright 2026 William Liu <lyz15972107087@gmail.com>
 
-This product includes software derived from SparkJS v2.1.0,
+This product includes software derived from SparkJS,
 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,
+This product includes software adapted from SuperSplat,
 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,
+This product includes ruzstd,
 Copyright © 2019 Moritz Borcherding, licensed under the MIT License.
 See THIRD_PARTY_LICENSES.md for the complete license notice.
+
+This product includes flate2,
+Copyright (c) 2014-2026 Alex Crichton, licensed under the MIT License.
+See THIRD_PARTY_LICENSES.md for the complete license notice.
+
+This product includes zlib-rs,
+(C) 2024 Trifecta Tech Foundation, licensed under the zlib License.
+See THIRD_PARTY_LICENSES.md for the complete license notice.

package/README.md

@@ -175,6 +175,7 @@ const streaming = new SogStreamScheduler({
 
 **Large scenes**
 
+- [Building RAD files](docs/BuildRad.md) — Convert models to streamable RAD with quality LOD.
 - [RadStreamScheduler](docs/RadStreamScheduler.md) — Large RAD scenes with adaptive detail.
 - [SogStreamScheduler](docs/SogStreamScheduler.md) — Large SOG scenes with adaptive detail.
 
@@ -194,7 +195,7 @@ See [Contributing](CONTRIBUTING.md#validation) for validation commands. `npm run
 
 ## Acknowledgements
 
-The overall architecture of Gaussian Splat Lite draws on [Spark](https://github.com/sparkjsdev/spark) and [SuperSplat](https://github.com/playcanvas/supersplat).
+Gaussian Splat Lite uses [Spark](https://github.com/sparkjsdev/spark) and [SuperSplat](https://github.com/playcanvas/supersplat) as reference implementations.
 
 Example model adapted from [shehabmekky](https://superspl.at/scene/c1e6297e) ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)).
 

package/THIRD_PARTY_LICENSES.md

@@ -1,8 +1,8 @@
 # Third-party licenses
 
-## SparkJS v2.1.0
+## SparkJS
 
-Gaussian Splat Lite includes software derived from SparkJS v2.1.0.
+Gaussian Splat Lite includes code derived from SparkJS.
 
 The MIT License
 
@@ -26,9 +26,9 @@ 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
+## SuperSplat
 
-Gaussian Splat Lite includes software adapted from SuperSplat 3.0.0-alpha.
+Gaussian Splat Lite includes software adapted from SuperSplat.
 
 MIT License
 
@@ -52,9 +52,9 @@ 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.9.0
+## ruzstd
 
-Gaussian Splat Lite includes ruzstd 0.9.0 in its WebAssembly build.
+Gaussian Splat Lite includes ruzstd in its WebAssembly build.
 
 MIT License
 
@@ -110,3 +110,61 @@ 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.
+
+## flate2
+
+Gaussian Splat Lite includes flate2 in its WebAssembly build.
+
+MIT License
+
+Copyright (c) 2014-2026 Alex Crichton
+
+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.
+
+## zlib-rs
+
+Gaussian Splat Lite includes zlib-rs in its WebAssembly build.
+
+zlib License
+
+(C) 2024 Trifecta Tech Foundation
+
+This software is provided 'as-is', without any express or implied
+warranty. In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+
+3. This notice may not be removed or altered from any source distribution.

package/bin/build-lod.js

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import {
+  Worker,
+  isMainThread,
+  parentPort,
+  workerData,
+} from "node:worker_threads";
+import { readInput } from "./rad/input.js";
+import { buildLod } from "./rad/lod.js";
+import { Pool } from "./rad/parallel.js";
+import { checkOutput, writeRad } from "./rad/rad.js";
+import { GIB, Workspace } from "./rad/storage.js";
+
+const help = `Convert PLY or SPZ files to RAD with levels of detail (LOD).
+
+Usage: gsl-build-lod <input> [more inputs...] [options]
+       npm run build-lod -- <input> [more inputs...] [options]
+
+Inputs: PLY, SPZ.
+Output: <input-stem>-lod.rad. Existing files are not overwritten.
+
+Options:
+  --lod-base <base>      LOD spacing (default: 1.75, range: 1.1..16)
+  --max-sh <0..3>        Maximum SH degree (default: 3)
+  --rad-chunked          Write a .rad header and separate .radc files
+  --memory-budget <GiB>  Target memory in GiB (default: 4, minimum: 1)
+  --temp-dir <path>      Temporary file location (default: system temp)
+  -o, --output <path>    Output .rad path (one input only)
+  -h, --help             Show this help
+
+SH4 inputs are accepted; coefficients above --max-sh are discarded.
+The memory target covers the whole conversion, worker threads included.
+No compilation is required.`;
+
+function parse(args) {
+  const options = {
+    inputs: [],
+    lodBase: 1.75,
+    maxSh: 3,
+    budget: 4 * GIB,
+    chunked: false,
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--help" || arg === "-h") return;
+    if (arg === "--") {
+      options.inputs.push(...args.slice(i + 1));
+      break;
+    }
+    if (arg === "--rad-chunked") {
+      options.chunked = true;
+      continue;
+    }
+    if (!arg.startsWith("-")) {
+      options.inputs.push(arg);
+      continue;
+    }
+    const equal = arg.indexOf("=");
+    const name = equal < 0 ? arg : arg.slice(0, equal);
+    const key = {
+      "--lod-base": "lodBase",
+      "--max-sh": "maxSh",
+      "--memory-budget": "budget",
+      "--temp-dir": "tempDir",
+      "-o": "output",
+      "--output": "output",
+    }[name];
+    if (!key) throw new Error(`Unknown option: ${arg}`);
+    const value = equal < 0 ? args[++i] : arg.slice(equal + 1);
+    if (!value) throw new Error(`${name} requires a value`);
+    options[key] = ["lodBase", "maxSh", "budget"].includes(key)
+      ? Number(value) * (key === "budget" ? GIB : 1)
+      : value;
+  }
+  if (
+    !Number.isFinite(options.lodBase) ||
+    options.lodBase < 1.1 ||
+    options.lodBase > 16
+  )
+    throw new Error("--lod-base must be between 1.1 and 16");
+  if (
+    !Number.isInteger(options.maxSh) ||
+    options.maxSh < 0 ||
+    options.maxSh > 3
+  )
+    throw new Error("--max-sh must be an integer between 0 and 3");
+  if (
+    !Number.isFinite(options.budget) ||
+    options.budget < GIB ||
+    options.budget > Number.MAX_SAFE_INTEGER
+  )
+    throw new Error(
+      "--memory-budget must be a finite GiB number of at least 1 within the platform limit",
+    );
+  if (!options.inputs.length) throw new Error(help);
+  if (options.output && options.inputs.length !== 1)
+    throw new Error("--output requires exactly one input");
+  return options;
+}
+
+async function convert(input, options, cancelled) {
+  const output =
+    options.output ??
+    path.join(
+      path.dirname(input),
+      `${path.basename(input, path.extname(input))}-lod.rad`,
+    );
+  checkOutput(output, options.chunked);
+  const workspace = new Workspace(options.budget, options.tempDir, cancelled);
+  const start = performance.now();
+  console.log(
+    `${input} -> ${output}\nMemory target: ${(options.budget / GIB).toFixed(3)} GiB`,
+  );
+  // Worker threads for the LOD, closed before writing starts its own.
+  let pool;
+  try {
+    workspace.check();
+    const splats = await readInput(input, options.maxSh, workspace);
+    const count = splats.length;
+    pool = new Pool(workspace, count);
+    splats.retain(pool);
+    console.log(
+      `Read ${count} splats, SH${splats.inputSh}, in ${((performance.now() - start) / 1000).toFixed(2)}s`,
+    );
+    if (splats.inputSh > splats.maxSh)
+      console.log(
+        `Keeping SH0–SH${splats.maxSh}; higher coefficients are discarded for RAD output.`,
+      );
+    if (splats.invalid)
+      console.log(
+        `Removed ${splats.invalid} splats with NaN or infinite values or a zero rotation`,
+      );
+    const empty = count - splats.invalid - splats.length;
+    if (empty) console.log(`Removed ${empty} empty splats`);
+    if (!splats.length) throw new Error("Input contains no usable splats");
+    const leaves = splats.length;
+    const lodStart = performance.now();
+    buildLod(splats, options.lodBase, pool);
+    await pool.close();
+    console.log(
+      `Built ${splats.length} LOD splats from ${leaves} leaves in ${((performance.now() - lodStart) / 1000).toFixed(2)}s`,
+    );
+    const bytes = await writeRad(
+      splats,
+      output,
+      options.chunked,
+      options.lodBase,
+    );
+    console.log(
+      `Wrote ${(bytes / 1048576).toFixed(2)} MiB in ${((performance.now() - start) / 1000).toFixed(2)}s total`,
+    );
+  } finally {
+    await pool?.close();
+    workspace.dispose();
+  }
+}
+
+async function run(options, cancelled) {
+  let failed = 0;
+  for (const input of options.inputs) {
+    if (Atomics.load(cancelled, 0)) return;
+    try {
+      await convert(input, options, cancelled);
+    } catch (error) {
+      if (Atomics.load(cancelled, 0)) return;
+      console.error(`${input}: ${error.message ?? error}`);
+      failed++;
+    }
+  }
+  if (failed) throw new Error(`${failed} conversion(s) failed`);
+}
+
+// Keep signal handling responsive while the conversion runs synchronous code.
+// The worker observes cancellation and unwinds its existing catch/finally blocks.
+async function start(options) {
+  const cancelled = new Int32Array(new SharedArrayBuffer(4));
+  let progressLine = "";
+  const endProgress = () => {
+    if (progressLine) process.stdout.write("\n");
+    progressLine = "";
+  };
+  const print = ({ method, args }) => {
+    if (method === "progress") {
+      const [line, done] = args;
+      if (process.stdout.isTTY) {
+        const width = process.stdout.columns;
+        const text = !done && width ? line.slice(0, width - 1) : line;
+        process.stdout.write(`\r\x1b[2K${text}${done ? "\n" : ""}`);
+        progressLine = done ? "" : text;
+      } else console.log(line);
+    } else {
+      // Insert logs above the live progress instead of leaving a stale row.
+      if (progressLine) process.stdout.write("\r\x1b[2K");
+      console[method](...args);
+      if (progressLine) process.stdout.write(progressLine);
+    }
+  };
+  const interrupt = (signal) => {
+    const code = signal === "SIGINT" ? 130 : 143;
+    if (Atomics.compareExchange(cancelled, 0, 0, code) === 0) {
+      endProgress();
+      console.error(`${signal}: cancelling conversion and cleaning up...`);
+    }
+  };
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", interrupt);
+  try {
+    const code = await new Promise((resolve, reject) => {
+      const worker = new Worker(new URL(import.meta.url), {
+        workerData: { options, cancelled },
+      });
+      worker.on("message", print);
+      worker.once("error", reject);
+      worker.once("exit", resolve);
+    });
+    process.exitCode = Atomics.load(cancelled, 0) || code;
+  } finally {
+    endProgress();
+    process.off("SIGINT", interrupt);
+    process.off("SIGTERM", interrupt);
+  }
+}
+
+try {
+  if (!isMainThread) {
+    // Worker stdout buffers later writes until its event loop yields.
+    // Forward logs directly so synchronous conversion keeps showing progress.
+    for (const method of ["log", "warn", "error"])
+      console[method] = (...args) => parentPort.postMessage({ method, args });
+    await run(workerData.options, workerData.cancelled);
+  } else {
+    const options = parse(process.argv.slice(2));
+    if (!options) console.log(help);
+    else await start(options);
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}