@woosh/meep-engine 3.9.0 → 3.10.0

package/src/avif/native/av1/encode/choose_restoration.js

@@ -0,0 +1,616 @@
+import { clamp_index } from "../../../../core/math/clamp_index.js";
+import { RESTORE_NONE, RESTORE_WIENER } from "../tables/av1_symbols.js";
+import { WIENER_TAPS_MAX, WIENER_TAPS_MID, WIENER_TAPS_MIN } from "../tables/filter_tables.js";
+import { apply_loop_restoration, count_units_in_frame, restoration_unit_of } from "../filter/loop_restoration.js";
+import { DECODE_THOROUGH } from "./decode_effort.js";
+import { apply_cdef } from "../filter/cdef.js";
+import { round2 } from "../util/round2.js";
+import { write_lr_unit } from "./write_lr.js";
+
+/**
+ * Taps in each direction, and the fraction they are counted in.
+ * @type {number}
+ */
+const TAPS = 3;
+
+/** @type {number} the coded taps are sixty-fourths of the filter's unit gain of 128 */
+const TAP_SCALE = 128;
+
+/**
+ * Added to the diagonal of each fit, in the units the samples are measured in.
+ *
+ * A flat unit — a patch of sky, a black border — leaves a system with no information in it, and
+ * without this the solve returns whatever the rounding left. With it, such a unit fits the identity,
+ * which is the right answer for a patch with nothing in it to restore.
+ * @type {number}
+ */
+const RIDGE = 1e-3;
+
+/**
+ * Choose a restoration filter for each unit of the frame, after everything else is decided.
+ *
+ * ### What it is
+ *
+ * Deblocking and the directional filter both work on what a block looks like. Restoration works on
+ * what the *picture* looks like: it fits a small symmetric blur or sharpen to each patch of the
+ * reconstruction so that the patch lands closer to the source. The filter is seven taps across and
+ * seven down, symmetric in each direction and summing to one, which is three numbers per direction
+ * and the format codes them per unit.
+ *
+ * ### Why it is fitted rather than searched
+ *
+ * A least squares fit is the answer, not an approximation to it: with the vertical taps fixed, the
+ * horizontal ones that minimise squared error against the source solve a three by three system.
+ * Fixing the horizontal and solving the vertical does the same, and alternating converges in two
+ * rounds. Searching a ladder of filters, the way the deblocking level is chosen, would be both
+ * slower and worse.
+ *
+ * ### Why a unit may end up with none
+ *
+ * The taps cost thirty or forty bits, and a unit the reconstruction already got right does not earn
+ * them back. So each unit is priced — by writing its real syntax against a costing writer, both
+ * ways — and keeps the filter only when the error it saves is worth what it costs, at the same
+ * lambda every other decision in this encoder is taken at. A plane where no unit keeps one is
+ * signalled as having no restoration at all, which costs it nothing anywhere.
+ *
+ * @param {Av1EncodeContext} ec
+ * @see AV1 spec 7.17 "Loop restoration process", which is what this is choosing the parameters for
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function choose_restoration(ec) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    const wanted = frame.uses_lr;
+
+    frame.frame_restoration_type[0] = RESTORE_NONE;
+    frame.frame_restoration_type[1] = RESTORE_NONE;
+    frame.frame_restoration_type[2] = RESTORE_NONE;
+    frame.uses_lr = 0;
+
+    if (wanted === 0 || ec.decode_effort < DECODE_THOROUGH || ec.restoration_trials < 1 || ctx.lr_type === null) {
+        return;
+    }
+
+    ec.resize_restoration(ctx);
+
+    prepare_deringed(ec);
+
+    frame.uses_lr = 1;
+
+    const planes = Math.min(ctx.num_planes, ec.restoration_planes);
+
+    for (let plane = 0; plane < planes; plane++) {
+        frame.frame_restoration_type[plane] = RESTORE_WIENER;
+
+        fit_plane(ec, plane);
+    }
+
+    // the units are priced against what the filter actually did, so it has to actually be run
+    apply_loop_restoration(ctx, ctx.planes, ctx.cdef_planes, ctx.lr_planes, ctx.plane_stride);
+
+    let any = 0;
+
+    for (let plane = 0; plane < planes; plane++) {
+        measure_units(ec, plane);
+
+        if (keep_units(ec, plane) === 0) {
+            frame.frame_restoration_type[plane] = RESTORE_NONE;
+
+            continue;
+        }
+
+        any = 1;
+    }
+
+    frame.uses_lr = any;
+}
+
+/**
+ * Leave the frame as the decoder will have it when restoration starts: deblocked in `planes`, and
+ * deringed in `cdef_planes` — which is a copy of the first when no directional filter is signalled,
+ * exactly as the decoder makes it.
+ *
+ * @param {Av1EncodeContext} ec
+ */
+function prepare_deringed(ec) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    const uses_cdef = frame.coded_lossless === 0
+        && frame.allow_intrabc === 0
+        && ec.sequence.enable_cdef === 1;
+
+    if (uses_cdef) {
+        apply_cdef(ctx);
+
+        return;
+    }
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const samples = ctx.plane_stride[plane] * ctx.plane_rows[plane];
+
+        for (let i = 0; i < samples; i++) {
+            ctx.cdef_planes[plane][i] = ctx.planes[plane][i];
+        }
+    }
+}
+
+/**
+ * Fit one plane's units, alternating between the two directions.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ */
+function fit_plane(ec, plane) {
+    const ctx = ec.frame_context;
+
+    const width = ctx.plane_width[plane];
+    const height = ctx.plane_height[plane];
+    const stride = ctx.plane_stride[plane];
+
+    const map_stride = build_unit_map(ec, plane);
+
+    const units = unit_count(ec, plane);
+
+    for (let i = 0; i < units; i++) {
+        const index = ctx.lr_unit_index(plane, Math.floor(i / ec.restoration_columns), i % ec.restoration_columns);
+
+        ctx.lr_type[index] = RESTORE_WIENER;
+
+        for (let j = 0; j < 6; j++) {
+            ctx.lr_wiener[index * 6 + j] = 0;
+        }
+    }
+
+    const input = ctx.cdef_planes[plane];
+
+    for (let round = 0; round < ec.restoration_trials; round++) {
+        // the horizontal taps against a picture the vertical ones have already been through
+        filter_plane(ec, plane, input, ec.restoration_middle, stride, width, height, map_stride, 0, round === 0 ? 0 : 1);
+
+        fit_direction(ec, plane, ec.restoration_middle, stride, width, height, map_stride, 1);
+
+        // and then the vertical taps against a picture the horizontal ones have been through
+        filter_plane(ec, plane, input, ec.restoration_middle, stride, width, height, map_stride, 1, 1);
+
+        fit_direction(ec, plane, ec.restoration_middle, stride, width, height, map_stride, 0);
+    }
+}
+
+/**
+ * Which unit each 4x4 block of a plane belongs to, worked out once rather than per sample.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @returns {number} the map's stride, in 4x4 blocks
+ */
+function build_unit_map(ec, plane) {
+    const ctx = ec.frame_context;
+
+    const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+    const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+    const columns = (ctx.plane_width[plane] + 3) >> 2;
+    const rows = (ctx.plane_height[plane] + 3) >> 2;
+
+    const map = ec.restoration_map;
+
+    for (let y = 0; y < rows; y++) {
+        for (let x = 0; x < columns; x++) {
+            map[y * columns + x] = restoration_unit_of(ctx, plane, y << sub_y, x << sub_x);
+        }
+    }
+
+    return columns;
+}
+
+/**
+ * Run one direction's taps over a whole plane, per unit.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @param {Uint16Array} input
+ * @param {Float32Array} output
+ * @param {number} stride
+ * @param {number} width
+ * @param {number} height
+ * @param {number} map_stride
+ * @param {number} pass `0` for the vertical taps, `1` for the horizontal
+ * @param {number} filtering `0` copies instead, which is what the identity would have done
+ */
+function filter_plane(ec, plane, input, output, stride, width, height, map_stride, pass, filtering) {
+    const ctx = ec.frame_context;
+
+    const taps = ctx.lr_wiener;
+    const filter = ec.restoration_taps;
+
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        const map_row = (y >> 2) * map_stride;
+
+        for (let x = 0; x < width; x++) {
+            if (filtering === 0) {
+                output[row + x] = input[row + x];
+
+                continue;
+            }
+
+            expand(taps, ec.restoration_map[map_row + (x >> 2)] * 6 + pass * 3, filter);
+
+            let sum = 0;
+
+            for (let t = 0; t < 7; t++) {
+                const at = pass === 1
+                    ? row + clamp_index(x + t - 3, width)
+                    : clamp_index(y + t - 3, height) * stride + x;
+
+                sum += filter[t] * input[at];
+            }
+
+            output[row + x] = sum / TAP_SCALE;
+        }
+    }
+}
+
+/**
+ * Solve one direction's taps for every unit of a plane at once.
+ *
+ * Three free numbers per unit: the filter is symmetric and sums to one, so the centre tap follows
+ * from the other three and each of them multiplies a *pair* of samples either side of the middle.
+ * That is what makes the basis below what it is.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @param {Float32Array} values what the other direction left
+ * @param {number} stride
+ * @param {number} width
+ * @param {number} height
+ * @param {number} map_stride
+ * @param {number} pass `0` for the vertical taps, `1` for the horizontal
+ */
+function fit_direction(ec, plane, values, stride, width, height, map_stride, pass) {
+    const ctx = ec.frame_context;
+
+    const stats = ec.restoration_stats;
+
+    stats.fill(0);
+
+    const source = ec.source[plane];
+    const source_stride = ec.source_stride[plane];
+
+    const map = ec.restoration_map;
+
+    const basis = ec.restoration_basis;
+
+    for (let y = 0; y < height; y++) {
+        const row = y * stride;
+        const map_row = (y >> 2) * map_stride;
+
+        for (let x = 0; x < width; x++) {
+            const centre = values[row + x];
+
+            for (let i = 0; i < TAPS; i++) {
+                const near = pass === 1
+                    ? values[row + clamp_index(x + i - 3, width)]
+                    : values[clamp_index(y + i - 3, height) * stride + x];
+
+                const far = pass === 1
+                    ? values[row + clamp_index(x + 3 - i, width)]
+                    : values[clamp_index(y + 3 - i, height) * stride + x];
+
+                basis[i] = near + far - 2 * centre;
+            }
+
+            const target = source[y * source_stride + x] - centre;
+
+            const at = map[map_row + (x >> 2)] * 12;
+
+            for (let i = 0; i < TAPS; i++) {
+                stats[at + TAPS * TAPS + i] += basis[i] * target;
+
+                for (let j = 0; j < TAPS; j++) {
+                    stats[at + i * TAPS + j] += basis[i] * basis[j];
+                }
+            }
+        }
+    }
+
+    // chroma's outermost tap is not coded, so it is not fitted either
+    const first = plane > 0 ? 1 : 0;
+
+    const units = unit_count(ec, plane);
+
+    for (let i = 0; i < units; i++) {
+        const index = ctx.lr_unit_index(plane, Math.floor(i / ec.restoration_columns), i % ec.restoration_columns);
+
+        solve(ec, stats, index * 12, first);
+
+        for (let j = 0; j < TAPS; j++) {
+            const tap = j < first
+                ? 0
+                : Math.round(ec.restoration_solution[j] * TAP_SCALE);
+
+            ctx.lr_wiener[index * 6 + pass * 3 + j] = clamp_tap(tap, j);
+        }
+    }
+}
+
+/**
+ * Gaussian elimination on the three by three the fit leaves, or the two by two for chroma.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {Float64Array} stats
+ * @param {number} at
+ * @param {number} first the first tap that is fitted rather than fixed at zero
+ */
+function solve(ec, stats, at, first) {
+    const n = TAPS - first;
+
+    const m = ec.restoration_system;
+    const out = ec.restoration_solution;
+
+    out.fill(0);
+
+    for (let i = 0; i < n; i++) {
+        for (let j = 0; j < n; j++) {
+            m[i * (n + 1) + j] = stats[at + (i + first) * TAPS + j + first];
+        }
+
+        m[i * (n + 1) + i] += RIDGE;
+        m[i * (n + 1) + n] = stats[at + TAPS * TAPS + i + first];
+    }
+
+    for (let column = 0; column < n; column++) {
+        let pivot = column;
+
+        for (let row = column + 1; row < n; row++) {
+            if (Math.abs(m[row * (n + 1) + column]) > Math.abs(m[pivot * (n + 1) + column])) {
+                pivot = row;
+            }
+        }
+
+        if (m[pivot * (n + 1) + column] === 0) {
+            return;
+        }
+
+        if (pivot !== column) {
+            for (let j = column; j <= n; j++) {
+                const swap = m[column * (n + 1) + j];
+
+                m[column * (n + 1) + j] = m[pivot * (n + 1) + j];
+                m[pivot * (n + 1) + j] = swap;
+            }
+        }
+
+        for (let row = 0; row < n; row++) {
+            if (row === column) {
+                continue;
+            }
+
+            const factor = m[row * (n + 1) + column] / m[column * (n + 1) + column];
+
+            if (factor === 0) {
+                continue;
+            }
+
+            for (let j = column; j <= n; j++) {
+                m[row * (n + 1) + j] -= factor * m[column * (n + 1) + j];
+            }
+        }
+    }
+
+    for (let i = 0; i < n; i++) {
+        out[i + first] = m[i * (n + 1) + n] / m[i * (n + 1) + i];
+    }
+}
+
+/**
+ * Squared error, per unit, of the restored picture and of the one it was made from.
+ *
+ * Attributed by the same rule the filter itself uses, so that a unit is judged on exactly the
+ * samples it filtered — the mapping is offset vertically by eight luma samples and getting that
+ * wrong would credit each unit with its neighbour's work.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ */
+function measure_units(ec, plane) {
+    const ctx = ec.frame_context;
+
+    const errors = ec.restoration_errors;
+
+    // only this plane's slots, so that what each plane decided on is still there afterwards — the
+    // spec reads it, and so does anyone asking why a unit went the way it did
+    const span = ctx.lr_unit_rows * ctx.lr_unit_stride;
+
+    errors.fill(0, plane * span * 2, (plane + 1) * span * 2);
+
+    const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+    const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+    const width = ctx.plane_width[plane];
+    const height = ctx.plane_height[plane];
+    const stride = ctx.plane_stride[plane];
+
+    const restored = ctx.lr_planes[plane];
+    const deringed = ctx.cdef_planes[plane];
+
+    const source = ec.source[plane];
+    const source_stride = ec.source_stride[plane];
+
+    const step_x = 4 >> sub_x;
+    const step_y = 4 >> sub_y;
+
+    for (let y = 0; y < height; y += step_y) {
+        for (let x = 0; x < width; x += step_x) {
+            const unit = restoration_unit_of(ctx, plane, (y << sub_y) >> 2, (x << sub_x) >> 2);
+
+            let with_filter = 0;
+            let without = 0;
+
+            for (let j = 0; j < step_y && y + j < height; j++) {
+                const row = (y + j) * stride;
+                const source_row = (y + j) * source_stride;
+
+                for (let i = 0; i < step_x && x + i < width; i++) {
+                    const target = source[source_row + x + i];
+
+                    const a = restored[row + x + i] - target;
+                    const b = deringed[row + x + i] - target;
+
+                    with_filter += a * a;
+                    without += b * b;
+                }
+            }
+
+            errors[unit * 2] += with_filter;
+            errors[unit * 2 + 1] += without;
+        }
+    }
+}
+
+/**
+ * Keep the filter on the units that earned it, walking them in the order they will be coded so that
+ * each one is priced against the taps the one before it left as the reference.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @returns {number} `1` if any unit kept its filter
+ */
+function keep_units(ec, plane) {
+    const ctx = ec.frame_context;
+
+    unit_count(ec, plane);
+
+    const writer = ec.restoration_writer;
+
+    const errors = ec.restoration_errors;
+
+    for (let pass = 0; pass < 2; pass++) {
+        for (let i = 0; i < TAPS; i++) {
+            ctx.ref_lr_wiener[(plane * 2 + pass) * 3 + i] = WIENER_TAPS_MID[i];
+        }
+    }
+
+    let kept = 0;
+
+    for (let unit_row = 0; unit_row < ec.restoration_rows; unit_row++) {
+        for (let unit_col = 0; unit_col < ec.restoration_columns; unit_col++) {
+            const index = ctx.lr_unit_index(plane, unit_row, unit_col);
+
+            ctx.lr_type[index] = RESTORE_WIENER;
+
+            save_reference(ec, plane);
+
+            writer.reset_costing();
+            write_lr_unit(ctx, writer, plane, unit_row, unit_col);
+
+            const with_filter = writer.cost;
+
+            restore_reference(ec, plane);
+
+            ctx.lr_type[index] = RESTORE_NONE;
+
+            writer.reset_costing();
+            write_lr_unit(ctx, writer, plane, unit_row, unit_col);
+
+            const without = writer.cost;
+
+            restore_reference(ec, plane);
+
+            if (errors[index * 2] + ec.lambda * (with_filter - without) >= errors[index * 2 + 1]) {
+                continue;
+            }
+
+            ctx.lr_type[index] = RESTORE_WIENER;
+
+            // and let the reference advance, because the unit after this one is coded against it
+            for (let pass = 0; pass < 2; pass++) {
+                for (let i = plane > 0 ? 1 : 0; i < TAPS; i++) {
+                    ctx.ref_lr_wiener[(plane * 2 + pass) * 3 + i] = ctx.lr_wiener[index * 6 + pass * 3 + i];
+                }
+            }
+
+            kept = 1;
+        }
+    }
+
+    return kept;
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ */
+function save_reference(ec, plane) {
+    const ctx = ec.frame_context;
+
+    for (let i = 0; i < 6; i++) {
+        ec.restoration_reference[i] = ctx.ref_lr_wiener[plane * 6 + i];
+    }
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ */
+function restore_reference(ec, plane) {
+    const ctx = ec.frame_context;
+
+    for (let i = 0; i < 6; i++) {
+        ctx.ref_lr_wiener[plane * 6 + i] = ec.restoration_reference[i];
+    }
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} plane
+ * @returns {number} units in the plane, and the shape of them on the encode context
+ */
+function unit_count(ec, plane) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    const sub_x = plane > 0 ? ctx.subsampling_x : 0;
+    const sub_y = plane > 0 ? ctx.subsampling_y : 0;
+
+    const unit_size = frame.loop_restoration_size[plane];
+
+    ec.restoration_rows = count_units_in_frame(unit_size, round2(frame.frame_height, sub_y));
+    ec.restoration_columns = count_units_in_frame(unit_size, round2(frame.upscaled_width, sub_x));
+
+    return ec.restoration_rows * ec.restoration_columns;
+}
+
+/**
+ * @param {Int8Array} coefficients
+ * @param {number} offset
+ * @param {Int32Array} filter
+ */
+function expand(coefficients, offset, filter) {
+    filter[3] = TAP_SCALE;
+
+    for (let i = 0; i < TAPS; i++) {
+        const c = coefficients[offset + i];
+
+        filter[i] = c;
+        filter[6 - i] = c;
+        filter[3] -= 2 * c;
+    }
+}
+
+/**
+ * @param {number} tap
+ * @param {number} j
+ * @returns {number}
+ */
+function clamp_tap(tap, j) {
+    if (tap < WIENER_TAPS_MIN[j]) {
+        return WIENER_TAPS_MIN[j];
+    }
+
+    return tap > WIENER_TAPS_MAX[j] ? WIENER_TAPS_MAX[j] : tap;
+}

package/src/avif/native/av1/encode/decode_effort.d.ts

@@ -0,0 +1,57 @@
+/**
+ * How much work the file asks of whoever reads it.
+ *
+ * The other axis to {@link EFFORT_FAST} and its neighbours, and an unrelated one. Encode effort
+ * spends *this* machine's time to make a smaller file; decode effort spends the *reader's* time to
+ * the same end, by signalling in-loop filters the decoder then has to run over the whole frame.
+ * A file is smaller with them and slower to read; the trade lands on different people.
+ *
+ * Measured over eight pictures — five of them photographs — against libavif at speed 6, at
+ * {@link EFFORT_BALANCED}, with the decode times on one megapixel of the same picture:
+ *
+ *     DECODE_FAST       +13.1% rate      115 ms/MP
+ *     DECODE_BALANCED    +8.6%           294 ms/MP
+ *     DECODE_THOROUGH    +7.9%           350 ms/MP
+ *
+ * The directional filter is the whole of that first step: four and a half points of rate for a
+ * hundred and seventy milliseconds a megapixel, because its direction search runs over every 8x8
+ * block of the frame. Restoration is the second: another seven tenths of a point for fifty-odd
+ * milliseconds. Deblocking is in all three because it is nearly free — fifteen milliseconds — and
+ * worth two and a half points.
+ *
+ * ### Why fast is the default
+ *
+ * A texture is decoded on the machine that will draw with it, once per load, competing with
+ * everything else that machine is doing. A megapixel texture five per cent larger costs a few
+ * kilobytes of download — tens of milliseconds on a slow connection, and cached after that — where
+ * the filters cost two hundred and forty milliseconds of CPU every single time it is read. For
+ * pictures that are decoded far more often than they are transferred, the fast setting is the right
+ * one by two orders of magnitude, and that is what this codec is for.
+ *
+ * Reverse it for anything whose bytes are the scarce thing: an image served to many readers over a
+ * network it is paid for by the gigabyte, where a fifth of a second on each of their machines is
+ * someone else's problem and five per cent of every transfer is yours.
+ *
+ * None of this changes fidelity at a given quality setting. What the filters buy is *rate* at
+ * matched fidelity — the same picture in fewer bytes, not a better one.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/**
+ * Deblocking only. Three times faster to read, five per cent larger.
+ * @type {number}
+ */
+export const DECODE_FAST: number;
+/**
+ * And the directional filter, which is most of what the other two settings cost and most of what
+ * they save.
+ * @type {number}
+ */
+export const DECODE_BALANCED: number;
+/**
+ * And loop restoration: the smallest file this encoder makes, and the slowest to read.
+ * @type {number}
+ */
+export const DECODE_THOROUGH: number;
+//# sourceMappingURL=decode_effort.d.ts.map

package/src/avif/native/av1/encode/decode_effort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode_effort.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/decode_effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH;;;GAGG;AACH,0BAFU,MAAM,CAEa;AAE7B;;;;GAIG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;GAGG;AACH,8BAFU,MAAM,CAEiB"}