@voluma/vlam 0.1.0 → 0.2.1

package/dist/formats/lcc/parse-lcc.d.ts

@@ -0,0 +1,177 @@
+import { type SplatData } from '../../splat-data';
+/**
+ * Decoder for XGRIDS' older LCC datasets (`.lcc` / `meta.lcc`; see
+ * `docs/formats/lcc-notes.md`). Manifest versions **2.x** through **5.x** share the
+ * same binary layout; v2/v3 omit `fileType` and v3 often names the manifest `meta.lcc`.
+ *
+ * Unlike `.lcc2` - which delivers SOG/WebP tiles and reuses {@link parseSog} -
+ * an LCC dataset is raw binary: a JSON manifest, an `index.bin` of per-cell
+ * per-level ranges, and one large `data.bin` of fixed 32-byte splat records
+ * that chunks are cut out of with HTTP range requests.
+ *
+ * Implemented from XGRIDS' openly published spec (Data Organization Format
+ * originated from XGRIDS); no XGRIDS code is used, and their capture data is
+ * never redistributed. Where the whitepaper's field table disagrees with real
+ * captures the bytes win - see `docs/formats/lcc-notes.md` for the verification.
+ */
+/** Bytes per splat in `data.bin`. */
+export declare const LCC_RECORD_BYTES = 32;
+/** Bytes per splat in `shcoef.bin`, and of the SH block inside an env record. */
+export declare const LCC_SH_RECORD_BYTES = 64;
+/** SH coefficients per channel in a `Quality` capture (3rd order). */
+export declare const LCC_SH_COEFFICIENTS = 15;
+/** A `[min, max]` dequantization range from the manifest's `attributes`. */
+export interface LccRange {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+}
+/**
+ * Where a capture's local origin sits in the real world. Purely informational
+ * - the splat data is local and is rendered as-is (see `parseGeoreference`).
+ */
+export interface LccGeoreference {
+    /** The local origin's coordinates in {@link epsg}, from manifest `offset`. */
+    readonly origin: readonly [number, number, number];
+    /** The projection's EPSG code, when the manifest names one. */
+    readonly epsg?: number;
+}
+/** The manifest fields this loader consumes. */
+export interface LccManifest {
+    readonly totalSplats: number;
+    readonly totalLevel: number;
+    readonly cellLengthX: number;
+    readonly cellLengthY: number;
+    readonly indexDataSize: number;
+    /** Per-level splat totals; index 0 is the finest level. */
+    readonly splats: readonly number[];
+    readonly bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    /** `Quality` captures carry `shcoef.bin`; `Portable` ones have no SH. */
+    readonly fileType: 'Portable' | 'Quality';
+    readonly scale: LccRange;
+    readonly shcoef: LccRange;
+    readonly envScale: LccRange;
+    readonly envShcoef: LccRange;
+    /** Set when the capture is georeferenced; absent for a purely local one. */
+    readonly georeference?: LccGeoreference;
+}
+/** One cell's range within `data.bin` at one LOD level. */
+export interface LccLevelRange {
+    readonly count: number;
+    readonly byteOffset: number;
+    readonly byteSize: number;
+}
+/** One `index.bin` record: a cell of the 2D grid, at every LOD level. */
+export interface LccIndexCell {
+    readonly cellX: number;
+    readonly cellY: number;
+    /** Range per level; index 0 is the finest. */
+    readonly levels: readonly LccLevelRange[];
+}
+/** Everything the worker needs to turn fetched bytes into splats. */
+export interface LccChunkParams {
+    /** `splats` decodes `data.bin`; `environment` decodes `environment.bin`. */
+    readonly kind: 'splats' | 'environment';
+    /** Byte range within the source file. */
+    readonly start: number;
+    readonly length: number;
+    /**
+     * Bytes per record. Always 32 in `data.bin`; `environment.bin` interleaves
+     * a 64-byte SH block per splat in a `Quality` capture, making it 96.
+     *
+     * This is a property of the *file*, not of whether the SH is wanted - a
+     * `Quality` environment stays 96 bytes per record even with SH disabled.
+     */
+    readonly stride: number;
+    /** Dequantization range for the scale field (`scale` or `envscale`). */
+    readonly scale: LccRange;
+    /** Present when this chunk's SH should be decoded (see `LccShParams`). */
+    readonly sh?: LccShParams;
+}
+/** How to obtain (and dequantize) a chunk's higher-order SH. */
+export interface LccShParams {
+    /** SH bands to keep: 1, 2 or 3 → 3, 8 or 15 coefficients. */
+    readonly bands: 1 | 2 | 3;
+    readonly range: LccRange;
+    /**
+     * Where the SH bytes come from. `sidecar` fetches `shcoef.bin` over the
+     * given range (`data.bin` offset × 2); `inline` reads the 64-byte block
+     * that follows each base record inside a 96-byte environment record.
+     */
+    readonly source: 'sidecar' | 'inline';
+    /** Absolute `shcoef.bin` URL; only for `source: 'sidecar'`. */
+    readonly url?: string;
+    /**
+     * Re-encode the decoded words into this range instead of {@link range}.
+     *
+     * An LCC capture quantizes base SH (`shcoef`) and environment SH
+     * (`envshcoef`) against *different* ranges, but the shared pool decodes the
+     * whole scene through one range uniform. Left alone, whichever chunk lands
+     * first wins and the other's coefficients are read against the wrong span -
+     * the environment range is wider, so base SH gets amplified into a
+     * view-dependent "flashlight." So the environment chunk is requantized into
+     * the base range here, letting every chunk agree on `shcoef`. Values outside
+     * the base range clip (only decorative sky highlights, and only the few
+     * thousand environment splats pay the re-encode).
+     */
+    readonly requantizeTo?: LccRange;
+}
+/** Coefficients carried by each SH band count. */
+export declare function lccShCoefficientCount(bands: 1 | 2 | 3): number;
+/**
+ * Validates an untrusted `.lcc` manifest and extracts the fields the loader
+ * needs. Everything downstream (index record size, chunk byte ranges, pool
+ * sizing) derives from these, so they are checked up front.
+ *
+ * @throws {Error} on an unsupported version or a malformed manifest.
+ */
+export declare function parseLccManifest(json: unknown): LccManifest;
+/**
+ * Parses `index.bin` into one record per cell.
+ *
+ * @param buffer - The whole file (a few KB even for large captures).
+ * @param manifest - Supplies the record size and level count.
+ * @throws {Error} if the file length or any record is inconsistent.
+ */
+export declare function parseLccIndex(buffer: ArrayBuffer, manifest: LccManifest): LccIndexCell[];
+/**
+ * Decodes a packed rotation into a quaternion `[w, x, y, z]`.
+ *
+ * Smallest-three: bits 30-31 name the omitted (largest-magnitude) component
+ * as an index into `(x, y, z, w)`, and three 10-bit fields hold the others in
+ * ascending index order as offset binary with bias 511, spanning `[-√½, +√½]`.
+ * The omitted component is recovered from unit length.
+ *
+ * Note this is neither the whitepaper's `QLut`/`DecodeRotation` nor the
+ * LCC-Web SDK's sign-magnitude `parseQuat` (which decodes the SDK's own
+ * repacked GPU texture, not the file) - see `docs/formats/lcc-notes.md`.
+ *
+ * The result is unit-length for any word a real encoder produces. A corrupt
+ * word whose three stored components already exceed unit length yields a
+ * non-unit (but always finite) quaternion, as in {@link parseSog}'s
+ * equivalent decode; {@link writeCovariance} normalizes.
+ */
+export declare function decodeLccRotation(encoded: number): [number, number, number, number];
+/**
+ * Decodes one packed SH word into its three channel values.
+ *
+ * `DecodePacked_11_10_11`: R is bits 0-10, G bits 11-20, B bits 21-31, each a
+ * unit fraction of its field's maximum, dequantized across `range`.
+ */
+export declare function decodeLccShWord(word: number, range: LccRange, out: Float32Array, at: number): void;
+/**
+ * Decodes a range of `data.bin` (or the base records of `environment.bin`)
+ * into the flat arrays the pool uploads.
+ *
+ * @param buffer - Exactly the chunk's bytes: `count * 32` for `splats`, or
+ * `count * stride` for `environment`.
+ * @param params - Byte range and dequantization ranges from the scene builder.
+ * @param sh - Optional SH bytes: the matching `shcoef.bin` range for
+ * `source: 'sidecar'`, or unused when the SH is inline in `buffer`.
+ * @param signal - Checked inside the decode loop so a superseded chunk can be
+ * abandoned mid-decode.
+ * @throws a `DOMException` named `AbortError` when cancelled.
+ */
+export declare function parseLccChunk(buffer: ArrayBuffer, params: LccChunkParams, sh?: ArrayBuffer, signal?: AbortSignal): Promise<SplatData>;

package/dist/formats/lcc/parse-mesh-ply.d.ts

@@ -0,0 +1,21 @@
+/** A plain indexed triangle mesh decoded from a PLY. */
+export interface TriangleMeshData {
+    readonly vertexCount: number;
+    readonly triangleCount: number;
+    /** `x, y, z` per vertex, in the file's own coordinate frame. */
+    readonly positions: Float32Array;
+    /** Three vertex indices per triangle, into {@link positions}. */
+    readonly indices: Uint32Array;
+}
+/**
+ * Parses a binary little-endian triangle-mesh PLY.
+ *
+ * Faces with more than three vertices are fan-triangulated; degenerate faces
+ * (fewer than three) are dropped. Coordinates are passed through untouched, so
+ * a source-local frame stays source-local - an LCC2 mesh needs the same
+ * `createLcc2ToThreeMatrix` correction its splats get.
+ *
+ * @throws {Error} if the file is not a binary little-endian PLY, lacks a
+ * usable vertex or face element, or is truncated.
+ */
+export declare function parseMeshPly(buffer: ArrayBuffer): TriangleMeshData;