@woosh/meep-engine 3.9.0 → 3.10.0

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

@@ -0,0 +1,318 @@
+import { DECODE_BALANCED } from "./decode_effort.js";
+import { apply_cdef } from "../filter/cdef.js";
+import { apply_loop_filter } from "../filter/loop_filter.js";
+
+/**
+ * Coarse deblocking levels to measure before refining around the best of them.
+ *
+ * The curve of error against filter level has one minimum and is not steep near it, so a handful of
+ * points across the range finds the neighbourhood and a step either side finishes the job. Zero is
+ * in the list because "do not filter at all" is a real answer at high quality.
+ * @type {number[]}
+ */
+const LEVEL_LADDER = [0, 2, 5, 10, 18, 32, 52];
+
+/**
+ * Directional strengths to measure, as primary and secondary pairs.
+ *
+ * The primary filter runs along the edge the block's dominant direction names and the secondary
+ * across it, and what a picture wants of them is not separable — so they are searched as pairs
+ * rather than one at a time. The secondary strength is coded in two bits with three meaning four,
+ * which is why three is not among them.
+ *
+ * Ordered so that a prefix of it still spans the range rather than crowding the weak end: the
+ * search is truncated to `cdef_trials` and each entry costs a pass over the whole frame, so the
+ * first four have to be a usable answer on their own.
+ * @type {number[]}
+ */
+const STRENGTH_LADDER = [
+    0, 0,
+    2, 1,
+    6, 2,
+    1, 0,
+    11, 4,
+    4, 2,
+    1, 1,
+    8, 2,
+    2, 2,
+    0, 1,
+    3, 1,
+    15, 4
+];
+
+/**
+ * Choose the frame's in-loop filter strengths, after everything has been coded.
+ *
+ * The in-loop filters are the coding tools an AV1 encoder decides *after* it has finished coding,
+ * and that is not a shortcut — it is where they live. They run over the whole frame once decoding
+ * is done; intra prediction reads the reconstruction from before them, so nothing a block was coded
+ * against changes, and with one strength for the frame they cost a few bits in the frame header and
+ * not one symbol in the tile. So the encoder codes the picture, then asks which strengths bring the
+ * result closest to the source, and writes those.
+ *
+ * Deblocking comes first and directional enhancement second, in that order, because that is the
+ * order the decoder applies them and the second is choosing what to do about what the first left.
+ *
+ * @param {Av1EncodeContext} ec
+ * @see AV1 spec 7.14 "Loop filter process" and 7.15 "CDEF process", of which this picks the strengths
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function choose_filters(ec) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    frame.loop_filter_level[0] = 0;
+    frame.loop_filter_level[1] = 0;
+    frame.loop_filter_level[2] = 0;
+    frame.loop_filter_level[3] = 0;
+
+    frame.cdef_y_pri_strength[0] = 0;
+    frame.cdef_y_sec_strength[0] = 0;
+    frame.cdef_uv_pri_strength[0] = 0;
+    frame.cdef_uv_sec_strength[0] = 0;
+
+    // a lossless frame signals no filter at all, and would not be lossless if it did
+    if (frame.coded_lossless === 1) {
+        ec.sequence.enable_cdef = 0;
+
+        return;
+    }
+
+    ec.resize_filters(ctx);
+
+    save_planes(ec);
+
+    if (ec.filter_trials > 0) {
+        const luma = choose_level(ec, 0);
+
+        frame.loop_filter_level[0] = luma;
+        frame.loop_filter_level[1] = luma;
+
+        if (ctx.num_planes > 1 && luma > 0) {
+            // chroma is only filtered at all when luma is: the format codes its levels behind that
+            frame.loop_filter_level[2] = choose_level(ec, 1);
+            frame.loop_filter_level[3] = frame.loop_filter_level[2];
+        }
+
+        // leave the frame as the decoder will have it at this point, which is what the directional
+        // filter is choosing what to do about
+        restore_planes(ec);
+
+        apply_loop_filter(ctx);
+    }
+
+    choose_cdef(ec);
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {number} first the first plane the error is measured over; `0` for luma, `1` for chroma
+ * @returns {number} the level that leaves the least squared error
+ */
+function choose_level(ec, first) {
+    let best = 0;
+    let best_error = Infinity;
+
+    for (let i = 0; i < LEVEL_LADDER.length && i < ec.filter_trials; i++) {
+        const level = LEVEL_LADDER[i];
+
+        const error = deblocked_error(ec, first, level);
+
+        if (error < best_error) {
+            best_error = error;
+            best = level;
+        }
+    }
+
+    // one step either side of the winner, which is as fine as a filter level is worth resolving
+    for (let step = -1; step <= 1; step += 2) {
+        const level = best + step;
+
+        if (level < 0 || level > 63) {
+            continue;
+        }
+
+        const error = deblocked_error(ec, first, level);
+
+        if (error < best_error) {
+            best_error = error;
+            best = level;
+        }
+    }
+
+    return best;
+}
+
+/**
+ * Deblock a copy of the frame at one level and measure what it left.
+ *
+ * @param {Av1EncodeContext} ec
+ * @param {number} first
+ * @param {number} level
+ * @returns {number} squared error against the source
+ */
+function deblocked_error(ec, first, level) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    if (first === 0) {
+        frame.loop_filter_level[0] = level;
+        frame.loop_filter_level[1] = level;
+    } else {
+        frame.loop_filter_level[2] = level;
+        frame.loop_filter_level[3] = level;
+    }
+
+    restore_planes(ec);
+
+    apply_loop_filter(ctx);
+
+    return plane_group_error(ec, ctx.planes, first);
+}
+
+/**
+ * Choose the directional filter's strengths, over a frame the deblocker has already been through.
+ *
+ * Luma and chroma are independent — each strength touches only its own planes — so one pass over
+ * the frame measures one candidate for each, and the two winners can be read off separately from
+ * the same sweep rather than costing a sweep apiece.
+ *
+ * @param {Av1EncodeContext} ec
+ */
+function choose_cdef(ec) {
+    const ctx = ec.frame_context;
+    const frame = ec.frame;
+
+    const trials = Math.min(ec.cdef_trials, STRENGTH_LADDER.length / 2);
+
+    // the one in-loop filter that costs the reader real time. Whether the file has one at all is
+    // `decode_effort`; how hard this encoder looks for the strength, once it does, is `cdef_trials`
+    if (ec.decode_effort < DECODE_BALANCED || trials < 1) {
+        ec.sequence.enable_cdef = 0;
+
+        return;
+    }
+
+    let best_luma = 0;
+    let best_luma_error = Infinity;
+
+    let best_chroma = 0;
+    let best_chroma_error = Infinity;
+
+    for (let i = 0; i < trials; i++) {
+        frame.cdef_y_pri_strength[0] = STRENGTH_LADDER[i * 2];
+        frame.cdef_y_sec_strength[0] = STRENGTH_LADDER[i * 2 + 1];
+        frame.cdef_uv_pri_strength[0] = STRENGTH_LADDER[i * 2];
+        frame.cdef_uv_sec_strength[0] = STRENGTH_LADDER[i * 2 + 1];
+
+        apply_cdef(ctx);
+
+        const luma_error = plane_group_error(ec, ctx.cdef_planes, 0);
+
+        if (luma_error < best_luma_error) {
+            best_luma_error = luma_error;
+            best_luma = i;
+        }
+
+        if (ctx.num_planes > 1) {
+            const chroma_error = plane_group_error(ec, ctx.cdef_planes, 1);
+
+            if (chroma_error < best_chroma_error) {
+                best_chroma_error = chroma_error;
+                best_chroma = i;
+            }
+        }
+    }
+
+    frame.cdef_y_pri_strength[0] = STRENGTH_LADDER[best_luma * 2];
+    frame.cdef_y_sec_strength[0] = STRENGTH_LADDER[best_luma * 2 + 1];
+    frame.cdef_uv_pri_strength[0] = STRENGTH_LADDER[best_chroma * 2];
+    frame.cdef_uv_sec_strength[0] = STRENGTH_LADDER[best_chroma * 2 + 1];
+
+    // filtering at no strength is the same picture as not filtering, so say so and save the decoder
+    // a pass over the frame
+    if (best_luma === 0 && best_chroma === 0) {
+        ec.sequence.enable_cdef = 0;
+    }
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {Uint16Array[]} planes
+ * @param {number} first `0` measures luma alone, `1` measures the chroma planes
+ * @returns {number}
+ */
+function plane_group_error(ec, planes, first) {
+    const ctx = ec.frame_context;
+
+    const last = first === 0 ? 1 : ctx.num_planes;
+
+    let error = 0;
+
+    for (let plane = first; plane < last; plane++) {
+        error += plane_error(ec, planes[plane], plane);
+    }
+
+    return error;
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ * @param {Uint16Array} reconstruction
+ * @param {number} plane
+ * @returns {number}
+ */
+function plane_error(ec, reconstruction, plane) {
+    const ctx = ec.frame_context;
+
+    const stride = ctx.plane_stride[plane];
+
+    const source = ec.source[plane];
+    const source_stride = ec.source_stride[plane];
+
+    const width = ctx.plane_width[plane];
+    const height = ctx.plane_height[plane];
+
+    let error = 0;
+
+    for (let y = 0; y < height; y++) {
+        const a = y * stride;
+        const b = y * source_stride;
+
+        for (let x = 0; x < width; x++) {
+            const difference = reconstruction[a + x] - source[b + x];
+
+            error += difference * difference;
+        }
+    }
+
+    return error;
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ */
+function save_planes(ec) {
+    const ctx = ec.frame_context;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const samples = ctx.plane_stride[plane] * ctx.plane_rows[plane];
+
+        ec.unfiltered[plane].set(ctx.planes[plane].subarray(0, samples));
+    }
+}
+
+/**
+ * @param {Av1EncodeContext} ec
+ */
+function restore_planes(ec) {
+    const ctx = ec.frame_context;
+
+    for (let plane = 0; plane < ctx.num_planes; plane++) {
+        const samples = ctx.plane_stride[plane] * ctx.plane_rows[plane];
+
+        ctx.planes[plane].set(ec.unfiltered[plane].subarray(0, samples));
+    }
+}

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

@@ -0,0 +1,35 @@
+/**
+ * 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: Av1EncodeContext): void;
+//# sourceMappingURL=choose_restoration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"choose_restoration.d.ts","sourceRoot":"","sources":["../../../../../../src/avif/native/av1/encode/choose_restoration.js"],"names":[],"mappings":"AA4BA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,+DA+CC"}