@driftengine/splats 3.61.0

package/dist/splatPly.js

@@ -0,0 +1,242 @@
+/** The `.ply` reader: an ASCII header describing a binary body, as a training run writes it. */
+import { SPLAT_SH1_COEFFICIENTS, packSplats } from './splatData.js';
+/** Coefficients per channel in the l=1 band: the three basis functions Y(1,−1), Y(1,0), Y(1,1). */
+const SH1_PER_CHANNEL = 3;
+/**
+ * The spherical-harmonic band-0 constant, `0.5 * sqrt(1 / pi)`.
+ *
+ * A capture stores colour as the DC term of a spherical-harmonic expansion, which is a *radiance
+ * coefficient* and not a colour: it is signed, unbounded, and centred on zero rather than on a half.
+ * `0.5 + C0 * f_dc` is the conversion every viewer of this format uses, and getting it wrong is not
+ * subtle — dropping the 0.5 leaves half the capture negative and clamped to black.
+ */
+const SH_C0 = 0.28209479177387814;
+/** How many bytes each PLY scalar type occupies, and how to read one. */
+const SCALARS = {
+    char: { bytes: 1, read: (v, at) => v.getInt8(at) },
+    int8: { bytes: 1, read: (v, at) => v.getInt8(at) },
+    uchar: { bytes: 1, read: (v, at) => v.getUint8(at) },
+    uint8: { bytes: 1, read: (v, at) => v.getUint8(at) },
+    short: { bytes: 2, read: (v, at) => v.getInt16(at, true) },
+    int16: { bytes: 2, read: (v, at) => v.getInt16(at, true) },
+    ushort: { bytes: 2, read: (v, at) => v.getUint16(at, true) },
+    uint16: { bytes: 2, read: (v, at) => v.getUint16(at, true) },
+    int: { bytes: 4, read: (v, at) => v.getInt32(at, true) },
+    int32: { bytes: 4, read: (v, at) => v.getInt32(at, true) },
+    uint: { bytes: 4, read: (v, at) => v.getUint32(at, true) },
+    uint32: { bytes: 4, read: (v, at) => v.getUint32(at, true) },
+    float: { bytes: 4, read: (v, at) => v.getFloat32(at, true) },
+    float32: { bytes: 4, read: (v, at) => v.getFloat32(at, true) },
+    double: { bytes: 8, read: (v, at) => v.getFloat64(at, true) },
+    float64: { bytes: 8, read: (v, at) => v.getFloat64(at, true) },
+};
+const HEADER_END = 'end_header';
+/**
+ * Parse the ASCII header and build a property offset table from the **declared** order.
+ *
+ * **Declared, never assumed.** Training runs emit roughly
+ * `x y z nx ny nz f_dc_0..2 f_rest_0..44 opacity scale_0..2 rot_0..3`, and the normals are unused
+ * and sometimes absent — so a reader that hard-codes offsets reads a file that is one property
+ * short as garbage, silently, at every field after the gap.
+ */
+function parseHeader(bytes) {
+    /* Latin-1 rather than UTF-8: the header is ASCII and the body is not text, so decoding the whole
+       buffer as UTF-8 can throw on a byte sequence that is simply a float. */
+    const text = new TextDecoder('latin1').decode(bytes.subarray(0, Math.min(bytes.length, 65536)));
+    const endsAt = text.indexOf(HEADER_END);
+    if (endsAt < 0) {
+        throw new Error(`no \`${HEADER_END}\` in the first ${Math.min(bytes.length, 65536)} bytes, so this is not a ` +
+            'PLY this reader understands.');
+    }
+    /* Past the marker and its line ending, which is \n or \r\n depending on the writer. */
+    const afterMarker = endsAt + HEADER_END.length;
+    let bodyAt = afterMarker;
+    if (text[bodyAt] === '\r')
+        bodyAt++;
+    if (text[bodyAt] === '\n')
+        bodyAt++;
+    const lines = text
+        .slice(0, endsAt)
+        .split(/\r?\n/)
+        .map((line) => line.trim());
+    if ((lines[0] ?? '') !== 'ply')
+        throw new Error('the first line of a PLY is `ply`; this one is not.');
+    const format = lines.find((line) => line.startsWith('format '));
+    if (format === undefined)
+        throw new Error('the header declares no `format` line.');
+    if (format !== 'format binary_little_endian 1.0') {
+        throw new Error(`this reader takes \`format binary_little_endian 1.0\` and the file says \`${format}\`. ` +
+            'An ASCII or big-endian body is refused rather than misread, because a silent misread of a ' +
+            'two-hundred-megabyte capture is worse than a stop.');
+    }
+    /*
+     * Only the `vertex` element carries splats. Other elements are skipped entirely rather than
+     * parsed: a capture that also declares faces is still a capture, and this reader has no use for
+     * them — but their properties must not land in the vertex stride.
+     */
+    const properties = new Map();
+    let count = -1;
+    let stride = 0;
+    let inVertex = false;
+    let sphericalHarmonics = 0;
+    for (const line of lines) {
+        if (line.startsWith('element ')) {
+            const [, name, howMany] = line.split(/\s+/);
+            inVertex = name === 'vertex';
+            if (inVertex)
+                count = Number(howMany);
+            continue;
+        }
+        if (!inVertex || !line.startsWith('property '))
+            continue;
+        const [, type, name] = line.split(/\s+/);
+        if (type === 'list') {
+            throw new Error('a `property list` in the vertex element gives every splat a different size, which this ' +
+                'reader does not handle. A Gaussian capture has none.');
+        }
+        const scalar = SCALARS[type ?? ''];
+        if (scalar === undefined)
+            throw new Error(`unknown PLY scalar type \`${type}\`.`);
+        if (name === undefined)
+            throw new Error(`a \`property ${type}\` line names no property.`);
+        properties.set(name, { name, offset: stride, read: scalar.read });
+        /* Located and counted, never read: view-dependent colour is out of this row's scope, and
+           knowing a capture carries the coefficients is what makes adding it a reader change. */
+        if (name.startsWith('f_rest_'))
+            sphericalHarmonics++;
+        stride += scalar.bytes;
+    }
+    if (count < 0)
+        throw new Error('the header declares no `vertex` element.');
+    return { count, stride, properties, bodyAt, sphericalHarmonics };
+}
+function require_(header, name) {
+    const found = header.properties.get(name);
+    if (found === undefined) {
+        throw new Error(`the vertex element declares no \`${name}\`, which a Gaussian capture must carry. ` +
+            `It declares: ${[...header.properties.keys()].slice(0, 12).join(', ')}…`);
+    }
+    return found;
+}
+/**
+ * Read a `.ply` Gaussian capture.
+ *
+ * **The encodings are the whole of this function's risk.** Scale is stored as its *logarithm* and
+ * opacity as its *logit*, so both are undone here — and here only, because `packSplats` documents
+ * that it takes linear values. Getting the boundary wrong produces a capture that is either
+ * invisible or a solid block, and both have been reported against other viewers as rendering bugs.
+ *
+ * **The file stores rotation as wxyz** — `rot_0` is the real part — and `SplatSource` takes xyzw,
+ * so the reorder happens here for the same reason it happens in the `.splat` reader.
+ */
+export function readSplatPly(buffer) {
+    const bytes = new Uint8Array(buffer);
+    const header = parseHeader(bytes);
+    const { count, stride, bodyAt } = header;
+    const needed = bodyAt + count * stride;
+    if (buffer.byteLength < needed) {
+        throw new Error(`the header declares ${count} vertices of ${stride} bytes after a ${bodyAt}-byte header, ` +
+            `which needs ${needed} bytes; the file is ${buffer.byteLength}. It is truncated.`);
+    }
+    const x = require_(header, 'x');
+    const y = require_(header, 'y');
+    const z = require_(header, 'z');
+    const dc0 = require_(header, 'f_dc_0');
+    const dc1 = require_(header, 'f_dc_1');
+    const dc2 = require_(header, 'f_dc_2');
+    const alpha = require_(header, 'opacity');
+    const s0 = require_(header, 'scale_0');
+    const s1 = require_(header, 'scale_1');
+    const s2 = require_(header, 'scale_2');
+    const r0 = require_(header, 'rot_0');
+    const r1 = require_(header, 'rot_1');
+    const r2 = require_(header, 'rot_2');
+    const r3 = require_(header, 'rot_3');
+    /*
+     * The l=1 band, if the file has one, and **the transpose that finding it needs**.
+     *
+     * A training run writes `f_rest_*` **channel-major**: all of red's coefficients, then all of
+     * green's, then all of blue's. So the per-channel stride is the total over three, and the l=1
+     * band is the first three of each channel — `f_rest_0..2`, then `f_rest_{n}..{n+2}`, then
+     * `f_rest_{2n}..{2n+2}` — where `n` is 3 at degree 1, 8 at degree 2 and 15 at degree 3.
+     *
+     * **Reading them as if they were interleaved is the failure to expect**, because it produces a
+     * capture that is plausible from a distance: the nine values are all real coefficients of
+     * *something*, so the cloud still has a sheen, and it is the wrong sheen in the wrong channel.
+     * The count is checked against a multiple of three rather than trusted, and a file whose
+     * `f_rest_*` count is not divisible by three is read as having no harmonics at all.
+     */
+    const perChannel = Math.floor(header.sphericalHarmonics / 3);
+    const wantsSh = header.sphericalHarmonics > 0 &&
+        header.sphericalHarmonics % 3 === 0 &&
+        perChannel >= SH1_PER_CHANNEL;
+    const restBands = [];
+    if (wantsSh) {
+        for (let channel = 0; channel < 3; channel++) {
+            for (let band = 0; band < SH1_PER_CHANNEL; band++) {
+                const property = header.properties.get(`f_rest_${channel * perChannel + band}`);
+                if (property === undefined) {
+                    restBands.length = 0;
+                    break;
+                }
+                restBands.push(property);
+            }
+            if (restBands.length === 0)
+                break;
+        }
+    }
+    const hasSh = restBands.length === SH1_PER_CHANNEL * 3;
+    const sh1 = hasSh ? new Float32Array(count * SPLAT_SH1_COEFFICIENTS) : undefined;
+    const view = new DataView(buffer);
+    const positions = new Float32Array(count * 3);
+    const scales = new Float32Array(count * 3);
+    const rotations = new Float32Array(count * 4);
+    const colors = new Float32Array(count * 3);
+    const opacities = new Float32Array(count);
+    const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+    for (let index = 0; index < count; index++) {
+        const at = bodyAt + index * stride;
+        const p = index * 3;
+        positions[p] = x.read(view, at + x.offset);
+        positions[p + 1] = y.read(view, at + y.offset);
+        positions[p + 2] = z.read(view, at + z.offset);
+        /* Stored as a logarithm, so the standard deviation is its exponential. */
+        scales[p] = Math.exp(s0.read(view, at + s0.offset));
+        scales[p + 1] = Math.exp(s1.read(view, at + s1.offset));
+        scales[p + 2] = Math.exp(s2.read(view, at + s2.offset));
+        colors[p] = clamp01(0.5 + SH_C0 * dc0.read(view, at + dc0.offset));
+        colors[p + 1] = clamp01(0.5 + SH_C0 * dc1.read(view, at + dc1.offset));
+        colors[p + 2] = clamp01(0.5 + SH_C0 * dc2.read(view, at + dc2.offset));
+        /* Stored as a logit, so the opacity is its logistic. */
+        opacities[index] = 1 / (1 + Math.exp(-alpha.read(view, at + alpha.offset)));
+        const r = index * 4;
+        rotations[r] = r1.read(view, at + r1.offset);
+        rotations[r + 1] = r2.read(view, at + r2.offset);
+        rotations[r + 2] = r3.read(view, at + r3.offset);
+        rotations[r + 3] = r0.read(view, at + r0.offset);
+        /*
+         * Channel-major in the file, basis-major in `SplatSource` — the transpose the block above
+         * describes, in the one loop that touches the file's own order.
+         */
+        if (sh1 !== undefined) {
+            const to = index * SPLAT_SH1_COEFFICIENTS;
+            for (let band = 0; band < SH1_PER_CHANNEL; band++) {
+                for (let channel = 0; channel < 3; channel++) {
+                    const property = restBands[channel * SH1_PER_CHANNEL + band];
+                    sh1[to + band * 3 + channel] =
+                        property === undefined ? 0 : property.read(view, at + property.offset);
+                }
+            }
+        }
+    }
+    const data = packSplats({
+        count,
+        positions,
+        scales,
+        rotations,
+        colors,
+        opacities,
+        ...(sh1 === undefined ? {} : { sh1 }),
+    });
+    return { ...data, sphericalHarmonics: header.sphericalHarmonics };
+}

