@driftengine/capture 4.0.0

package/dist/gaussians/adam.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Adam over a cloud's parameters, one moment pair per number.
+ *
+ * **Why Adam and not a plain descent.** The six families being fitted are in wildly different
+ * units — metres, logarithms of metres, a quaternion, a colour on nought to one — and a single
+ * step size that suits one of them moves another by nothing or by everything. Adam divides each
+ * number's step by the size of its own recent gradients, so a rate here is a *fraction of the
+ * parameter's own scale* and the families become comparable. It is also what makes the loss's
+ * absolute size irrelevant: a frame of a million pixels and one of a thousand descend alike.
+ *
+ * **The bias correction is a running product rather than a power.** `β₁ⁿ` would want `**`, which
+ * `packages/capture` may not use — the determinism gate refuses it, because an exponent is one of
+ * the operations a platform may round its own way. Multiplying by β each step is the same number
+ * by the same arithmetic the rest of the fit uses.
+ */
+/**
+ * One optimised family: the values, their gradient, and Adam's two moments.
+ *
+ * Every array is allocated at the cloud's budget and used to `count * stride`, because the budget
+ * is the one thing the cloud may not exceed — so densification never reallocates and a plan can
+ * gather into the same arrays it reads.
+ */
+export interface Family {
+    /** Numbers per Gaussian. */
+    readonly stride: number;
+    /** The step size, as a fraction of what this family's own gradients have been. */
+    readonly rate: number;
+    readonly values: Float64Array;
+    readonly gradient: Float64Array;
+    readonly moment: Float64Array;
+    readonly second: Float64Array;
+}
+export declare function createFamily(stride: number, rate: number, budget: number): Family;
+/** How far into the decay the fit is: β₁ⁿ and β₂ⁿ, carried rather than raised. */
+export interface AdamState {
+    unbias1: number;
+    unbias2: number;
+}
+export declare function createAdamState(): AdamState;
+/**
+ * One step over every family, on the gradients standing in them.
+ *
+ * **The gradient is read and not owned**: the caller writes every number of it before every step,
+ * so there is nothing here to clear. A caller that accumulated into it instead would need that
+ * clear back, and would be the one to add it.
+ */
+export declare function adamStep(families: readonly Family[], count: number, state: AdamState): void;
+/**
+ * Rewrite every family by a plan: slot `i` takes its values from `sources[i]`.
+ *
+ * **A slot marked fresh starts Adam over.** A Gaussian that was just split off its parent has none
+ * of that parent's history — its gradients are about to be different ones — and carrying the
+ * moments across would take a step sized for a shape that no longer exists. The reference
+ * implementation zeroes them for the same reason, and it is also what separates two halves of a
+ * split: identical values with identical moments receive identical steps forever.
+ */
+export declare function gather(families: readonly Family[], sources: Int32Array, fresh: Uint8Array, count: number, scratch: Float64Array): void;

package/dist/gaussians/adam.js

