@voluma/vlam 0.1.0 → 0.2.1

package/dist/one-shot-worker-G80btnth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"one-shot-worker-G80btnth.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/orientation.d.ts

@@ -0,0 +1,35 @@
+import * as THREE from 'three/webgpu';
+/**
+ * How a loaded scene is oriented into the three.js Y-up world.
+ *
+ * - `'y-up'` (default): VLAM normalizes every known format to three.js Y-up -
+ *   the OpenCV-frame formats (PLY/`.splat`/`.ksplat`/SOG/`.rad`) are flipped
+ *   180° about X, SPZ is already Y-up, and LCC carries its own Z-up→Y-up matrix.
+ *   "Drop a file and it stands up", matching engine viewers (PlayCanvas, Babylon).
+ * - `'source'`: no cosmetic correction - the scene renders in its data frame,
+ *   matching raw Spark / mkkellogg. A host that manages orientation itself (e.g.
+ *   swapping viewers while keeping one stored per-scene rotation) uses this.
+ *
+ * Note LCC's Z-up→Y-up matrix is *format semantics*, not a cosmetic default: it
+ * is applied in **both** modes (Spark applies it too). Only the 180°-X flip for
+ * the Y-down formats is gated by this option.
+ */
+export type SplatOrientation = 'y-up' | 'source';
+/**
+ * Formats {@link yUpTransformForFormat} understands: the self-contained scene
+ * formats ({@link SplatData.sourceFormat}) plus the streamed ones.
+ */
+export type OrientableFormat = 'ply' | 'splat' | 'ksplat' | 'sog' | 'spz' | 'rad' | 'streamed-sog' | 'lcc' | 'lcc2';
+/**
+ * The 180°-about-X rotation that maps a 3DGS Y-down capture to three.js Y-up -
+ * the same correction Spark documents as `quaternion.set(1, 0, 0, 0)`. Returned
+ * as a fresh {@link THREE.Matrix4} so callers can mutate/decompose it freely.
+ */
+export declare function createYUpTransform(): THREE.Matrix4;
+/**
+ * The `'y-up'` correction for a format, or `null` when nothing is needed:
+ * SPZ is already Y-up, and LCC self-orients via its `formatTransform`
+ * (callers apply that in both modes, so this returns `null` for LCC to avoid
+ * doubling it). Y-down formats (PLY/`.splat`/`.ksplat`/SOG) get the 180°-X flip.
+ */
+export declare function yUpTransformForFormat(format: OrientableFormat | undefined): THREE.Matrix4 | null;

package/dist/ply-header-BwgExCn-.js

@@ -0,0 +1,125 @@
+const c = {
+  float: 4,
+  float32: 4,
+  double: 8,
+  float64: 8,
+  int: 4,
+  int32: 4,
+  uint: 4,
+  uint32: 4,
+  short: 2,
+  int16: 2,
+  ushort: 2,
+  uint16: 2,
+  char: 1,
+  int8: 1,
+  uchar: 1,
+  uint8: 1
+};
+function P(t) {
+  const s = new Uint8Array(t, 0, Math.min(t.byteLength, 65536)), o = new TextDecoder("ascii").decode(s), p = /end_header\r?\n/.exec(o);
+  if (!/^ply\r?\n/.test(o))
+    throw new Error('Not a PLY file (missing "ply" magic).');
+  if (!p)
+    throw new Error(
+      'Unsupported PLY file: no "end_header" within the first 64 KiB - the header exceeds the supported window, or the file is truncated.'
+    );
+  if (!o.includes("format binary_little_endian 1.0"))
+    throw new Error("Unsupported PLY format; expected binary_little_endian 1.0.");
+  const i = [];
+  for (const e of o.slice(0, p.index).split(`
+`)) {
+    const n = e.trim().split(/\s+/);
+    if (n[0] === "element") {
+      const r = n[1], f = Number(n[2]);
+      if (r === void 0) throw new Error(`Malformed PLY element: "${e.trim()}"`);
+      if (!Number.isSafeInteger(f) || f < 0)
+        throw new Error(`Invalid PLY ${r} count: ${n[2]}.`);
+      i.push({
+        name: r,
+        count: f,
+        properties: /* @__PURE__ */ new Map(),
+        propertyNames: [],
+        listProperties: /* @__PURE__ */ new Map(),
+        stride: 0,
+        hasListProperty: !1
+      });
+    } else if (n[0] === "property") {
+      const r = i[i.length - 1];
+      if (!r) throw new Error(`PLY property declared before any element: "${e.trim()}"`);
+      if (n[1] === "list") {
+        const m = n[2] ?? "", w = n[3] ?? "", l = n[4];
+        if (c[m] === void 0 || c[w] === void 0 || l === void 0)
+          throw new Error(`Unsupported PLY property: "${e.trim()}"`);
+        if (r.properties.has(l) || r.listProperties.has(l))
+          throw new Error(`Duplicate PLY property "${l}" in element "${r.name}".`);
+        r.listProperties.set(l, { countType: m, itemType: w }), r.hasListProperty = !0;
+        continue;
+      }
+      const f = n[1] ?? "", y = c[f], d = n[2];
+      if (y === void 0 || d === void 0)
+        throw new Error(`Unsupported PLY property: "${e.trim()}"`);
+      if (r.properties.has(d) || r.listProperties.has(d))
+        throw new Error(`Duplicate PLY property "${d}" in element "${r.name}".`);
+      r.properties.set(d, { type: f, offset: r.stride }), r.propertyNames.push(d), r.stride += y;
+    }
+  }
+  let a = p.index + p[0].length, u = !0;
+  const h = [];
+  for (const e of i)
+    h.push({
+      name: e.name,
+      count: e.count,
+      properties: e.properties,
+      propertyNames: e.propertyNames,
+      listProperties: e.listProperties,
+      stride: e.stride,
+      offset: u ? a : -1,
+      hasListProperty: e.hasListProperty
+    }), e.hasListProperty ? u = !1 : a += e.count * e.stride;
+  return {
+    elements: h,
+    element: (e) => h.find((n) => n.name === e)
+  };
+}
+function $(t, s) {
+  if (t.offset < 0)
+    throw new Error(
+      `Unsupported PLY layout: element "${t.name}" follows a list property, so its position cannot be determined.`
+    );
+  const o = t.offset + t.count * t.stride;
+  if (o > s)
+    throw new Error(
+      `Truncated PLY file: element "${t.name}" needs ${o} bytes but the file is ${s}.`
+    );
+}
+function L(t) {
+  const s = c[t];
+  if (s === void 0) throw new Error(`Unsupported PLY property type: "${t}".`);
+  return s;
+}
+function E(t, s) {
+  const o = t.properties.get(s);
+  if (!o)
+    throw new Error(`PLY element "${t.name}" is missing property "${s}".`);
+  return o.offset;
+}
+function Y(t, s, o, p) {
+  for (const i of s) {
+    const a = t.properties.get(i);
+    if (!a)
+      throw new Error(`${p}: missing property "${i}".`);
+    if (!o.includes(a.type))
+      throw new Error(
+        `Unsupported PLY property type for "${i}": expected ${o.join(" or ")}, got ${a.type}.`
+      );
+  }
+}
+export {
+  Y as a,
+  $ as b,
+  E as c,
+  L as d,
+  P as p
+};
+//# sourceMappingURL=ply-header-BwgExCn-.js.map