package/dist/splatSog.d.ts

@@ -0,0 +1,110 @@
+/**
+ * The `.sog` reader: a ZIP of lossless WebP images and a manifest that says what each channel is.
+ *
+ * **SOG is a container, and the name is shared with the technique it grew out of.** The row that
+ * asked for this pointed at `fraunhoferhhi/Self-Organizing-Gaussians`, which is the ECCV 2024 paper
+ * that sorts Gaussian parameters into a 2D grid so that ordinary image compression can carry them.
+ * That paper ships pre-trained scenes and a script that decompresses them to `.ply`, and documents
+ * no on-disk `.sog` structure at all. What capture tools emit is the container specified by
+ * PlayCanvas and open-sourced with `splat-transform`, and this file reads *that*: version 2, a
+ * `meta.json` naming its images, and a fixed encoding per property.
+ *
+ * A reader built against the paper would decode something no tool produces. The distinction is
+ * recorded here because it cost an afternoon to find and the next person should start with it.
+ *
+ * ## Two capabilities this cannot supply itself
+ *
+ * **WebP decode**, which is `WebpDecoder` below and is a parameter rather than a dependency. Every
+ * browser has a decoder; Node has none, and the alternative to asking for one is a WebP decoder in
+ * this package, which is `AGENTS.md`'s "do not add dependencies" arriving as a thousand lines of
+ * vendored VP8L instead. `browserWebpDecoder` is the ordinary implementation, exactly as
+ * `BrowserStore` is for `KeyValueStore` — and it forwards to core rather than reaching for a
+ * canvas, for a measured reason its own note carries.
+ *
+ * **Inflate**, if a producer ever deflates. `splat-transform` 3.3.3 stores every entry
+ * uncompressed — the images are already compressed and a second pass buys nothing — so the common
+ * path needs no inflate at all, and `DecompressionStream` covers the other one. It is in every
+ * browser and in Node 18, which is under this engine's floor.
+ */
+import type { SplatData, SplatSource } from './splatData.ts';
+/** The container version this reader understands. */
+export declare const SOG_VERSION = 2;
+/** What a `.sog` manifest declares. Field names are the file's, not this engine's. */
+export interface SogMeta {
+    readonly version: number;
+    readonly count: number;
+    readonly asset?: {
+        readonly generator?: string;
+    };
+    readonly antialias?: boolean;
+    readonly means: {
+        readonly mins: readonly number[];
+        readonly maxs: readonly number[];
+        readonly files: readonly string[];
+    };
+    readonly scales: {
+        readonly codebook: readonly number[];
+        readonly files: readonly string[];
+    };
+    readonly quats: {
+        readonly files: readonly string[];
+    };
+    readonly sh0: {
+        readonly codebook: readonly number[];
+        readonly files: readonly string[];
+    };
+    /** Absent where the capture carries no bands past the DC term, which is the common case. */
+    readonly shN?: {
+        readonly count: number;
+        readonly bands: number;
+        readonly codebook: readonly number[];
+        readonly files: readonly string[];
+    };
+}
+/** One decoded image: 8-bit RGBA, row-major from the top left, four bytes a texel. */
+export interface DecodedImage {
+    readonly width: number;
+    readonly height: number;
+    readonly rgba: Uint8Array | Uint8ClampedArray;
+}
+/** What turns a WebP file's bytes into texels. See this file's header for why it is a parameter. */
+export type WebpDecoder = (bytes: Uint8Array) => Promise<DecodedImage>;
+/**
+ * Unpack a bundled `.sog`, which is a ZIP with every file at the root.
+ *
+ * **Read through the central directory and never through the local headers**, and that is not
+ * defensive: `splat-transform` writes its entries streaming, so bit 3 of the general-purpose flags
+ * is set and every local header carries a compressed size of *zero* with the real sizes in a data
+ * descriptor after the payload. A reader that trusted the local header would extract nothing from
+ * every file a capture tool has produced. Measured on a file that tool wrote: flags `0x808`, sizes
+ * zero in the local header and correct in the central directory.
+ *
+ * Only the two methods the format can produce: stored, which is what `splat-transform` writes
+ * because the images are already compressed, and deflate, through `DecompressionStream`.
+ */
+export declare function unbundleSog(bundle: ArrayBuffer): Promise<Map<string, Uint8Array>>;
+/** Parse and check a `meta.json`. Refuses a version it does not understand rather than guessing. */
+export declare function readSogMeta(bytes: Uint8Array | string): SogMeta;
+/** The files a capture is made of, by the names its manifest gives them. */
+export type SogFiles = ReadonlyMap<string, Uint8Array>;
+/**
+ * Read a `.sog` capture into a `SplatSource`.
+ *
+ * `files` is what `unbundleSog` returns for a bundle, or the files of an unbundled capture keyed by
+ * the names its `meta.json` uses. `decode` turns one WebP into texels; see `browserWebpDecoder`.
+ *
+ * **Every per-Gaussian property is co-located**: the texel at `(x, y)` means the same Gaussian in
+ * every image, and the Gaussians run row-major from the top left. So one index walks all of them,
+ * which is the property that makes this reader a single loop and is also the property a reader that
+ * transposed one image would break silently.
+ */
+export declare function readSplatSog(files: SogFiles, decode: WebpDecoder): Promise<SplatData>;
+/**
+ * The same read, stopping one step short: the linear values, before they are packed for the GPU.
+ *
+ * **Exported because the packing is lossy and a check has to see what was decoded**, not what
+ * survived a half-float. `splatSog.test.ts` compares sixty-four Gaussians against the `.ply` they
+ * were encoded from and needs metres and quaternions to do it; a consumer transforming a capture
+ * before it is uploaded wants the same thing, which is why this is public rather than internal.
+ */
+export declare function readSogSource(files: SogFiles, decode: WebpDecoder): Promise<SplatSource>;