@@ -0,0 +1,88 @@
+/**
+ * Adam over a cloud's parameters, one moment pair per number.
+ *
+ * **Why Adam and not a plain descent.** The six families being fitted are in wildly different
+ * units — metres, logarithms of metres, a quaternion, a colour on nought to one — and a single
+ * step size that suits one of them moves another by nothing or by everything. Adam divides each
+ * number's step by the size of its own recent gradients, so a rate here is a *fraction of the
+ * parameter's own scale* and the families become comparable. It is also what makes the loss's
+ * absolute size irrelevant: a frame of a million pixels and one of a thousand descend alike.
+ *
+ * **The bias correction is a running product rather than a power.** `β₁ⁿ` would want `**`, which
+ * `packages/capture` may not use — the determinism gate refuses it, because an exponent is one of
+ * the operations a platform may round its own way. Multiplying by β each step is the same number
+ * by the same arithmetic the rest of the fit uses.
+ */
+const BETA1 = 0.9;
+const BETA2 = 0.999;
+const EPSILON = 1e-8;
+export function createFamily(stride, rate, budget) {
+    return {
+        stride,
+        rate,
+        values: new Float64Array(budget * stride),
+        gradient: new Float64Array(budget * stride),
+        moment: new Float64Array(budget * stride),
+        second: new Float64Array(budget * stride),
+    };
+}
+export function createAdamState() {
+    return { unbias1: 1, unbias2: 1 };
+}
+/**
+ * One step over every family, on the gradients standing in them.
+ *
+ * **The gradient is read and not owned**: the caller writes every number of it before every step,
+ * so there is nothing here to clear. A caller that accumulated into it instead would need that
+ * clear back, and would be the one to add it.
+ */
+export function adamStep(families, count, state) {
+    state.unbias1 *= BETA1;
+    state.unbias2 *= BETA2;
+    const correction1 = 1 - state.unbias1;
+    const correction2 = 1 - state.unbias2;
+    for (const family of families) {
+        const { values, gradient, moment, second, rate, stride } = family;
+        const end = count * stride;
+        for (let at = 0; at < end; at += 1) {
+            const g = gradient[at];
+            const m = BETA1 * moment[at] + (1 - BETA1) * g;
+            const v = BETA2 * second[at] + (1 - BETA2) * g * g;
+            moment[at] = m;
+            second[at] = v;
+            values[at] =
+                values[at] -
+                    (rate * (m / correction1)) / (Math.sqrt(v / correction2) + EPSILON);
+        }
+    }
+}
+/**
+ * Rewrite every family by a plan: slot `i` takes its values from `sources[i]`.
+ *
+ * **A slot marked fresh starts Adam over.** A Gaussian that was just split off its parent has none
+ * of that parent's history — its gradients are about to be different ones — and carrying the
+ * moments across would take a step sized for a shape that no longer exists. The reference
+ * implementation zeroes them for the same reason, and it is also what separates two halves of a
+ * split: identical values with identical moments receive identical steps forever.
+ */
+export function gather(families, sources, fresh, count, scratch) {
+    for (const family of families) {
+        gatherArray(family.values, family.stride, sources, fresh, count, scratch, false);
+        gatherArray(family.moment, family.stride, sources, fresh, count, scratch, true);
+        gatherArray(family.second, family.stride, sources, fresh, count, scratch, true);
+    }
+}
+/** One array gathered through `scratch`, because a slot may take from a slot below itself. */
+function gatherArray(array, stride, sources, fresh, count, scratch, blankWhenFresh) {
+    for (let slot = 0; slot < count; slot += 1) {
+        const from = sources[slot] * stride;
+        for (let c = 0; c < stride; c += 1)
+            scratch[slot * stride + c] = array[from + c];
+    }
+    for (let slot = 0; slot < count; slot += 1) {
+        const blank = blankWhenFresh && fresh[slot] !== 0;
+        for (let c = 0; c < stride; c += 1) {
+            array[slot * stride + c] = blank ? 0 : scratch[slot * stride + c];
+        }
+    }
+}

package/dist/gaussians/depth.d.ts

@@ -0,0 +1,8 @@
+import { type GaussianSet, type RasterCamera } from './project.ts';
+/**
+ * The cloud's depth and coverage, one of each per pixel.
+ *
+ * A pixel no light reached is left at zero in both, which is a coverage of nothing rather than a
+ * surface at the camera — a caller reading the depth alone would find a wall in front of its face.
+ */
+export declare function renderDepth(set: GaussianSet, camera: RasterCamera, depth: Float32Array, coverage: Float32Array): void;

package/dist/gaussians/depth.js

