@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/transform/forward_transform_2d.js

@@ -0,0 +1,574 @@
+import { TRANSFORM_ROW_SHIFT } from "../tables/transform_tables.js";
+import { TX_HEIGHT_LOG2, TX_WIDTH_LOG2 } from "../tables/block_tables.js";
+import { inverse_adst, inverse_dct } from "./inverse_transform_1d.js";
+
+/**
+ * Longest transform side, in samples.
+ * @type {number}
+ */
+const MAX_SIDE = 64;
+
+/**
+ * A DCT, in the sense {@link forward_matrix} means it.
+ * @type {number}
+ */
+export const FORWARD_DCT = 0;
+
+/**
+ * An ADST.
+ * @type {number}
+ */
+export const FORWARD_ADST = 1;
+
+/**
+ * Magnitude the specification's inverse transform is probed with.
+ *
+ * Large enough that its internal rounding is a part in ten thousand of the answer, small enough that
+ * nothing saturates on the way through.
+ * @type {number}
+ */
+const PROBE = 1 << 14;
+
+/**
+ * Headroom given to the probe, in bits. Well above any real transform's, because clamping during
+ * measurement would quietly bend the matrix rather than fail.
+ * @type {number}
+ */
+const PROBE_RANGE = 24;
+
+/**
+ * Forward matrices, keyed by kind and size, built on first use.
+ * @type {Map<number, Float32Array>}
+ */
+const MATRICES = new Map();
+
+/** @type {Int32Array} */
+const PROBE_VECTOR = new Int32Array(MAX_SIDE);
+
+/** @type {Float64Array} */
+const INTERMEDIATE = new Float64Array(MAX_SIDE * MAX_SIDE);
+
+/** @type {Float64Array} */
+const COLUMN = new Float64Array(MAX_SIDE);
+
+/**
+ * One line of the block, and the folded halves the fast DCT makes of it.
+ *
+ * A length `n` is folded to `n / 2`, that to `n / 4`, and so on, so twice the longest side holds
+ * every level at once and each of them is one contiguous run.
+ * @type {Float64Array}
+ */
+const LINE = new Float64Array(MAX_SIDE * 2);
+
+/**
+ * The odd half of each DCT length: the rows of the forward matrix with an odd index, over the first
+ * half of their columns. Indexed by `log2` of the length, and built beside the matrix it comes from.
+ * @type {Float32Array[]}
+ */
+const DCT_ODD = new Array(7).fill(null);
+
+/**
+ * The two-point forward DCT, which is where the fold stops.
+ * @type {Float32Array}
+ */
+let DCT_BASE = null;
+
+/**
+ * The forward transform matrix for one kind and size: the numerical inverse of the specification's
+ * own inverse transform.
+ *
+ * AV1 defines no forward transform. Every encoder invents one, and the only property that matters is
+ * that the *normative* inverse turns its output back into the picture. Rather than transliterate
+ * libaom's integer butterflies — hundreds of lines, and correct only if every one of them is —
+ * this measures the inverse the decoder actually runs and inverts it.
+ *
+ * The measured map is very slightly non-linear, because the integer butterfly rounds internally.
+ * That shows up as a fraction of a step of error in the round trip, which quantisation then
+ * swallows; at quantizer index zero the lossless path uses the exactly invertible
+ * Walsh-Hadamard pair instead, so nothing depends on this being exact.
+ *
+ * @param {number} kind {@link FORWARD_DCT} or {@link FORWARD_ADST}
+ * @param {number} log2_n
+ * @returns {Float32Array} `n * n`, row major
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+function forward_matrix(kind, log2_n) {
+    const key = kind * 8 + log2_n;
+
+    const found = MATRICES.get(key);
+
+    if (found !== undefined) {
+        return found;
+    }
+
+    const n = 1 << log2_n;
+
+    const measured = new Float64Array(n * n);
+
+    for (let k = 0; k < n; k++) {
+        PROBE_VECTOR.fill(0, 0, n);
+        PROBE_VECTOR[k] = PROBE;
+
+        if (kind === FORWARD_DCT) {
+            inverse_dct(PROBE_VECTOR, log2_n, PROBE_RANGE);
+        } else {
+            inverse_adst(PROBE_VECTOR, log2_n, PROBE_RANGE);
+        }
+
+        for (let i = 0; i < n; i++) {
+            measured[i * n + k] = PROBE_VECTOR[i] / PROBE;
+        }
+    }
+
+    // inverted at full precision and then narrowed, because the inversion is a Gauss-Jordan
+    // elimination whose intermediate values want every digit, and what comes out of it does not:
+    // the entries are used once each per output coefficient, so what matters about them is how many
+    // fit in a cache line. A 32x32 matrix is four kilobytes this way and eight the other, and the
+    // transform reads the whole of it once per row of the block. Seven significant digits against a
+    // coefficient that is rounded to an integer is nothing
+    const inverted = invert(measured, n);
+
+    const narrowed = new Float32Array(n * n);
+
+    narrowed.set(inverted);
+
+    MATRICES.set(key, narrowed);
+
+    return narrowed;
+}
+
+/**
+ * Invert a square matrix by Gauss-Jordan elimination with partial pivoting.
+ *
+ * @param {Float64Array} source `n * n`, row major; not modified
+ * @param {number} n
+ * @returns {Float64Array} `n * n`
+ */
+function invert(source, n) {
+    const a = Float64Array.from(source);
+    const b = new Float64Array(n * n);
+
+    for (let i = 0; i < n; i++) {
+        b[i * n + i] = 1;
+    }
+
+    for (let column = 0; column < n; column++) {
+        let pivot = column;
+
+        for (let row = column + 1; row < n; row++) {
+            if (Math.abs(a[row * n + column]) > Math.abs(a[pivot * n + column])) {
+                pivot = row;
+            }
+        }
+
+        if (a[pivot * n + column] === 0) {
+            throw new Error("the specification's inverse transform measured as singular");
+        }
+
+        if (pivot !== column) {
+            for (let k = 0; k < n; k++) {
+                const swap_a = a[column * n + k];
+                const swap_b = b[column * n + k];
+
+                a[column * n + k] = a[pivot * n + k];
+                b[column * n + k] = b[pivot * n + k];
+
+                a[pivot * n + k] = swap_a;
+                b[pivot * n + k] = swap_b;
+            }
+        }
+
+        const scale = 1 / a[column * n + column];
+
+        for (let k = 0; k < n; k++) {
+            a[column * n + k] *= scale;
+            b[column * n + k] *= scale;
+        }
+
+        for (let row = 0; row < n; row++) {
+            if (row === column) {
+                continue;
+            }
+
+            const factor = a[row * n + column];
+
+            if (factor === 0) {
+                continue;
+            }
+
+            for (let k = 0; k < n; k++) {
+                a[row * n + k] -= factor * a[column * n + k];
+                b[row * n + k] -= factor * b[column * n + k];
+            }
+        }
+    }
+
+    return b;
+}
+
+/**
+ * Build the folded form of one DCT length, and of every length it folds down to.
+ *
+ * ### Why it folds at all
+ *
+ * A cosine basis alternates between symmetric and antisymmetric about the middle of the block:
+ * `F[2k][j] === F[2k][n - 1 - j]` and `F[2k + 1][j] === -F[2k + 1][n - 1 - j]`. Fold the input into
+ * the sum and the difference of its two halves and each output needs only one of them: the even
+ * outputs the sum, the odd outputs the difference. That alone halves the multiplies.
+ *
+ * The other half of the saving is that the even outputs, taken against the folded sum, *are* a
+ * forward DCT of half the length. So the sum folds again, and again, down to two points: the
+ * multiplies go from `n * n` to a little over `n * n / 3`, against `2n` additions for the folding.
+ *
+ * Both facts are properties of the cosine basis rather than of any implementation, and this
+ * module's spec checks them against the dense matrix as measured rather than against the ideal one
+ * — so a change to the decoder's inverse transform cannot quietly invalidate them.
+ *
+ * @param {number} log2_n
+ */
+function build_dct_plan(log2_n) {
+    if (DCT_ODD[log2_n] !== null) {
+        return;
+    }
+
+    const n = 1 << log2_n;
+    const half = n >> 1;
+
+    const matrix = forward_matrix(FORWARD_DCT, log2_n);
+
+    const odd = new Float32Array(half * half);
+
+    for (let k = 0; k < half; k++) {
+        for (let j = 0; j < half; j++) {
+            odd[k * half + j] = matrix[(2 * k + 1) * n + j];
+        }
+    }
+
+    DCT_ODD[log2_n] = odd;
+
+    if (log2_n > 2) {
+        build_dct_plan(log2_n - 1);
+
+        return;
+    }
+
+    // the fold halves the sum as it makes it, so that a level's outputs come out at the level's own
+    // scale rather than at twice it. The two-point transform sits on the far side of one such
+    // halving, which is what the doubling here undoes
+    const base = new Float32Array(4);
+
+    for (let k = 0; k < 2; k++) {
+        for (let j = 0; j < 2; j++) {
+            base[k * 2 + j] = 2 * matrix[(2 * k) * 4 + j];
+        }
+    }
+
+    DCT_BASE = base;
+}
+
+/**
+ * One forward DCT, folded.
+ *
+ * @param {Float64Array} values the input, and the scratch the fold writes into above it
+ * @param {number} offset where the input starts
+ * @param {number} log2_n
+ * @param {Float64Array} out
+ * @param {number} out_offset
+ * @param {number} out_stride
+ */
+function forward_dct(values, offset, log2_n, out, out_offset, out_stride) {
+    const n = 1 << log2_n;
+    const half = n >> 1;
+
+    const folded = offset + n;
+
+    for (let j = 0; j < half; j++) {
+        const near = values[offset + j];
+        const far = values[offset + n - 1 - j];
+
+        values[folded + j] = 0.5 * (near + far);
+        values[folded + half + j] = near - far;
+    }
+
+    const odd = DCT_ODD[log2_n];
+
+    for (let k = 0; k < half; k++) {
+        const base = k * half;
+
+        let sum = 0;
+
+        for (let j = 0; j < half; j++) {
+            sum += odd[base + j] * values[folded + half + j];
+        }
+
+        out[out_offset + out_stride * (2 * k + 1)] = sum;
+    }
+
+    if (log2_n > 2) {
+        forward_dct(values, folded, log2_n - 1, out, out_offset, out_stride * 2);
+
+        return;
+    }
+
+    const two = DCT_BASE;
+
+    const first = values[folded];
+    const second = values[folded + 1];
+
+    out[out_offset] = two[0] * first + two[1] * second;
+    out[out_offset + out_stride * 2] = two[2] * first + two[3] * second;
+}
+
+/**
+ * One forward transform along a line, of whichever kind.
+ *
+ * @param {number} kind {@link FORWARD_DCT} or {@link FORWARD_ADST}
+ * @param {number} log2_n
+ * @param {Float64Array} values
+ * @param {Float64Array} out
+ * @param {number} out_offset
+ * @param {number} out_stride
+ */
+function forward_transform_1d(kind, log2_n, values, out, out_offset, out_stride) {
+    if (kind === FORWARD_DCT) {
+        build_dct_plan(log2_n);
+
+        forward_dct(values, 0, log2_n, out, out_offset, out_stride);
+
+        return;
+    }
+
+    // an ADST is symmetric about nothing, so there is nothing to fold it along and it stays the
+    // matrix it was measured as
+    const n = 1 << log2_n;
+
+    const matrix = forward_matrix(FORWARD_ADST, log2_n);
+
+    for (let k = 0; k < n; k++) {
+        const base = k * n;
+
+        let sum = 0;
+
+        for (let j = 0; j < n; j++) {
+            sum += matrix[base + j] * values[j];
+        }
+
+        out[out_offset + out_stride * k] = sum;
+    }
+}
+
+/**
+ * Scale a transform whose sides differ by a factor of two carries, as a reciprocal.
+ *
+ * The inverse multiplies such a transform's input by `2896 / 4096`, which is one over the square
+ * root of two, to keep the basis orthonormal. The forward has to put it back.
+ * @type {number}
+ */
+const RECTANGULAR_SCALE = 4096 / 2896;
+
+/**
+ * Forward 2D transform of a spatial residual into coefficients.
+ *
+ * @param {Int32Array} residual the residual on entry, coefficients on exit, row major with the
+ *   transform's width as its stride
+ * @param {number} tx_size
+ * @param {number} row_kind the transform the *inverse* will run on rows
+ * @param {number} column_kind
+ * @see AV1 spec 7.13.3, which this has to be the inverse of
+ */
+export function forward_transform_2d(residual, tx_size, row_kind, column_kind) {
+    const log2_w = TX_WIDTH_LOG2[tx_size];
+    const log2_h = TX_HEIGHT_LOG2[tx_size];
+
+    const width = 1 << log2_w;
+    const height = 1 << log2_h;
+
+    const scale = forward_scale(tx_size, log2_w, log2_h);
+
+    for (let i = 0; i < height; i++) {
+        const row = i * width;
+
+        for (let j = 0; j < width; j++) {
+            LINE[j] = residual[row + j];
+        }
+
+        forward_transform_1d(row_kind, log2_w, LINE, INTERMEDIATE, row, 1);
+    }
+
+    for (let j = 0; j < width; j++) {
+        for (let i = 0; i < height; i++) {
+            LINE[i] = INTERMEDIATE[i * width + j];
+        }
+
+        forward_transform_1d(column_kind, log2_h, LINE, COLUMN, 0, 1);
+
+        for (let k = 0; k < height; k++) {
+            residual[k * width + j] = Math.round(COLUMN[k] * scale);
+        }
+    }
+}
+
+/**
+ * What the transform multiplies its output by at the end.
+ *
+ * The inverse shifts its intermediates down twice on the way through; the forward has to put both
+ * of those back, and a transform whose sides differ by a factor of two carries one more.
+ *
+ * @param {number} tx_size
+ * @param {number} log2_w
+ * @param {number} log2_h
+ * @returns {number}
+ */
+function forward_scale(tx_size, log2_w, log2_h) {
+    const scale = 1 << (TRANSFORM_ROW_SHIFT[tx_size] + 4);
+
+    return Math.abs(log2_w - log2_h) === 1 ? scale * RECTANGULAR_SCALE : scale;
+}
+
+/**
+ * The dense forward matrix, so that the spec can check what the fold assumes about it.
+ *
+ * @param {number} kind {@link FORWARD_DCT} or {@link FORWARD_ADST}
+ * @param {number} log2_n
+ * @returns {Float32Array} `n * n`, row major
+ */
+export function forward_matrix_of(kind, log2_n) {
+    return forward_matrix(kind, log2_n);
+}
+
+/**
+ * Largest coefficient magnitude a residual of a given energy can produce.
+ *
+ * The transform is a matrix, so a coefficient is a row of it dotted with the residual, and
+ * Cauchy-Schwarz bounds that by the row's length times the residual's. The 2D matrix is the
+ * Kronecker product of the two 1D ones, so its longest row is the product of their longest — which
+ * makes this a property of the transform, computed once and remembered.
+ *
+ * It is not an estimate. A residual whose length puts this bound below the quantiser's threshold
+ * has *no* coefficient that can survive, and the transform that would have found that out one
+ * multiply-accumulate at a time can be skipped outright.
+ *
+ * @param {number} tx_size
+ * @param {number} row_kind
+ * @param {number} column_kind
+ * @returns {number} multiply by the residual's Euclidean length for the bound
+ * @see the Cauchy-Schwarz inequality, which is the whole of it
+ */
+export function forward_transform_bound(tx_size, row_kind, column_kind) {
+    const log2_w = TX_WIDTH_LOG2[tx_size];
+    const log2_h = TX_HEIGHT_LOG2[tx_size];
+
+    const key = ((tx_size * 2 + row_kind) * 2 + column_kind);
+
+    const found = BOUNDS.get(key);
+
+    if (found !== undefined) {
+        return found;
+    }
+
+    const bound = forward_scale(tx_size, log2_w, log2_h)
+        * longest_row(forward_matrix(row_kind, log2_w), 1 << log2_w)
+        * longest_row(forward_matrix(column_kind, log2_h), 1 << log2_h);
+
+    BOUNDS.set(key, bound);
+
+    return bound;
+}
+
+/**
+ * @type {Map<number, number>} bounds by transform size and the two kinds, built on first use
+ */
+const BOUNDS = new Map();
+
+/**
+ * @param {Float32Array} matrix `n * n`, row major
+ * @param {number} n
+ * @returns {number} the Euclidean length of its longest row
+ */
+function longest_row(matrix, n) {
+    let longest = 0;
+
+    for (let k = 0; k < n; k++) {
+        let energy = 0;
+
+        for (let j = 0; j < n; j++) {
+            const value = matrix[k * n + j];
+
+            energy += value * value;
+        }
+
+        if (energy > longest) {
+            longest = energy;
+        }
+    }
+
+    return Math.sqrt(longest);
+}
+
+/**
+ * The forward Walsh-Hadamard transform, exactly inverted by the specification's inverse WHT at
+ * shift zero.
+ *
+ * @param {Int32Array} t four entries, transformed in place
+ */
+function forward_wht(t) {
+    let a = t[0];
+    let b = t[1];
+    let c = t[2];
+    let d = t[3];
+
+    a += b;
+    d -= c;
+
+    const e = (a - d) >> 1;
+
+    b = e - b;
+    c = e - c;
+
+    a -= c;
+    d += b;
+
+    t[0] = a;
+    t[1] = c;
+    t[2] = d;
+    t[3] = b;
+}
+
+/**
+ * Forward 4x4 Walsh-Hadamard transform, for lossless coding.
+ *
+ * Runs columns first and scales at the very end, mirroring the inverse's rows-then-columns with its
+ * shift of two on the row pass. The Hadamard's `(a - d) >> 1` throws a bit away, so scaling the
+ * input is not the same operation as scaling the output — and the difference is exactly the one step
+ * of precision that separates lossless from nearly lossless.
+ *
+ * @param {Int32Array} residual sixteen entries, row major
+ * @param {Int32Array} t scratch of at least four entries
+ */
+export function forward_wht_4x4(residual, t) {
+    for (let j = 0; j < 4; j++) {
+        for (let i = 0; i < 4; i++) {
+            t[i] = residual[i * 4 + j];
+        }
+
+        forward_wht(t);
+
+        for (let i = 0; i < 4; i++) {
+            residual[i * 4 + j] = t[i];
+        }
+    }
+
+    for (let i = 0; i < 4; i++) {
+        for (let j = 0; j < 4; j++) {
+            t[j] = residual[i * 4 + j];
+        }
+
+        forward_wht(t);
+
+        for (let j = 0; j < 4; j++) {
+            residual[i * 4 + j] = t[j] * 4;
+        }
+    }
+}