package/dist/splatSog.js

@@ -0,0 +1,285 @@
+/**
+ * The `.sog` reader: a ZIP of lossless WebP images and a manifest that says what each channel is.
+ *
+ * **SOG is a container, and the name is shared with the technique it grew out of.** The row that
+ * asked for this pointed at `fraunhoferhhi/Self-Organizing-Gaussians`, which is the ECCV 2024 paper
+ * that sorts Gaussian parameters into a 2D grid so that ordinary image compression can carry them.
+ * That paper ships pre-trained scenes and a script that decompresses them to `.ply`, and documents
+ * no on-disk `.sog` structure at all. What capture tools emit is the container specified by
+ * PlayCanvas and open-sourced with `splat-transform`, and this file reads *that*: version 2, a
+ * `meta.json` naming its images, and a fixed encoding per property.
+ *
+ * A reader built against the paper would decode something no tool produces. The distinction is
+ * recorded here because it cost an afternoon to find and the next person should start with it.
+ *
+ * ## Two capabilities this cannot supply itself
+ *
+ * **WebP decode**, which is `WebpDecoder` below and is a parameter rather than a dependency. Every
+ * browser has a decoder; Node has none, and the alternative to asking for one is a WebP decoder in
+ * this package, which is `AGENTS.md`'s "do not add dependencies" arriving as a thousand lines of
+ * vendored VP8L instead. `browserWebpDecoder` is the ordinary implementation, exactly as
+ * `BrowserStore` is for `KeyValueStore` — and it forwards to core rather than reaching for a
+ * canvas, for a measured reason its own note carries.
+ *
+ * **Inflate**, if a producer ever deflates. `splat-transform` 3.3.3 stores every entry
+ * uncompressed — the images are already compressed and a second pass buys nothing — so the common
+ * path needs no inflate at all, and `DecompressionStream` covers the other one. It is in every
+ * browser and in Node 18, which is under this engine's floor.
+ */
+import { SPLAT_SH1_COEFFICIENTS, packSplats } from './splatData.js';
+/**
+ * The band-0 constant, `0.5 * sqrt(1 / pi)`.
+ *
+ * The same number `splatPly.ts` carries and for the same reason: a capture stores colour as the DC
+ * term of a spherical-harmonic expansion, which is signed radiance rather than a colour, and
+ * `0.5 + C0 * dc` is the conversion. Duplicated rather than shared because each reader states the
+ * encoding it is undoing, and this one undoes a codebook lookup first.
+ */
+const SH_C0 = 0.28209479177387814;
+/** The container version this reader understands. */
+export const SOG_VERSION = 2;
+/* ------------------------------------------------------------------ the zip */
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_SIGNATURE = 0x02014b50;
+/** The end-of-central-directory record with no comment. A comment may follow, up to 65535 bytes. */
+const EOCD_BYTES = 22;
+/**
+ * Unpack a bundled `.sog`, which is a ZIP with every file at the root.
+ *
+ * **Read through the central directory and never through the local headers**, and that is not
+ * defensive: `splat-transform` writes its entries streaming, so bit 3 of the general-purpose flags
+ * is set and every local header carries a compressed size of *zero* with the real sizes in a data
+ * descriptor after the payload. A reader that trusted the local header would extract nothing from
+ * every file a capture tool has produced. Measured on a file that tool wrote: flags `0x808`, sizes
+ * zero in the local header and correct in the central directory.
+ *
+ * Only the two methods the format can produce: stored, which is what `splat-transform` writes
+ * because the images are already compressed, and deflate, through `DecompressionStream`.
+ */
+export async function unbundleSog(bundle) {
+    const view = new DataView(bundle);
+    const bytes = new Uint8Array(bundle);
+    let eocd = -1;
+    const earliest = Math.max(0, bundle.byteLength - EOCD_BYTES - 0xffff);
+    for (let at = bundle.byteLength - EOCD_BYTES; at >= earliest; at--) {
+        if (view.getUint32(at, true) === EOCD_SIGNATURE) {
+            eocd = at;
+            break;
+        }
+    }
+    if (eocd < 0) {
+        throw new Error('splatSog: this is not a bundled `.sog`. A bundle is a ZIP and no end-of-central-directory ' +
+            'record was found — an unbundled capture is a `meta.json` beside its images, which ' +
+            '`readSplatSog` takes directly.');
+    }
+    const entries = view.getUint16(eocd + 10, true);
+    let at = view.getUint32(eocd + 16, true);
+    const files = new Map();
+    for (let i = 0; i < entries; i++) {
+        if (view.getUint32(at, true) !== CENTRAL_SIGNATURE) {
+            throw new Error(`splatSog: the central directory entry ${i} is not one.`);
+        }
+        const method = view.getUint16(at + 10, true);
+        const compressed = view.getUint32(at + 20, true);
+        const uncompressed = view.getUint32(at + 24, true);
+        const nameLength = view.getUint16(at + 28, true);
+        const extraLength = view.getUint16(at + 30, true);
+        const commentLength = view.getUint16(at + 32, true);
+        const localAt = view.getUint32(at + 42, true);
+        const name = new TextDecoder().decode(bytes.subarray(at + 46, at + 46 + nameLength));
+        at += 46 + nameLength + extraLength + commentLength;
+        /* The local header's own name and extra lengths, which are the only two of its fields a
+           streaming writer fills in truthfully. Everything else comes from the directory above. */
+        const localName = view.getUint16(localAt + 26, true);
+        const localExtra = view.getUint16(localAt + 28, true);
+        const from = localAt + 30 + localName + localExtra;
+        const payload = bytes.subarray(from, from + compressed);
+        if (method === 0) {
+            files.set(name, payload);
+        }
+        else if (method === 8) {
+            files.set(name, await inflateRaw(payload, uncompressed));
+        }
+        else {
+            throw new Error(`splatSog: \`${name}\` uses ZIP method ${method}, which is neither stored nor deflate.`);
+        }
+    }
+    return files;
+}
+async function inflateRaw(payload, expected) {
+    const stream = new Blob([payload])
+        .stream()
+        .pipeThrough(new DecompressionStream('deflate-raw'));
+    const out = new Uint8Array(await new Response(stream).arrayBuffer());
+    if (expected !== 0 && out.byteLength !== expected) {
+        throw new Error(`splatSog: an entry inflated to ${out.byteLength} bytes where the directory says ${expected}.`);
+    }
+    return out;
+}
+/* ------------------------------------------------------------- the manifest */
+/** Parse and check a `meta.json`. Refuses a version it does not understand rather than guessing. */
+export function readSogMeta(bytes) {
+    const text = typeof bytes === 'string' ? bytes : new TextDecoder().decode(bytes);
+    const meta = JSON.parse(text);
+    if (meta.version !== SOG_VERSION) {
+        throw new Error(`splatSog: this manifest declares version ${String(meta.version)} and this reader ` +
+            `implements ${SOG_VERSION}. The encodings are versioned, so reading it anyway would ` +
+            'produce a plausible cloud rather than an error.');
+    }
+    if (!Number.isFinite(meta.count) || meta.count <= 0) {
+        throw new Error('splatSog: the manifest declares no `count`.');
+    }
+    for (const name of ['means', 'scales', 'quats', 'sh0']) {
+        if (meta[name] === undefined)
+            throw new Error(`splatSog: the manifest declares no \`${name}\`.`);
+    }
+    return meta;
+}
+/* --------------------------------------------------------- the dequantisers */
+/**
+ * A position's own inverse, and it is not the obvious one.
+ *
+ * **Positions are stored in a signed logarithmic domain**, so that a capture's dense middle gets
+ * the resolution and its far outliers do not spend it: what is quantised is
+ * `sign(x) * log(1 + |x|)`, and `mins`/`maxs` in the manifest are in *that* domain rather than in
+ * metres. Read as metres they are wrong by an exponential, which does not look like an error — it
+ * looks like a cloud that has been squashed toward its own centre.
+ */
+function unlog(n) {
+    return Math.sign(n) * (Math.exp(Math.abs(n)) - 1);
+}
+/**
+ * The smallest-three quaternion, whose fourth component the file does not store.
+ *
+ * Three components quantised into `[-sqrt(2)/2, +sqrt(2)/2]` and an alpha of 252 to 255 saying
+ * which one was dropped — it is always the largest, so the reconstructed one is non-negative and
+ * the sign is not ambiguous. The order the three are read back into is the *rotation* of the
+ * component list past the dropped one, which is what makes 252 mean w and 255 mean z.
+ */
+const QUAT_SCALE = Math.SQRT2;
+function unpackQuaternion(r, g, b, mode, out, at) {
+    const a = (r / 255 - 0.5) * QUAT_SCALE;
+    const c = (g / 255 - 0.5) * QUAT_SCALE;
+    const d = (b / 255 - 0.5) * QUAT_SCALE;
+    const largest = Math.sqrt(Math.max(0, 1 - a * a - c * c - d * d));
+    /* wxyz as the file thinks of it, with the dropped component put back where it belongs. */
+    const wxyz = [0, 0, 0, 0];
+    const dropped = mode - 252;
+    const rest = [a, c, d];
+    let k = 0;
+    for (let i = 0; i < 4; i++)
+        wxyz[i] = i === dropped ? largest : (rest[k++] ?? 0);
+    /* And out as xyzw, which is what `SplatSource` takes. See its own note on the two conventions. */
+    out[at] = wxyz[1] ?? 0;
+    out[at + 1] = wxyz[2] ?? 0;
+    out[at + 2] = wxyz[3] ?? 0;
+    out[at + 3] = wxyz[0] ?? 0;
+}
+/**
+ * Read a `.sog` capture into a `SplatSource`.
+ *
+ * `files` is what `unbundleSog` returns for a bundle, or the files of an unbundled capture keyed by
+ * the names its `meta.json` uses. `decode` turns one WebP into texels; see `browserWebpDecoder`.
+ *
+ * **Every per-Gaussian property is co-located**: the texel at `(x, y)` means the same Gaussian in
+ * every image, and the Gaussians run row-major from the top left. So one index walks all of them,
+ * which is the property that makes this reader a single loop and is also the property a reader that
+ * transposed one image would break silently.
+ */
+export async function readSplatSog(files, decode) {
+    return packSplats(await readSogSource(files, decode));
+}
+/**
+ * The same read, stopping one step short: the linear values, before they are packed for the GPU.
+ *
+ * **Exported because the packing is lossy and a check has to see what was decoded**, not what
+ * survived a half-float. `splatSog.test.ts` compares sixty-four Gaussians against the `.ply` they
+ * were encoded from and needs metres and quaternions to do it; a consumer transforming a capture
+ * before it is uploaded wants the same thing, which is why this is public rather than internal.
+ */
+export async function readSogSource(files, decode) {
+    const metaBytes = files.get('meta.json');
+    if (metaBytes === undefined)
+        throw new Error('splatSog: the capture has no `meta.json`.');
+    const meta = readSogMeta(metaBytes);
+    const image = async (name) => {
+        const bytes = files.get(name);
+        if (bytes === undefined) {
+            throw new Error(`splatSog: the manifest names \`${name}\` and the capture does not carry it. ` +
+                `It carries: ${[...files.keys()].join(', ')}`);
+        }
+        return decode(bytes);
+    };
+    const [meansLow, meansHigh, scales, quats, sh0] = await Promise.all([
+        image(meta.means.files[0] ?? 'means_l.webp'),
+        image(meta.means.files[1] ?? 'means_u.webp'),
+        image(meta.scales.files[0] ?? 'scales.webp'),
+        image(meta.quats.files[0] ?? 'quats.webp'),
+        image(meta.sh0.files[0] ?? 'sh0.webp'),
+    ]);
+    const count = meta.count;
+    const positions = new Float32Array(count * 3);
+    const scaleOut = new Float32Array(count * 3);
+    const rotations = new Float32Array(count * 4);
+    const colors = new Float32Array(count * 3);
+    const opacities = new Float32Array(count);
+    const scaleBook = meta.scales.codebook;
+    const colourBook = meta.sh0.codebook;
+    const mins = meta.means.mins;
+    const maxs = meta.means.maxs;
+    for (let i = 0; i < count; i++) {
+        const t = i * 4;
+        for (let axis = 0; axis < 3; axis++) {
+            /* Sixteen bits per axis, split across two images: the low byte and the high one. */
+            const q = ((meansHigh.rgba[t + axis] ?? 0) << 8) | (meansLow.rgba[t + axis] ?? 0);
+            const lo = mins[axis] ?? 0;
+            const hi = maxs[axis] ?? 0;
+            positions[i * 3 + axis] = unlog(lo + (hi - lo) * (q / 65535));
+            /* The codebook is in the log domain, exactly as a `.ply`'s `scale_n` is. */
+            scaleOut[i * 3 + axis] = Math.exp(scaleBook[scales.rgba[t + axis] ?? 0] ?? 0);
+            /* And the colour's codebook is a DC coefficient, so it takes the band constant. */
+            colors[i * 3 + axis] = 0.5 + (colourBook[sh0.rgba[t + axis] ?? 0] ?? 0) * SH_C0;
+        }
+        unpackQuaternion(quats.rgba[t] ?? 0, quats.rgba[t + 1] ?? 0, quats.rgba[t + 2] ?? 0, quats.rgba[t + 3] ?? 252, rotations, i * 4);
+        /* Opacity is linear in alpha here, where a `.ply` stores its logit. */
+        opacities[i] = (sh0.rgba[t + 3] ?? 0) / 255;
+    }
+    const source = { count, positions, scales: scaleOut, rotations, colors, opacities };
+    const sh1 = await readSh1(meta, image, count);
+    return sh1 === null ? source : { ...source, sh1 };
+}
+/**
+ * The l=1 band, out of the palette the container stores it in, or null where there is none.
+ *
+ * **A capture's higher bands are a palette and an index per Gaussian**, not a value per Gaussian:
+ * `shN_labels` is a sixteen-bit index into `shN_centroids`, whose rows hold 64 palette entries and
+ * whose width is the band count times three. Only the l=1 coefficients are read, because that is
+ * what `SplatSource.sh1` carries and what this engine's shader evaluates — degrees 2 and 3 are
+ * declined against a measured bandwidth figure, which `docs/IMPROVEMENTS.md` records with its
+ * number.
+ */
+async function readSh1(meta, image, count) {
+    const shN = meta.shN;
+    if (shN === undefined || shN.bands < 1)
+        return null;
+    const centroids = await image(shN.files[0] ?? 'shN_centroids.webp');
+    const labels = await image(shN.files[1] ?? 'shN_labels.webp');
+    const book = shN.codebook;
+    /* Three coefficients a band for l=1, one palette entry per row of `coefficients` pixels. */
+    const coefficients = shN.bands * (shN.bands + 2);
+    const out = new Float32Array(count * SPLAT_SH1_COEFFICIENTS);
+    for (let i = 0; i < count; i++) {
+        const label = (labels.rgba[i * 4] ?? 0) | ((labels.rgba[i * 4 + 1] ?? 0) << 8);
+        const entry = label * coefficients;
+        /* Interleaved by basis function and then by channel, which is what `SplatSource.sh1` takes and
+           is not how the palette stores it: the palette is one pixel per coefficient, RGB in it. */
+        for (let basis = 0; basis < 3; basis++) {
+            const at = (entry + basis) * 4;
+            for (let channel = 0; channel < 3; channel++) {
+                out[i * SPLAT_SH1_COEFFICIENTS + basis * 3 + channel] =
+                    book[centroids.rgba[at + channel] ?? 0] ?? 0;
+            }
+        }
+    }
+    return out;
+}