@@ -0,0 +1,73 @@
+/**
+ * How far away a cloud of Gaussians is, a pixel at a time.
+ *
+ * **A splat cloud has no surface**, so there is no depth to read off it the way a triangle
+ * rasteriser reads one. What it has is light arriving from a sequence of overlapping blobs, and the
+ * honest answer is where that light came from: each splat's own depth, weighted by how much of the
+ * pixel it actually contributed. A nearly opaque splat in front takes almost all of the weight, so
+ * the answer is its depth; a thin haze in front of a wall averages towards the wall.
+ *
+ * **The coverage is answered beside it, and callers need both.** At a silhouette a cloud thins out
+ * and a pixel may be a tenth covered — a depth averaged out of a tenth of a pixel's light is not a
+ * measurement of anything, and a fusion that treated it as one would carve the silhouette into the
+ * volume. So this answers how much light arrived as well, and the fusion weights by it rather than
+ * choosing a cutoff here on the caller's behalf.
+ *
+ * **Depth along the camera's own axis, not along the ray.** That is what a projection's `z` is and
+ * what `fuseDepth` compares a voxel against; a radial distance would be a different quantity with
+ * the same name, which is the kind of mistake that reads as a scene slightly the wrong shape.
+ */
+import { exactExp } from '@driftengine/core';
+import { visibleGaussians, } from './project.js';
+/** Below this a Gaussian contributes less than a quarter of a value of an eight-bit channel. */
+const FAINT = 1 / 255 / 4;
+/**
+ * The cloud's depth and coverage, one of each per pixel.
+ *
+ * A pixel no light reached is left at zero in both, which is a coverage of nothing rather than a
+ * surface at the camera — a caller reading the depth alone would find a wall in front of its face.
+ */
+export function renderDepth(set, camera, depth, coverage) {
+    const { width, height } = camera;
+    depth.fill(0);
+    coverage.fill(0);
+    const pixels = width * height;
+    const transmittance = new Float64Array(pixels).fill(1);
+    const weighted = new Float64Array(pixels);
+    const { order, projected } = visibleGaussians(set, camera);
+    for (const at of order) {
+        const one = projected[at];
+        const determinant = one.a * one.d - one.b * one.b;
+        const inverse = [one.d / determinant, -one.b / determinant, one.a / determinant];
+        const left = Math.max(0, Math.floor(one.x - one.radius));
+        const right = Math.min(width - 1, Math.ceil(one.x + one.radius));
+        const top = Math.max(0, Math.floor(one.y - one.radius));
+        const bottom = Math.min(height - 1, Math.ceil(one.y + one.radius));
+        const opacity = set.opacities[at];
+        for (let y = top; y <= bottom; y += 1) {
+            for (let x = left; x <= right; x += 1) {
+                const dx = x + 0.5 - one.x;
+                const dy = y + 0.5 - one.y;
+                const power = -0.5 *
+                    (inverse[0] * dx * dx +
+                        2 * inverse[1] * dx * dy +
+                        inverse[2] * dy * dy);
+                const alpha = opacity * exactExp(power);
+                if (alpha < FAINT)
+                    continue;
+                const pixel = y * width + x;
+                const share = alpha * transmittance[pixel];
+                weighted[pixel] = weighted[pixel] + share * one.depth;
+                coverage[pixel] = coverage[pixel] + share;
+                transmittance[pixel] = transmittance[pixel] * (1 - alpha);
+            }
+        }
+    }
+    for (let pixel = 0; pixel < pixels; pixel += 1) {
+        const covered = coverage[pixel];
+        /* Divided by the light that arrived rather than by one: a half-covered pixel is still at the
+           depth of what covered it, and the caller is told how much that was. */
+        if (covered > 0)
+            depth[pixel] = weighted[pixel] / covered;
+    }
+}

package/dist/gaussians/gradients.d.ts