package/dist/ply-header-BwgExCn-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ply-header-BwgExCn-.js","sources":["../src/lib/ply-header.ts"],"sourcesContent":["/**\n * Shared PLY header reader.\n *\n * PLY is a container, not a format: the same `.ply` extension carries the\n * uncompressed \"INRIA flavor\" 3DGS export (see `parse-splat-ply.ts`) and\n * SuperSplat/PlayCanvas's compressed flavor (`parse-compressed-ply.ts`).\n * Both need the same thing first - the element list, their property layouts,\n * and where each element's records start - so that lives here.\n */\n\n/** Byte size of each scalar type PLY can declare. */\nconst PROPERTY_SIZES: Record<string, number> = {\n  float: 4,\n  float32: 4,\n  double: 8,\n  float64: 8,\n  int: 4,\n  int32: 4,\n  uint: 4,\n  uint32: 4,\n  short: 2,\n  int16: 2,\n  ushort: 2,\n  uint16: 2,\n  char: 1,\n  int8: 1,\n  uchar: 1,\n  uint8: 1,\n};\n\n/** One scalar property of an element. */\nexport interface PlyProperty {\n  readonly type: string;\n  /** Byte offset within one record of the element. */\n  readonly offset: number;\n}\n\n/**\n * One list property (`property list <countType> <itemType> <name>`), such as a\n * mesh's `face` indices. Only the types are recorded - the data is variable-size\n * and must be walked record by record (see `parse-mesh-ply.ts`).\n */\nexport interface PlyListProperty {\n  /** Type of the per-record item count, e.g. `uchar`. */\n  readonly countType: string;\n  /** Type of each item, e.g. `int`. */\n  readonly itemType: string;\n}\n\n/** One PLY element (`element <name> <count>`) and its record layout. */\nexport interface PlyElement {\n  readonly name: string;\n  readonly count: number;\n  readonly properties: ReadonlyMap<string, PlyProperty>;\n  /** Property names in declaration order. */\n  readonly propertyNames: readonly string[];\n  /** List properties by name; empty unless {@link hasListProperty}. */\n  readonly listProperties: ReadonlyMap<string, PlyListProperty>;\n  /**\n   * Bytes per record - meaningless when {@link hasListProperty}, since a list\n   * makes each record's size depend on its contents.\n   */\n  readonly stride: number;\n  /**\n   * Byte offset of this element's first record within the file, or -1 when a\n   * preceding element has a variable-size record and no arithmetic can find it.\n   */\n  readonly offset: number;\n  /** A list property makes this element's records variable-size. */\n  readonly hasListProperty: boolean;\n}\n\n/** A parsed PLY header. */\nexport interface PlyHeader {\n  readonly elements: readonly PlyElement[];\n  /** The element of that name, or undefined. */\n  element(name: string): PlyElement | undefined;\n}\n\n/**\n * Reads a binary little-endian PLY header and resolves every element's byte\n * offset by walking the elements in declaration order.\n *\n * Whether the declared records actually fit in the buffer is deliberately not\n * checked here - call {@link assertPlyElementFits} once the caller has\n * validated the properties it needs, so a wrong property type is reported as\n * such rather than as the truncation it happens to imply.\n *\n * @throws {Error} if the file is not a binary little-endian PLY, or declares a\n * property type this reader cannot size.\n */\nexport function parsePlyHeader(buffer: ArrayBuffer): PlyHeader {\n  const headerBytes = new Uint8Array(buffer, 0, Math.min(buffer.byteLength, 64 * 1024));\n  const headerText = new TextDecoder('ascii').decode(headerBytes);\n  const endMatch = /end_header\\r?\\n/.exec(headerText);\n  if (!/^ply\\r?\\n/.test(headerText)) {\n    throw new Error('Not a PLY file (missing \"ply\" magic).');\n  }\n  if (!endMatch) {\n    throw new Error(\n      'Unsupported PLY file: no \"end_header\" within the first 64 KiB - the header exceeds the ' +\n        'supported window, or the file is truncated.',\n    );\n  }\n  if (!headerText.includes('format binary_little_endian 1.0')) {\n    throw new Error('Unsupported PLY format; expected binary_little_endian 1.0.');\n  }\n\n  interface Building {\n    name: string;\n    count: number;\n    properties: Map<string, PlyProperty>;\n    propertyNames: string[];\n    listProperties: Map<string, PlyListProperty>;\n    stride: number;\n    hasListProperty: boolean;\n  }\n  const building: Building[] = [];\n\n  for (const line of headerText.slice(0, endMatch.index).split('\\n')) {\n    const tokens = line.trim().split(/\\s+/);\n    if (tokens[0] === 'element') {\n      const name = tokens[1];\n      const count = Number(tokens[2]);\n      if (name === undefined) throw new Error(`Malformed PLY element: \"${line.trim()}\"`);\n      if (!Number.isSafeInteger(count) || count < 0) {\n        throw new Error(`Invalid PLY ${name} count: ${tokens[2]}.`);\n      }\n      building.push({\n        name,\n        count,\n        properties: new Map(),\n        propertyNames: [],\n        listProperties: new Map(),\n        stride: 0,\n        hasListProperty: false,\n      });\n    } else if (tokens[0] === 'property') {\n      const element = building[building.length - 1];\n      if (!element) throw new Error(`PLY property declared before any element: \"${line.trim()}\"`);\n      if (tokens[1] === 'list') {\n        // A list makes this element's records variable-size. That is fine for\n        // the element itself (a trailing `face` list is common) - it only\n        // costs later elements their computable offset. The types are recorded\n        // so a reader that does want the data can walk it record by record.\n        const countType = tokens[2] ?? '';\n        const itemType = tokens[3] ?? '';\n        const listName = tokens[4];\n        if (\n          PROPERTY_SIZES[countType] === undefined ||\n          PROPERTY_SIZES[itemType] === undefined ||\n          listName === undefined\n        ) {\n          throw new Error(`Unsupported PLY property: \"${line.trim()}\"`);\n        }\n        if (element.properties.has(listName) || element.listProperties.has(listName)) {\n          throw new Error(`Duplicate PLY property \"${listName}\" in element \"${element.name}\".`);\n        }\n        element.listProperties.set(listName, { countType, itemType });\n        element.hasListProperty = true;\n        continue;\n      }\n      const type = tokens[1] ?? '';\n      const size = PROPERTY_SIZES[type];\n      const name = tokens[2];\n      if (size === undefined || name === undefined) {\n        throw new Error(`Unsupported PLY property: \"${line.trim()}\"`);\n      }\n      if (element.properties.has(name) || element.listProperties.has(name)) {\n        // A duplicate name would let the later offset overwrite the earlier\n        // one while the stride counts both - every read after it lands on\n        // the wrong bytes.\n        throw new Error(`Duplicate PLY property \"${name}\" in element \"${element.name}\".`);\n      }\n      element.properties.set(name, { type, offset: element.stride });\n      element.propertyNames.push(name);\n      element.stride += size;\n    }\n  }\n\n  // Records are laid out back to back in element order, starting right after\n  // the header - so each element begins where the previous one ended, until a\n  // variable-size element makes the rest unreachable by arithmetic.\n  let offset = endMatch.index + endMatch[0].length;\n  let resolved = true;\n  const elements: PlyElement[] = [];\n  for (const element of building) {\n    elements.push({\n      name: element.name,\n      count: element.count,\n      properties: element.properties,\n      propertyNames: element.propertyNames,\n      listProperties: element.listProperties,\n      stride: element.stride,\n      offset: resolved ? offset : -1,\n      hasListProperty: element.hasListProperty,\n    });\n    if (element.hasListProperty) resolved = false;\n    else offset += element.count * element.stride;\n  }\n\n  return {\n    elements,\n    element: (name: string) => elements.find((candidate) => candidate.name === name),\n  };\n}\n\n/**\n * Asserts an element's records are actually present in a file of `totalBytes`.\n *\n * Takes a size rather than a buffer so it works for a streamed parse, which\n * only ever holds a window of the file.\n *\n * @throws {Error} if the element sits behind a variable-size one, or its\n * records run past the end of the file.\n */\nexport function assertPlyElementFits(element: PlyElement, totalBytes: number): void {\n  if (element.offset < 0) {\n    throw new Error(\n      `Unsupported PLY layout: element \"${element.name}\" follows a list property, so its ` +\n        'position cannot be determined.',\n    );\n  }\n  const end = element.offset + element.count * element.stride;\n  if (end > totalBytes) {\n    throw new Error(\n      `Truncated PLY file: element \"${element.name}\" needs ${end} bytes but the file is ` +\n        `${totalBytes}.`,\n    );\n  }\n}\n\n/**\n * Byte size of a PLY scalar type.\n *\n * @throws {Error} if the type is not one PLY can declare.\n */\nexport function plyTypeSize(type: string): number {\n  const size = PROPERTY_SIZES[type];\n  if (size === undefined) throw new Error(`Unsupported PLY property type: \"${type}\".`);\n  return size;\n}\n\n/** The byte offset of `property` within `element`'s record. */\nexport function plyPropertyOffset(element: PlyElement, property: string): number {\n  const found = element.properties.get(property);\n  if (!found) {\n    throw new Error(`PLY element \"${element.name}\" is missing property \"${property}\".`);\n  }\n  return found.offset;\n}\n\n/** Asserts every named property exists on `element` with the given type. */\nexport function assertPlyPropertyTypes(\n  element: PlyElement,\n  properties: readonly string[],\n  types: readonly string[],\n  what: string,\n): void {\n  for (const name of properties) {\n    const property = element.properties.get(name);\n    if (!property) {\n      throw new Error(`${what}: missing property \"${name}\".`);\n    }\n    if (!types.includes(property.type)) {\n      throw new Error(\n        `Unsupported PLY property type for \"${name}\": expected ${types.join(' or ')}, ` +\n          `got ${property.type}.`,\n      );\n    }\n  }\n}\n"],"names":["PROPERTY_SIZES","parsePlyHeader","buffer","headerBytes","headerText","endMatch","building","line","tokens","name","count","element","countType","itemType","listName","type","size","offset","resolved","elements","candidate","assertPlyElementFits","totalBytes","end","plyTypeSize","plyPropertyOffset","property","found","assertPlyPropertyTypes","properties","types","what"],"mappings":"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"}

package/dist/ply-header.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Shared PLY header reader.
+ *
+ * PLY is a container, not a format: the same `.ply` extension carries the
+ * uncompressed "INRIA flavor" 3DGS export (see `parse-splat-ply.ts`) and
+ * SuperSplat/PlayCanvas's compressed flavor (`parse-compressed-ply.ts`).
+ * Both need the same thing first - the element list, their property layouts,
+ * and where each element's records start - so that lives here.
+ */
+/** One scalar property of an element. */
+export interface PlyProperty {
+    readonly type: string;
+    /** Byte offset within one record of the element. */
+    readonly offset: number;
+}
+/**
+ * One list property (`property list <countType> <itemType> <name>`), such as a
+ * mesh's `face` indices. Only the types are recorded - the data is variable-size
+ * and must be walked record by record (see `parse-mesh-ply.ts`).
+ */
+export interface PlyListProperty {
+    /** Type of the per-record item count, e.g. `uchar`. */
+    readonly countType: string;
+    /** Type of each item, e.g. `int`. */
+    readonly itemType: string;
+}
+/** One PLY element (`element <name> <count>`) and its record layout. */
+export interface PlyElement {
+    readonly name: string;
+    readonly count: number;
+    readonly properties: ReadonlyMap<string, PlyProperty>;
+    /** Property names in declaration order. */
+    readonly propertyNames: readonly string[];
+    /** List properties by name; empty unless {@link hasListProperty}. */
+    readonly listProperties: ReadonlyMap<string, PlyListProperty>;
+    /**
+     * Bytes per record - meaningless when {@link hasListProperty}, since a list
+     * makes each record's size depend on its contents.
+     */
+    readonly stride: number;
+    /**
+     * Byte offset of this element's first record within the file, or -1 when a
+     * preceding element has a variable-size record and no arithmetic can find it.
+     */
+    readonly offset: number;
+    /** A list property makes this element's records variable-size. */
+    readonly hasListProperty: boolean;
+}
+/** A parsed PLY header. */
+export interface PlyHeader {
+    readonly elements: readonly PlyElement[];
+    /** The element of that name, or undefined. */
+    element(name: string): PlyElement | undefined;
+}
+/**
+ * Reads a binary little-endian PLY header and resolves every element's byte
+ * offset by walking the elements in declaration order.
+ *
+ * Whether the declared records actually fit in the buffer is deliberately not
+ * checked here - call {@link assertPlyElementFits} once the caller has
+ * validated the properties it needs, so a wrong property type is reported as
+ * such rather than as the truncation it happens to imply.
+ *
+ * @throws {Error} if the file is not a binary little-endian PLY, or declares a
+ * property type this reader cannot size.
+ */
+export declare function parsePlyHeader(buffer: ArrayBuffer): PlyHeader;
+/**
+ * Asserts an element's records are actually present in a file of `totalBytes`.
+ *
+ * Takes a size rather than a buffer so it works for a streamed parse, which
+ * only ever holds a window of the file.
+ *
+ * @throws {Error} if the element sits behind a variable-size one, or its
+ * records run past the end of the file.
+ */
+export declare function assertPlyElementFits(element: PlyElement, totalBytes: number): void;
+/**
+ * Byte size of a PLY scalar type.
+ *
+ * @throws {Error} if the type is not one PLY can declare.
+ */
+export declare function plyTypeSize(type: string): number;
+/** The byte offset of `property` within `element`'s record. */
+export declare function plyPropertyOffset(element: PlyElement, property: string): number;
+/** Asserts every named property exists on `element` with the given type. */
+export declare function assertPlyPropertyTypes(element: PlyElement, properties: readonly string[], types: readonly string[], what: string): void;

package/dist/radix-sort.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @role Utility
+ * Shared constants and deterministic reference logic for GPU radix sorting.
+ */
+/** Depth precision retained by both the GPU radix path and WebGL worker path. */
+export declare const RADIX_KEY_BITS = 24;
+/** Exact Float32 depth keys use every sortable IEEE-754 bit. */
+export declare const RADIX_EXACT_KEY_BITS = 32;
+/** Four-bit digits keep the portable shader's workgroup memory requirements small. */
+export declare const RADIX_BITS_PER_PASS = 4;
+export declare const RADIX_BUCKETS: number;
+export declare const RADIX_PASS_COUNT: number;
+export declare const RADIX_KEY_MAX: number;
+/** Number of four-bit passes required for one unsigned radix key width. */
+export declare function radixPassCount(keyBits: number): number;
+/**
+ * Maps a Float32 bit pattern onto unsigned integer order without losing depth
+ * precision. Ascending mapped keys are ascending numeric floats, including
+ * negative view-space Z values (farther splats first in VLAM's convention).
+ */
+export declare function sortableFloat32Bits(bits: number): number;
+/** Quantizes a depth into the unsigned 24-bit key used by the GPU sorter. */
+export declare function quantizeDepthKey(depth: number, minimum: number, maximum: number): number;
+/**
+ * Stable CPU reference for validating the GPU's six four-bit radix passes.
+ * This is deliberately test/debug-only logic, not the WebGL production sorter.
+ */
+export declare function stableRadixSortReference(keys: Uint32Array, values?: Uint32Array, keyBits?: number): Uint32Array;

package/dist/radix-sorter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @role Bridge
+ * Portable stable WebGPU radix sorting adapted to Three.js TSL compute nodes.
+ */
+import * as THREE from 'three/webgpu';
+import type { SplatSorter } from './sorter';
+/**
+ * Stable four-bit-per-pass WebGPU radix sorter.
+ *
+ * The ranked scatter follows PlayCanvas/WebGPU-Radix-Sort's per-digit bitmask
+ * design. Three.js does not currently expose atomic workgroup arrays in TSL,
+ * so masks use disjoint global-storage slices per workgroup. Workgroup and
+ * storage barriers retain the same stable ranking semantics without relying
+ * on cross-workgroup execution order.
+ */
+export declare class RadixSorter implements SplatSorter {
+    readonly kind: "radix";
+    private readonly renderer;
+    private readonly stages;
+    private readonly workingAttributes;
+    /** Frees the JS mirrors three keeps behind the GPU-only ping-pong buffers. */
+    private readonly mirrors;
+    /** Set by {@link dispose}; makes a second dispose a no-op. */
+    private disposed;
+    private readonly viewRow2;
+    private readonly depthMin;
+    private readonly depthScale;
+    private readonly activeCount;
+    private readonly viewCenter;
+    /** Exact mode avoids scene-bounds quantization entirely. */
+    private readonly exactDepth;
+    constructor(options: {
+        renderer: THREE.WebGPURenderer;
+        capacity: number;
+        centersTexture?: THREE.DataTexture;
+        dataTextureWidth?: number;
+        /** Gathered world-space centers for a unified renderer. */
+        centersBuffer?: THREE.StorageBufferAttribute;
+        splatIndexAttribute: THREE.StorageInstancedBufferAttribute;
+        sourceIndexAttribute: THREE.StorageBufferAttribute;
+        /** Keep every Float32 depth bit instead of quantizing to 24 bits. */
+        exactDepth?: boolean;
+    });
+    sort(modelView: THREE.Matrix4, activeCount: number, bounds: THREE.Sphere): boolean;
+    dispose(): void;
+}

package/dist/relighting.d.ts

@@ -0,0 +1,50 @@
+/**
+ * PlayCanvas-style proxy-mesh splat relighting (screen-space modulate).
+ *
+ * Host lights a proxy mesh into an RGBA render target (RGB = lit color,
+ * A = coverage), then {@link SplatMesh.setRelighting} /
+ * {@link UnifiedSplatRenderer.setRelighting} multiplies baked splat color in
+ * the display fragment. Not a `SplatModifier` - coverage is per-pixel.
+ *
+ * See `docs/guide/relighting.md`.
+ */
+import * as THREE from 'three/webgpu';
+/** Defaults match PlayCanvas `GsplatRelighting` (0.5 gray proxy albedo → brightness 2). */
+export declare const DEFAULT_RELIGHT_BLEND = 1;
+export declare const DEFAULT_RELIGHT_BRIGHTNESS = 2;
+export declare const DEFAULT_RELIGHT_BACKGROUND = 1;
+/** Screen-space soft edge on coverage (px). Softens coarse proxy silhouettes. */
+export declare const DEFAULT_RELIGHT_SOFTNESS = 0;
+/** Live screen-space relighting settings for {@link SplatMesh.setRelighting}. */
+export type RelightingSettings = {
+    /** Lit proxy render: RGB = lighting, A = mesh coverage (0 = sky / uncovered). */
+    map: THREE.Texture;
+    /** How much the map affects splat color (`0` = baked only, `1` = full modulate). */
+    blend?: number;
+    /** Scales `map.rgb` before multiply; `2` compensates a 0.5 gray proxy albedo. */
+    brightness?: number;
+    /** Multiplier for splats where `map.a ≈ 0` (sky / uncovered). */
+    background?: number;
+    /**
+     * Softens the coverage mask over this many screen pixels (box filter). Use
+     * `2`–`4` when the proxy is a coarse collision mesh so triangle silhouettes
+     * do not read as a static shadow. `0` = hard PlayCanvas-style edges.
+     */
+    softness?: number;
+};
+/** Resolved numeric fields after clamping (map omitted - still the host texture). */
+export type RelightingUniforms = {
+    blend: number;
+    brightness: number;
+    background: number;
+    softness: number;
+};
+/**
+ * Clamps blend / brightness / background / softness.
+ */
+export declare function clampRelightingSettings(partial: Partial<Pick<RelightingSettings, 'blend' | 'brightness' | 'background' | 'softness'>>, previous?: RelightingUniforms): RelightingUniforms;
+/**
+ * 1×1 opaque white placeholder so the fragment graph can always sample a map
+ * when relighting is off (`blend === 0`).
+ */
+export declare function createPlaceholderRelightTexture(): THREE.DataTexture;

package/dist/selection-volume.d.ts

@@ -0,0 +1,87 @@
+import * as THREE from 'three/webgpu';
+import type { SplatData } from './splat-data';
+/**
+ * Volume selection over splat centers (CPU).
+ *
+ * A {@link SelectionVolume} answers one question - is this point inside the
+ * volume? - so hosts can select a region of a loaded splat cloud with a placed
+ * box, sphere or cylinder ({@link createSelectionVolume}), or with any custom
+ * shape by implementing the interface directly.
+ *
+ * Selection runs over a `SplatData`'s positions ({@link selectInData}); the
+ * split itself lives in `splat-partition.ts`. Everything here is pure array
+ * math - no GPU, no mesh - so it is cheap to test and works the same for any
+ * host. A one-shot selection gesture over a few million centers is a
+ * brute-force scan by design: it costs milliseconds, needs no index to build
+ * or invalidate, and supports arbitrarily transformed (including non-uniformly
+ * scaled) volumes that a radius-based spatial grid cannot.
+ */
+export interface SelectionVolume {
+    /**
+     * Whether the point `(x, y, z)` lies inside the volume, in **the frame the
+     * volume was built for** - for {@link createSelectionVolume} that is the
+     * frame of the positions passed to {@link selectInData} (splat-local for a
+     * `SplatData`, source-local for a collision mesh), fixed by the
+     * `worldMatrix` argument.
+     *
+     * A splat is selected iff its *center* passes this test; a splat whose
+     * center is outside but whose ellipsoid extent overlaps the volume is not
+     * selected.
+     */
+    containsPoint(x: number, y: number, z: number): boolean;
+}
+/** The built-in selection shapes. Custom shapes implement {@link SelectionVolume}. */
+export type SelectionVolumeKind = 'box' | 'sphere' | 'cylinder';
+/** Describes a built-in selection shape for {@link createSelectionVolume}. */
+export interface SelectionVolumeOptions {
+    kind: SelectionVolumeKind;
+    /**
+     * Places the shape: volume-local → world. Encodes the shape's center,
+     * orientation and any (possibly non-uniform) scale. Default identity.
+     * Must be invertible - a zero scale axis throws.
+     */
+    transform?: THREE.Matrix4;
+    /**
+     * Box half-extents (volume-local units). Required for `kind: 'box'`; every
+     * component must be positive.
+     */
+    halfExtents?: readonly [number, number, number];
+    /**
+     * Sphere or cylinder radius (volume-local units). Required for
+     * `kind: 'sphere'` and `kind: 'cylinder'`; must be positive.
+     */
+    radius?: number;
+    /**
+     * Cylinder full height along the volume-local Y axis. Required for
+     * `kind: 'cylinder'`; must be positive.
+     */
+    height?: number;
+}
+/**
+ * Builds a {@link SelectionVolume} for one of the built-in shapes.
+ *
+ * `worldMatrix` is the local → world matrix of the geometry being selected
+ * (`mesh.matrixWorld`; omit for data not attached to a mesh). It fixes the
+ * frame {@link SelectionVolume.containsPoint} expects: each point is mapped
+ * through `transform⁻¹ · worldMatrix` into the shape's own frame, so a rotated
+ * or non-uniformly scaled volume placement costs the same as an axis-aligned
+ * one.
+ *
+ * @throws {Error} if the shape's dimensions are missing/non-positive, or if
+ * the combined `transform⁻¹ · worldMatrix` is singular or non-finite (a
+ * collapsed axis on either matrix would otherwise select silent garbage).
+ */
+export declare function createSelectionVolume(options: SelectionVolumeOptions, worldMatrix?: THREE.Matrix4): SelectionVolume;
+/**
+ * The indices of every splat in `data` whose center is inside `volume`,
+ * ascending. Pure read - `data` is untouched; feed the result (or the volume
+ * directly) to `partitionSplatData` to split.
+ */
+export declare function selectInData(data: SplatData, volume: SelectionVolume): Uint32Array;
+/**
+ * How many splats in `data` fall inside `volume`, without materializing the
+ * index list - for a live "n selected" readout while a host drags a volume
+ * around, where {@link selectInData}'s `Uint32Array(count)` would allocate tens
+ * of megabytes per pointer event on a large scene.
+ */
+export declare function countInData(data: SplatData, volume: SelectionVolume): number;

package/dist/sh-pack-D5wAe5gg.js

@@ -0,0 +1,54 @@
+const p = [2047, 1023, 2047];
+function v(n) {
+  return [0, 3, 8, 15][n] ?? 0;
+}
+function C(n, t, a, m) {
+  const i = v(a);
+  let o = m ?? 0;
+  if (m === void 0)
+    for (const c of n) o = Math.max(o, Math.abs(c));
+  const s = {
+    min: [-o, -o, -o],
+    max: [o, o, o]
+  }, r = new Uint32Array(t * i), h = o || 1;
+  for (let c = 0; c < r.length; c++) {
+    const e = c * 3, u = (l, M) => Math.min(M, Math.max(0, Math.round((l / h + 1) * 0.5 * M))), x = u(n[e], 2047), d = u(n[e + 1], 1023), f = u(n[e + 2], 2047);
+    r[c] = (x | d << 11 | f << 21) >>> 0;
+  }
+  return { bands: a, packed: r, range: s };
+}
+function k(n) {
+  const t = (a, m, i) => {
+    if (m === a) return 0;
+    const o = (0 - a) / (m - a);
+    return Math.max(0, Math.min(i, Math.round(o * i)));
+  };
+  return (t(n.min[0], n.max[0], 2047) | t(n.min[1], n.max[1], 1023) << 11 | t(n.min[2], n.max[2], 2047) << 21) >>> 0;
+}
+function q(n, t) {
+  return n.min[0] === t.min[0] && n.min[1] === t.min[1] && n.min[2] === t.min[2] && n.max[0] === t.max[0] && n.max[1] === t.max[1] && n.max[2] === t.max[2];
+}
+function S(n, t, a) {
+  return n + (t - n) * a;
+}
+function A(n, t, a) {
+  const m = [n & 2047, n >>> 11 & 1023, n >>> 21 & 2047];
+  let i = 0, o = 0;
+  for (let s = 0; s < 3; s++) {
+    const r = p[s], h = S(
+      t.min[s],
+      t.max[s],
+      m[s] / r
+    ), c = a.min[s], e = a.max[s], u = e === c ? 0 : (h - c) / (e - c), x = Math.max(0, Math.min(r, Math.round(u * r)));
+    i |= x << o, o += s === 0 ? 11 : 10;
+  }
+  return i >>> 0;
+}
+export {
+  q as a,
+  k as n,
+  C as p,
+  A as r,
+  v as s
+};
+//# sourceMappingURL=sh-pack-D5wAe5gg.js.map

package/dist/sh-pack-D5wAe5gg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sh-pack-D5wAe5gg.js","sources":["../src/lib/sh-pack.ts"],"sourcesContent":["/**\n * Packing and requantization for per-splat higher-order SH.\n *\n * Every streamed format that keeps view-dependent color stores it in one\n * layout: {@link SplatPackedShData}, a `DecodePacked_11_10_11` word per\n * coefficient (R: bits 0-10 /2047, G: 11-20 /1023, B: 21-31 /2047) dequantized\n * across a per-channel range. LCC `Quality` captures and `.rad` deliver it directly; a\n * streamed SOG (or `.lcc2`) palette is *converted* into it at decode\n * ({@link packPaletteSh}) so it survives the shared pool - see\n * `docs/formats/streamed-shn-notes.md` (M11). The pool decodes the whole scene through\n * one range uniform, so a chunk whose range differs is requantized into the\n * scene's range at append ({@link requantizeShWord}).\n *\n * Pure array math, no THREE - safe to import in the decode worker.\n */\nimport type { SplatPackedShData, SplatShData } from './splat-data';\n\n/** A per-channel `[min, max]` dequantization range for packed SH. */\nexport type ShRange = SplatPackedShData['range'];\n\n/** The 11/10/11 field maxima of a packed SH word, per channel. */\nconst SH_FIELD_MAX = [2047, 1023, 2047] as const;\n\n/** Coefficients per channel for a band count (0 → none, 3 → 3rd order). */\nexport function shCoefficientCount(bands: number): number {\n  return [0, 3, 8, 15][bands] ?? 0;\n}\n\n/**\n * Quantizes splat-major coefficient triples into packed 11/10/11 words:\n * `count * shCoefficientCount(bands)` words, each holding one coefficient's\n * (R, G, B). `knownExtent` pins the symmetric range to a scene-wide value\n * (values outside clamp); without it the extent is measured from\n * `coefficients` - only safe when they are the whole scene, since every chunk\n * must share one range.\n */\nexport function packShCoefficients(\n  coefficients: Float32Array,\n  count: number,\n  bands: 1 | 2 | 3,\n  knownExtent?: number,\n): SplatPackedShData {\n  const words = shCoefficientCount(bands);\n  let extent = knownExtent ?? 0;\n  if (knownExtent === undefined) {\n    for (const value of coefficients) extent = Math.max(extent, Math.abs(value));\n  }\n  // The shader has one range for every band. A symmetric common range\n  // preserves the signed SH convention; exact 0 is not representable (it falls\n  // between the two middle codes, a half-LSB positive bias - see the tests).\n  const range = {\n    min: [-extent, -extent, -extent] as const,\n    max: [extent, extent, extent] as const,\n  };\n  const packed = new Uint32Array(count * words);\n  const divisor = extent || 1;\n  for (let i = 0; i < packed.length; i++) {\n    const base = i * 3;\n    const encode = (value: number, max: number): number =>\n      Math.min(max, Math.max(0, Math.round((value / divisor + 1) * 0.5 * max)));\n    const r = encode(coefficients[base] as number, 2047);\n    const g = encode(coefficients[base + 1] as number, 1023);\n    const b = encode(coefficients[base + 2] as number, 2047);\n    packed[i] = (r | (g << 11) | (b << 21)) >>> 0;\n  }\n  return { bands, packed, range };\n}\n\n/**\n * Converts a palette-compressed SH source ({@link SplatShData}, as SOG/`.lcc2`\n * store it) into the per-splat packed form, keeping the lowest `bands` bands.\n * Each splat's palette label indexes the codebook image; the coefficients are\n * read out into splat-major triples and quantized against this chunk's own\n * measured extent. Later chunks may measure a different extent - the pool\n * requantizes any mismatch into the scene's range at append.\n */\nexport function packPaletteSh(sh: SplatShData, count: number, bands: 1 | 2 | 3): SplatPackedShData {\n  const want = shCoefficientCount(bands);\n  // The palette stores its own (possibly higher) band count; a lower request is\n  // a prefix of each entry's coefficients, since bands run low-order first.\n  const have = shCoefficientCount(sh.bands);\n  const width = sh.paletteWidth;\n  const coefficients = new Float32Array(count * want * 3);\n  for (let i = 0; i < count; i++) {\n    const label = sh.labels[i] as number;\n    // SOG centroids layout: entry n, coefficient c at column (n % 64) · have + c,\n    // row ⌊n / 64⌋; R/G/B channels hold that coefficient for the R/G/B SH.\n    const column0 = (label % 64) * have;\n    const row = Math.floor(label / 64);\n    // Labels are 16-bit and the parser validates only the labels image, not\n    // the label *values*. An out-of-bounds palette read yields NaN\n    // coefficients, NaN-poisoning this chunk's measured range - and, were it\n    // the scene's first SH chunk, locking a NaN pool range that destroys SH\n    // scene-wide. Throw instead, like the `.rad` label path does.\n    // Check the row extent as well as the linear index: a label whose entry\n    // would wrap past the row's end must fail rather than silently reading\n    // the start of another entry on the next row.\n    if (column0 + have > width || (row * width + column0 + have) * 4 > sh.palette.length) {\n      throw new Error(`packPaletteSh: splat ${i} has SH label ${label} outside the palette.`);\n    }\n    // Read the min(want, have) low-order coefficients; if the caller asked for\n    // more bands than the palette carries, the surplus stays 0 (neutral) so the\n    // packed band count still matches the pool's, rather than a band mismatch\n    // that would drop the SH entirely.\n    const readable = Math.min(want, have);\n    for (let c = 0; c < readable; c++) {\n      const texel = (row * width + column0 + c) * 4;\n      const base = (i * want + c) * 3;\n      coefficients[base] = sh.palette[texel] as number;\n      coefficients[base + 1] = sh.palette[texel + 1] as number;\n      coefficients[base + 2] = sh.palette[texel + 2] as number;\n    }\n  }\n  return packShCoefficients(coefficients, count, bands);\n}\n\n/** The packed word that decodes to 0.0 in every channel under `range`. */\nexport function neutralShWord(range: ShRange): number {\n  const code = (lo: number, hi: number, maxCode: number): number => {\n    if (hi === lo) return 0;\n    const t = (0 - lo) / (hi - lo);\n    return Math.max(0, Math.min(maxCode, Math.round(t * maxCode)));\n  };\n  return (\n    (code(range.min[0], range.max[0], 2047) |\n      (code(range.min[1], range.max[1], 1023) << 11) |\n      (code(range.min[2], range.max[2], 2047) << 21)) >>>\n    0\n  );\n}\n\n/** Whether two packed-SH ranges are bit-identical (no requantization needed). */\nexport function packedRangesEqual(a: ShRange, b: ShRange): boolean {\n  return (\n    a.min[0] === b.min[0] &&\n    a.min[1] === b.min[1] &&\n    a.min[2] === b.min[2] &&\n    a.max[0] === b.max[0] &&\n    a.max[1] === b.max[1] &&\n    a.max[2] === b.max[2]\n  );\n}\n\nfunction lerp(a: number, b: number, t: number): number {\n  return a + (b - a) * t;\n}\n\n/**\n * Re-encodes one packed word so it decodes to the same three channel values\n * under `to` as it did under `from`. Values outside `to` clip to its endpoints;\n * a zero-width `to` channel collapses to code 0. This is what lets chunks\n * quantized against different ranges share one pool range.\n */\nexport function requantizeShWord(word: number, from: ShRange, to: ShRange): number {\n  const codes = [word & 0x7ff, (word >>> 11) & 0x3ff, (word >>> 21) & 0x7ff];\n  let out = 0;\n  let shift = 0;\n  for (let ch = 0; ch < 3; ch++) {\n    const maxCode = SH_FIELD_MAX[ch] as number;\n    const value = lerp(\n      from.min[ch] as number,\n      from.max[ch] as number,\n      (codes[ch] as number) / maxCode,\n    );\n    const lo = to.min[ch] as number;\n    const hi = to.max[ch] as number;\n    const t = hi === lo ? 0 : (value - lo) / (hi - lo);\n    const code = Math.max(0, Math.min(maxCode, Math.round(t * maxCode)));\n    out |= code << shift;\n    shift += ch === 0 ? 11 : 10;\n  }\n  return out >>> 0;\n}\n"],"names":["SH_FIELD_MAX","shCoefficientCount","bands","packShCoefficients","coefficients","count","knownExtent","words","extent","value","range","packed","divisor","i","base","encode","max","r","g","b","neutralShWord","code","lo","hi","maxCode","t","packedRangesEqual","a","lerp","requantizeShWord","word","from","to","codes","out","shift","ch"],"mappings":"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"}

package/dist/sh-pack.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Packing and requantization for per-splat higher-order SH.
+ *
+ * Every streamed format that keeps view-dependent color stores it in one
+ * layout: {@link SplatPackedShData}, a `DecodePacked_11_10_11` word per
+ * coefficient (R: bits 0-10 /2047, G: 11-20 /1023, B: 21-31 /2047) dequantized
+ * across a per-channel range. LCC `Quality` captures and `.rad` deliver it directly; a
+ * streamed SOG (or `.lcc2`) palette is *converted* into it at decode
+ * ({@link packPaletteSh}) so it survives the shared pool - see
+ * `docs/formats/streamed-shn-notes.md` (M11). The pool decodes the whole scene through
+ * one range uniform, so a chunk whose range differs is requantized into the
+ * scene's range at append ({@link requantizeShWord}).
+ *
+ * Pure array math, no THREE - safe to import in the decode worker.
+ */
+import type { SplatPackedShData, SplatShData } from './splat-data';
+/** A per-channel `[min, max]` dequantization range for packed SH. */
+export type ShRange = SplatPackedShData['range'];
+/** Coefficients per channel for a band count (0 → none, 3 → 3rd order). */
+export declare function shCoefficientCount(bands: number): number;
+/**
+ * Quantizes splat-major coefficient triples into packed 11/10/11 words:
+ * `count * shCoefficientCount(bands)` words, each holding one coefficient's
+ * (R, G, B). `knownExtent` pins the symmetric range to a scene-wide value
+ * (values outside clamp); without it the extent is measured from
+ * `coefficients` - only safe when they are the whole scene, since every chunk
+ * must share one range.
+ */
+export declare function packShCoefficients(coefficients: Float32Array, count: number, bands: 1 | 2 | 3, knownExtent?: number): SplatPackedShData;
+/**
+ * Converts a palette-compressed SH source ({@link SplatShData}, as SOG/`.lcc2`
+ * store it) into the per-splat packed form, keeping the lowest `bands` bands.
+ * Each splat's palette label indexes the codebook image; the coefficients are
+ * read out into splat-major triples and quantized against this chunk's own
+ * measured extent. Later chunks may measure a different extent - the pool
+ * requantizes any mismatch into the scene's range at append.
+ */
+export declare function packPaletteSh(sh: SplatShData, count: number, bands: 1 | 2 | 3): SplatPackedShData;
+/** The packed word that decodes to 0.0 in every channel under `range`. */
+export declare function neutralShWord(range: ShRange): number;
+/** Whether two packed-SH ranges are bit-identical (no requantization needed). */
+export declare function packedRangesEqual(a: ShRange, b: ShRange): boolean;
+/**
+ * Re-encodes one packed word so it decodes to the same three channel values
+ * under `to` as it did under `from`. Values outside `to` clip to its endpoints;
+ * a zero-width `to` channel collapses to code 0. This is what lets chunks
+ * quantized against different ranges share one pool range.
+ */
+export declare function requantizeShWord(word: number, from: ShRange, to: ShRange): number;