package/dist/splatSogDecoder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The ordinary WebP decoder for `.sog` captures, which lives here and not beside the reader.
+ *
+ * **Its own module because it is the reader's only reason to name `@driftengine/core`**, and that
+ * import has two costs worth avoiding: a consumer supplying its own decoder should not pull core
+ * through this path, and `scripts/sog-reader.test.mjs` runs under Node's strip-only mode, where an
+ * import that resolves through a `node_modules` symlink is refused outright — which is the trap
+ * `docs/IMPROVEMENTS.md` records under proving a package from its tarball. The reader itself
+ * imports nothing but its own package, so the test loads it and this file stays out of the way.
+ */
+import type { WebpDecoder } from './splatSog.ts';
+/**
+ * The ordinary decoder: `@driftengine/core`'s exact texel read.
+ *
+ * **A thin forward, and the reason it is not implemented here is worth reading before anybody
+ * inlines it.** Every browser API that hands back an image's pixels without a GPU premultiplies
+ * on the way through — a 2D canvas by storing premultiplied, WebCodecs by decoding a WebP with
+ * alpha to a premultiplied `BGRA` frame — so every RGB value comes back through
+ * `round(round(c * a / 255) * 255 / a)`. On the committed fixture that is 3 of 255 out on
+ * `sh0.webp`, whose RGB are *codebook indices* and whose alpha is the opacity: an index several
+ * entries away wherever a Gaussian is transparent. `createImageTexelDecoder` reads the same file
+ * exactly, and it lives in core because it is raw WebGL and `AGENTS.md` allows that only there.
+ *
+ * A consumer with its own decoder passes it instead; that is what the parameter is for.
+ */
+export declare function browserWebpDecoder(): WebpDecoder;