@@ -0,0 +1,36 @@
+import { type GaussianSet, type RasterCamera } from './project.ts';
+import type { Frame } from './rasterise.ts';
+/** Where the gradients go: one entry per parameter of every Gaussian. */
+export interface GaussianGradients {
+    /** Three per Gaussian. */
+    readonly positions: Float64Array;
+    readonly scales: Float64Array;
+    /** Four per Gaussian, xyzw. */
+    readonly rotations: Float64Array;
+    readonly colors: Float64Array;
+    /** Nine per Gaussian, and left at zero for a cloud with no band to fit. */
+    readonly sh1: Float64Array;
+    /**
+     * The gradients **as the screen sees them**, nine per Gaussian: the two of its centre in pixels,
+     * the three of its screen covariance, its opacity, and its resolved colour.
+     *
+     * Everything else here is a chain rule away from these. They are kept because the tiled device
+     * rasteriser computes exactly this much and nothing further — the projection and the band are
+     * per-splat work that is not worth a dispatch — so this is the surface
+     * `scripts/gpu-parity.mjs` holds the two rasterisers to.
+     */
+    readonly screen: Float64Array;
+    /** One per Gaussian. */
+    readonly opacities: Float64Array;
+}
+export declare function createGradients(count: number): GaussianGradients;
+/** Numbers a Gaussian's screen-space gradient occupies: mean, covariance, opacity, colour. */
+export declare const SCREEN_GRADIENTS = 9;
+/** The squared difference between a render and a frame, and the render's own gradient. */
+export declare function imageLoss(rendered: Frame, target: Frame, gradient: Float64Array): number;
+/**
+ * The gradients of a render against `dPixels` — the loss's derivative by each rendered channel,
+ * four a pixel — added into `out`. The render is repeated here rather than taken as an argument,
+ * because the backward walk needs what each Gaussian contributed on the way.
+ */
+export declare function accumulateGradients(set: GaussianSet, camera: RasterCamera, dPixels: Float64Array, out: GaussianGradients): void;

package/dist/gaussians/gradients.js