package/src/avif/native/av1/transform/inverse_transform_1d.d.ts

@@ -0,0 +1,76 @@
+/**
+ * `Round2( x, 12 )` for values that do not fit in a signed 32-bit integer.
+ *
+ * The butterfly's intermediates are a coefficient of up to 20 bits times a basis value of up to 12,
+ * summed in pairs — as much as 33 bits, which `>>` would wrap. Every JavaScript number is already a
+ * double, so the product is exact and only the shift needs replacing with a floor division; nothing
+ * is converted and nothing is lost.
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+export function round2_12(x: number): number;
+/**
+ * `cos128( angle )`: `4096 * cos( angle * pi / 128 )`, rounded.
+ *
+ * @param {number} angle
+ * @returns {number}
+ * @see AV1 spec 7.13.2.1 "Butterfly functions"
+ */
+export function cos128(angle: number): number;
+/**
+ * `sin128( angle )`.
+ * @param {number} angle
+ * @returns {number}
+ */
+export function sin128(angle: number): number;
+/**
+ * In-place inverse DCT of the first `1 << n` entries of `t`.
+ *
+ * A direct transliteration of the specification's thirty-one ordered steps. It is long, and it
+ * stays long: every step is a different butterfly pattern, and rewriting it as anything more
+ * compact would be a second, unverifiable description of the same thing.
+ *
+ * @param {Int32Array} t
+ * @param {number} n base 2 logarithm of the length, `2 .. 6`
+ * @param {number} r intermediate clamping range in bits
+ * @see AV1 spec 7.13.2.3 "Inverse DCT process"
+ */
+export function inverse_dct(t: Int32Array, n: number, r: number): void;
+/**
+ * @param {Int32Array} t
+ * @see AV1 spec 7.13.2.6 "Inverse ADST4 process"
+ */
+export function inverse_adst4(t: Int32Array): void;
+/**
+ * @param {Int32Array} t
+ * @param {number} r
+ * @see AV1 spec 7.13.2.7 "Inverse ADST8 process"
+ */
+export function inverse_adst8(t: Int32Array, r: number): void;
+/**
+ * @param {Int32Array} t
+ * @param {number} r
+ * @see AV1 spec 7.13.2.8 "Inverse ADST16 process"
+ */
+export function inverse_adst16(t: Int32Array, r: number): void;
+/**
+ * @param {Int32Array} t
+ * @param {number} n `2 .. 4`
+ * @param {number} r
+ * @see AV1 spec 7.13.2.9 "Inverse ADST process"
+ */
+export function inverse_adst(t: Int32Array, n: number, r: number): void;
+/**
+ * @param {Int32Array} t
+ * @param {number} shift
+ * @see AV1 spec 7.13.2.10 "Inverse Walsh-Hadamard transform process"
+ */
+export function inverse_wht(t: Int32Array, shift: number): void;
+/**
+ * @param {Int32Array} t
+ * @param {number} n `2 .. 5`
+ * @see AV1 spec 7.13.2.15 "Inverse identity transform process"
+ */
+export function inverse_identity(t: Int32Array, n: number): void;
+//# sourceMappingURL=inverse_transform_1d.d.ts.map

package/src/avif/native/av1/transform/inverse_transform_1d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inverse_transform_1d.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/transform/inverse_transform_1d.js"],"names":[],"mappings":"AAeA;;;;;;;;;;GAUG;AACH,6BAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AACH,8BAJW,MAAM,GACJ,MAAM,CAmBlB;AAED;;;;GAIG;AACH,8BAHW,MAAM,GACJ,MAAM,CAIlB;AAkFD;;;;;;;;;;;GAWG;AACH,+BALW,UAAU,KACV,MAAM,KACN,MAAM,QA2MhB;AA6CD;;;GAGG;AACH,iCAHW,UAAU,QAsCpB;AAED;;;;GAIG;AACH,iCAJW,UAAU,KACV,MAAM,QA6BhB;AAED;;;;GAIG;AACH,kCAJW,UAAU,KACV,MAAM,QA0ChB;AAED;;;;;GAKG;AACH,gCALW,UAAU,KACV,MAAM,KACN,MAAM,QAWhB;AAED;;;;GAIG;AACH,+BAJW,UAAU,SACV,MAAM,QAwBhB;AAED;;;;GAIG;AACH,oCAJW,UAAU,KACV,MAAM,QAqBhB"}