@@ -0,0 +1,228 @@
+/**
+ * What a Gaussian would have to change to make the picture right: the derivatives of the rendered
+ * frame with respect to every parameter of every Gaussian.
+ *
+ * **Analytic, and checked against a central difference.** Every term below is a chain rule through
+ * the same projection `rasterise.ts` draws with — the view transform, the perspective Jacobian, the
+ * screen covariance, its inverse, the exponent, the alpha, and the compositing — and
+ * `gradients.test.ts` compares each against the rasteriser it differentiates, nudged. A gradient
+ * that is subtly wrong does not fail: it trains to a slightly wrong cloud, which is why the
+ * comparison is the test rather than a measure of how well it fits.
+ *
+ * **The compositing is walked twice.** Forward, nearest first, to know what each Gaussian
+ * contributed and what light was left after it; then backward, furthest first, carrying the colour
+ * accumulated behind — because what a Gaussian's alpha is worth depends on everything in front of
+ * it and everything behind it at once.
+ */
+import { exactExp } from '@driftengine/core';
+import { cameraCentre, sh1Basis, sh1DirectionGradient, splatColour, SH1_COEFFICIENTS, viewDirection, } from './harmonics.js';
+import { visibleGaussians, } from './project.js';
+import { screenToParameters } from './projectGradient.js';
+export function createGradients(count) {
+    return {
+        positions: new Float64Array(count * 3),
+        scales: new Float64Array(count * 3),
+        rotations: new Float64Array(count * 4),
+        colors: new Float64Array(count * 3),
+        sh1: new Float64Array(count * SH1_COEFFICIENTS),
+        screen: new Float64Array(count * SCREEN_GRADIENTS),
+        opacities: new Float64Array(count),
+    };
+}
+const FAINT = 1 / 255 / 4;
+/** Numbers a Gaussian's screen-space gradient occupies: mean, covariance, opacity, colour. */
+export const SCREEN_GRADIENTS = 9;
+/** The squared difference between a render and a frame, and the render's own gradient. */
+export function imageLoss(rendered, target, gradient) {
+    let sum = 0;
+    for (let at = 0; at < gradient.length; at += 1) {
+        const off = rendered[at] - target[at];
+        sum += off * off;
+        gradient[at] = 2 * off;
+    }
+    return sum;
+}
+/**
+ * The gradients of a render against `dPixels` — the loss's derivative by each rendered channel,
+ * four a pixel — added into `out`. The render is repeated here rather than taken as an argument,
+ * because the backward walk needs what each Gaussian contributed on the way.
+ */
+export function accumulateGradients(set, camera, dPixels, out) {
+    const { width, height } = camera;
+    const { order, projected } = visibleGaussians(set, camera);
+    const pixels = width * height;
+    /* Forward: the light left at each pixel after every Gaussian in front of it. */
+    const transmittance = new Float64Array(pixels).fill(1);
+    for (const at of order) {
+        const one = projected[at];
+        const determinant = one.a * one.d - one.b * one.b;
+        const inverse = [one.d / determinant, -one.b / determinant, one.a / determinant];
+        const box = boxOf(one, width, height);
+        for (let y = box.top; y <= box.bottom; y += 1) {
+            for (let x = box.left; x <= box.right; x += 1) {
+                const dx = x + 0.5 - one.x;
+                const dy = y + 0.5 - one.y;
+                const power = -0.5 *
+                    (inverse[0] * dx * dx +
+                        2 * inverse[1] * dx * dy +
+                        inverse[2] * dy * dy);
+                const alpha = set.opacities[at] * exactExp(power);
+                if (alpha < FAINT)
+                    continue;
+                const pixel = y * width + x;
+                transmittance[pixel] = transmittance[pixel] * (1 - alpha);
+            }
+        }
+    }
+    /* Backward: furthest first, carrying what stands behind each Gaussian. */
+    const behind = new Float64Array(pixels * 3);
+    const behindAlpha = new Float64Array(pixels);
+    const light = Float64Array.from(transmittance);
+    const eye = new Float64Array(3);
+    cameraCentre(camera.worldToCamera, eye);
+    const direction = new Float64Array(3);
+    const basis = new Float64Array(3);
+    const colour = new Float64Array(3);
+    const dColour = new Float64Array(3);
+    const dDirection = new Float64Array(3);
+    for (let index = order.length - 1; index >= 0; index -= 1) {
+        const at = order[index];
+        const one = projected[at];
+        const determinant = one.a * one.d - one.b * one.b;
+        const inverse = [one.d / determinant, -one.b / determinant, one.a / determinant];
+        const box = boxOf(one, width, height);
+        const opacity = set.opacities[at];
+        const distance = viewDirection(set.positions, at, eye, direction);
+        sh1Basis(direction, basis);
+        splatColour(set.colors, set.sh1, at, basis, colour);
+        dColour.fill(0);
+        /* The screen-space gradients this Gaussian gathers over its own pixels. */
+        let dMeanX = 0;
+        let dMeanY = 0;
+        let dA = 0;
+        let dB = 0;
+        let dD = 0;
+        let dOpacity = 0;
+        for (let y = box.top; y <= box.bottom; y += 1) {
+            for (let x = box.left; x <= box.right; x += 1) {
+                const dx = x + 0.5 - one.x;
+                const dy = y + 0.5 - one.y;
+                const power = -0.5 *
+                    (inverse[0] * dx * dx +
+                        2 * inverse[1] * dx * dy +
+                        inverse[2] * dy * dy);
+                const weight = exactExp(power);
+                const alpha = opacity * weight;
+                if (alpha < FAINT)
+                    continue;
+                const pixel = y * width + x;
+                /* Undo this Gaussian's own share to recover the light that reached it. */
+                const after = light[pixel];
+                const before = alpha === 1 ? after : after / (1 - alpha);
+                let dAlpha = 0;
+                for (let c = 0; c < 3; c += 1) {
+                    const grad = dPixels[pixel * 4 + c];
+                    /* What this Gaussian puts on the pixel, and what its alpha takes from behind it. */
+                    dColour[c] = dColour[c] + grad * alpha * before;
+                    dAlpha += grad * before * (colour[c] - behind[pixel * 3 + c]);
+                }
+                const gradAlpha = dPixels[pixel * 4 + 3];
+                dAlpha += gradAlpha * before * (1 - behindAlpha[pixel]);
+                dOpacity += dAlpha * weight;
+                /* Through the exponent to the mean and the covariance. */
+                const dPower = dAlpha * opacity * weight;
+                const gx = inverse[0] * dx + inverse[1] * dy;
+                const gy = inverse[1] * dx + inverse[2] * dy;
+                dMeanX += dPower * gx;
+                dMeanY += dPower * gy;
+                /*
+                 * The exponent by the inverse covariance, **entry by entry rather than by three numbers**:
+                 * the off-diagonal is one of a symmetric pair, so it takes half of what a single shared
+                 * parameter would, and `dB` below is what puts the two halves back together. Written the
+                 * other way it is a factor of two on every cross term, which is a wrong gradient that
+                 * still points roughly the right way — so it fits, slightly wrongly, rather than failing.
+                 */
+                const dInverseA = -0.5 * dPower * dx * dx;
+                const dInverseB = -0.5 * dPower * dx * dy;
+                const dInverseD = -0.5 * dPower * dy * dy;
+                /* d(Σ⁻¹)/dΣ for a symmetric 2 × 2, written out. */
+                const ia = inverse[0];
+                const ib = inverse[1];
+                const id = inverse[2];
+                dA += -(ia * dInverseA * ia +
+                    ib * dInverseB * ia +
+                    ia * dInverseB * ib +
+                    ib * dInverseD * ib);
+                dB +=
+                    -(ia * dInverseA * ib + ib * dInverseB * ib + ia * dInverseB * id + ib * dInverseD * id) *
+                        2;
+                dD += -(ib * dInverseA * ib +
+                    id * dInverseB * ib +
+                    ib * dInverseB * id +
+                    id * dInverseD * id);
+                /* And carry this Gaussian into what stands behind the next one. */
+                for (let c = 0; c < 3; c += 1) {
+                    behind[pixel * 3 + c] =
+                        alpha * colour[c] + (1 - alpha) * behind[pixel * 3 + c];
+                }
+                behindAlpha[pixel] = alpha + (1 - alpha) * behindAlpha[pixel];
+                light[pixel] = before;
+            }
+        }
+        out.opacities[at] = out.opacities[at] + dOpacity;
+        /* What a device's tiled pass answers, before any of the chain rules below it. */
+        const screen = at * SCREEN_GRADIENTS;
+        out.screen[screen] = out.screen[screen] + dMeanX;
+        out.screen[screen + 1] = out.screen[screen + 1] + dMeanY;
+        out.screen[screen + 2] = out.screen[screen + 2] + dA;
+        out.screen[screen + 3] = out.screen[screen + 3] + dB;
+        out.screen[screen + 4] = out.screen[screen + 4] + dD;
+        out.screen[screen + 5] = out.screen[screen + 5] + dOpacity;
+        for (let c = 0; c < 3; c += 1) {
+            out.screen[screen + 6 + c] = out.screen[screen + 6 + c] + dColour[c];
+        }
+        /*
+         * The colour this Gaussian showed, back to the terms it was made of. **A channel the shader
+         * clamped at zero took no gradient**: it is flat there, so a constant term already below zero
+         * is not pushed further down by a frame that wanted it darker still.
+         */
+        for (let c = 0; c < 3; c += 1) {
+            if (!(colour[c] > 0))
+                continue;
+            out.colors[at * 3 + c] = out.colors[at * 3 + c] + dColour[c];
+            if (set.sh1 === undefined)
+                continue;
+            for (let band = 0; band < 3; band += 1) {
+                const slot = at * SH1_COEFFICIENTS + band * 3 + c;
+                out.sh1[slot] =
+                    out.sh1[slot] + dColour[c] * basis[band];
+            }
+        }
+        /*
+         * And the band is a **second way a position changes the picture**: moving a Gaussian turns the
+         * direction it is seen from, which reshades it. Small next to the term that moves it across the
+         * frame, and the difference finds it all the same.
+         */
+        if (set.sh1 !== undefined && distance > 0) {
+            sh1DirectionGradient(set.sh1, at, colour, dColour, dDirection);
+            let along = 0;
+            for (let axis = 0; axis < 3; axis += 1)
+                along += dDirection[axis] * direction[axis];
+            for (let axis = 0; axis < 3; axis += 1) {
+                out.positions[at * 3 + axis] =
+                    out.positions[at * 3 + axis] +
+                        (dDirection[axis] - along * direction[axis]) / distance;
+            }
+        }
+        /* Through the projection to the Gaussian's own parameters. */
+        screenToParameters(set, at, camera, dMeanX, dMeanY, dA, dB, dD, out);
+    }
+}
+function boxOf(one, width, height) {
+    return {
+        left: Math.max(0, Math.floor(one.x - one.radius)),
+        right: Math.min(width - 1, Math.ceil(one.x + one.radius)),
+        top: Math.max(0, Math.floor(one.y - one.radius)),
+        bottom: Math.min(height - 1, Math.ceil(one.y + one.radius)),
+    };
+}

package/dist/gaussians/harmonics.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The colour a Gaussian shows from a direction: its constant term plus the degree-1 band.
+ *
+ * **This is the splat shader's line, in JavaScript.** A capture fitted here is drawn by
+ * `@driftengine/splats`, so the two evaluations have to agree down to the sign of each basis —
+ * `SH_C1 * (-direction.y * c0 + direction.z * c1 - direction.x * c2)`, clamped at zero, shaded by
+ * the direction from the camera to the Gaussian in the capture's own world. A band evaluated with
+ * a different order here fits coefficients that look right in the fitter and wrong in the game,
+ * where it reads as a shader fault rather than as a capture that was never right.
+ *
+ * **Degree 1 and no further**, because that is what a record carries: nine coefficients and a
+ * scale in one more texel, and `SPLAT_WORDS_SH1` is what decided it.
+ */
+/** The l=1 basis constant, as the shader's `SH_C1`. */
+export declare const SH_C1 = 0.4886025119029199;
+/** Nine coefficients a Gaussian, interleaved by basis and then by channel. */
+export declare const SH1_COEFFICIENTS = 9;
+/** The three degree-1 basis values for a direction, the band constant folded in, into `out`. */
+export declare function sh1Basis(direction: ArrayLike<number>, out: Float64Array): void;
+/** Where a camera stands in the world, from a 3 × 4 world-to-camera: −Rᵀ · t. */
+export declare function cameraCentre(worldToCamera: ArrayLike<number>, out: Float64Array): void;
+/**
+ * The direction the band is shaded by: from `centre` to the Gaussian at `at`, normalised.
+ *
+ * A Gaussian standing exactly where the camera does has no direction to give. It answers with the
+ * camera's own forward axis rather than a division by zero — which costs nothing, because a
+ * Gaussian at the camera is behind the near plane and is not drawn.
+ *
+ * Answers the distance as well, because the gradient below divides by it: a direction is a
+ * normalisation, and how much a step moves it depends on how far away the thing is.
+ */
+export declare function viewDirection(positions: ArrayLike<number>, at: number, centre: ArrayLike<number>, out: Float64Array): number;
+/** A Gaussian's colour from a direction whose basis is already resolved, clamped at zero. */
+export declare function splatColour(colors: ArrayLike<number>, sh1: ArrayLike<number> | undefined, at: number, basis: ArrayLike<number>, out: Float64Array): void;
+/**
+ * The band's own gradient by the **direction** it was shaded from, into `out`.
+ *
+ * The colour is `−C·u_y·c₀ + C·u_z·c₁ − C·u_x·c₂` a channel, so each axis of the direction gathers
+ * one basis's coefficients. A channel the clamp flattened contributes nothing, exactly as it
+ * contributes nothing to the constant term.
+ *
+ * What the caller still owes is the step from a direction to a position: a direction is a
+ * normalisation, so only the part of a move across the line of sight turns it, and the amount it
+ * turns by falls off with distance.
+ */
+export declare function sh1DirectionGradient(sh1: ArrayLike<number>, at: number, colour: ArrayLike<number>, dColour: ArrayLike<number>, out: Float64Array): void;

package/dist/gaussians/harmonics.js

@@ -0,0 +1,99 @@
+/**
+ * The colour a Gaussian shows from a direction: its constant term plus the degree-1 band.
+ *
+ * **This is the splat shader's line, in JavaScript.** A capture fitted here is drawn by
+ * `@driftengine/splats`, so the two evaluations have to agree down to the sign of each basis —
+ * `SH_C1 * (-direction.y * c0 + direction.z * c1 - direction.x * c2)`, clamped at zero, shaded by
+ * the direction from the camera to the Gaussian in the capture's own world. A band evaluated with
+ * a different order here fits coefficients that look right in the fitter and wrong in the game,
+ * where it reads as a shader fault rather than as a capture that was never right.
+ *
+ * **Degree 1 and no further**, because that is what a record carries: nine coefficients and a
+ * scale in one more texel, and `SPLAT_WORDS_SH1` is what decided it.
+ */
+/** The l=1 basis constant, as the shader's `SH_C1`. */
+export const SH_C1 = 0.4886025119029199;
+/** Nine coefficients a Gaussian, interleaved by basis and then by channel. */
+export const SH1_COEFFICIENTS = 9;
+/** The three degree-1 basis values for a direction, the band constant folded in, into `out`. */
+export function sh1Basis(direction, out) {
+    out[0] = -SH_C1 * direction[1];
+    out[1] = SH_C1 * direction[2];
+    out[2] = -SH_C1 * direction[0];
+}
+/** Where a camera stands in the world, from a 3 × 4 world-to-camera: −Rᵀ · t. */
+export function cameraCentre(worldToCamera, out) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    for (let r = 0; r < 3; r += 1) {
+        for (let c = 0; c < 3; c += 1) {
+            out[c] =
+                out[c] -
+                    worldToCamera[r * 4 + c] * worldToCamera[r * 4 + 3];
+        }
+    }
+}
+/**
+ * The direction the band is shaded by: from `centre` to the Gaussian at `at`, normalised.
+ *
+ * A Gaussian standing exactly where the camera does has no direction to give. It answers with the
+ * camera's own forward axis rather than a division by zero — which costs nothing, because a
+ * Gaussian at the camera is behind the near plane and is not drawn.
+ *
+ * Answers the distance as well, because the gradient below divides by it: a direction is a
+ * normalisation, and how much a step moves it depends on how far away the thing is.
+ */
+export function viewDirection(positions, at, centre, out) {
+    const x = positions[at * 3] - centre[0];
+    const y = positions[at * 3 + 1] - centre[1];
+    const z = positions[at * 3 + 2] - centre[2];
+    const length = Math.sqrt(x * x + y * y + z * z);
+    if (!(length > 0)) {
+        out[0] = 0;
+        out[1] = 0;
+        out[2] = 1;
+        return 0;
+    }
+    out[0] = x / length;
+    out[1] = y / length;
+    out[2] = z / length;
+    return length;
+}
+/** A Gaussian's colour from a direction whose basis is already resolved, clamped at zero. */
+export function splatColour(colors, sh1, at, basis, out) {
+    for (let c = 0; c < 3; c += 1) {
+        let value = colors[at * 3 + c];
+        if (sh1 !== undefined) {
+            for (let band = 0; band < 3; band += 1) {
+                value += basis[band] * sh1[at * SH1_COEFFICIENTS + band * 3 + c];
+            }
+        }
+        out[c] = value > 0 ? value : 0;
+    }
+}
+/**
+ * The band's own gradient by the **direction** it was shaded from, into `out`.
+ *
+ * The colour is `−C·u_y·c₀ + C·u_z·c₁ − C·u_x·c₂` a channel, so each axis of the direction gathers
+ * one basis's coefficients. A channel the clamp flattened contributes nothing, exactly as it
+ * contributes nothing to the constant term.
+ *
+ * What the caller still owes is the step from a direction to a position: a direction is a
+ * normalisation, so only the part of a move across the line of sight turns it, and the amount it
+ * turns by falls off with distance.
+ */
+export function sh1DirectionGradient(sh1, at, colour, dColour, out) {
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    for (let c = 0; c < 3; c += 1) {
+        if (!(colour[c] > 0))
+            continue;
+        const weight = dColour[c] * SH_C1;
+        const base = at * SH1_COEFFICIENTS;
+        out[0] = out[0] - weight * sh1[base + 6 + c];
+        out[1] = out[1] - weight * sh1[base + c];
+        out[2] = out[2] + weight * sh1[base + 3 + c];
+    }
+}