@xprite/pixelate 0.0.0-stage → 0.1.1

package/dist/grid-period-distance.js

@@ -0,0 +1,233 @@
+import { blockPartition, MAX_RECOVERED_GRID_SIZE } from "./grid.js";
+import { PixelationAlgorithm } from "./types.js";
+/**
+ * Cell counts read from the distances between colour boundaries along each line. A boundary moves
+ * with the phase of its line, but the distance between two boundaries of one line does not, so
+ * the distances keep the pitch of a warped or row-shifted upscale whatever its phase does along
+ * the image.
+ *
+ * Boundaries are the sub-pixel peaks of the colour step along a line, after the step is summed
+ * over a few neighbouring lines, so that a cell edge, which runs across many lines, outlasts
+ * noise. The distances from every boundary to the next few of its line count, so a spurious
+ * boundary inside a cell, which puts one distance off the lattice, still leaves the distance
+ * across it on the lattice. A step scores the mean cosine of 2π times distance over step: the
+ * multiples of the step add up and the other distances cancel. Every fraction of the true step
+ * divides its multiples too and scores about as high, so among the steps near the best score the
+ * longest one that is itself a common distance stands for its axis, at the cell count it rounds to.
+ */
+const STRIDE = 4;
+const ALPHA_SCALE = 255;
+const ALPHA_CHANNEL = 3;
+/** Lines the colour step is summed over, centred on the line read. */
+const COHERENCE_LINES = 7;
+/** Lines read per axis; longer axes read evenly spread lines. */
+const MAX_LINES = 384;
+/** A boundary's step is at least EDGE_FLOOR and EDGE_SHARE of the EDGE_QUANTILE of the steps. */
+const EDGE_FLOOR = 20;
+const EDGE_SHARE = 0.1;
+const EDGE_QUANTILE = 0.95;
+/** Boundaries ahead of each boundary whose distances count. */
+const MAX_LAG = 4;
+const MIN_DISTANCE = 2;
+const MAX_DISTANCE = 64;
+const BIN = 0.25;
+const MIN_DISTANCES = 50;
+const MIN_STEP = 2.05;
+const MAX_STEP = 48;
+/** The longest step is this fraction of the axis, so that several cells hold it. */
+const MIN_PERIODS = 4;
+/** Relative spacing of the steps scored. */
+const STEP_RATIO = 1.0025;
+/** Peaks within this share of the best score tie with it. */
+const TIE_SHARE = 0.7;
+/** Share of the distances a standing step needs within FUNDAMENTAL_WINDOW of its own length. */
+const FUNDAMENTAL_SHARE = 0.04;
+const FUNDAMENTAL_WINDOW = 0.18;
+const MIN_FUNDAMENTAL_WINDOW = 0.6;
+/** Refinement: a fine search within REFINE_SPAN of the step, then least squares on the multiples. */
+const REFINE_SPAN = 0.06;
+const REFINE_RATIO = 1.0005;
+const REFINE_BIN = 0.05;
+const REFINE_PASSES = 2;
+/** A distance counts for a multiple while within this share of a step of it. */
+const REFINE_TOLERANCE = 0.3;
+const MIN_GRID_CELLS = 2;
+/** Colour step summed over COHERENCE_LINES lines, at each position of each line read. */
+function lineSteps(image, horizontal) {
+    const { width, height, data } = image;
+    const length = horizontal ? width : height, count = horizontal ? height : width;
+    const lines = Math.min(count, MAX_LINES);
+    const steps = new Float64Array(lines * (length - 1));
+    const half = (COHERENCE_LINES - 1) >> 1;
+    // Adjacent coherence windows overlap; keep each source line only until its last use.
+    const cached = new Map();
+    for (let k = 0; k < lines; k++) {
+        const centre = Math.floor(((k + 0.5) * count) / lines);
+        const first = Math.max(0, centre - half);
+        const last = Math.min(count - 1, centre + half);
+        for (const line of cached.keys())
+            if (line < first)
+                cached.delete(line);
+        for (let line = first; line <= last; line++) {
+            let values = cached.get(line);
+            if (!values) {
+                values = new Float64Array(length - 1);
+                const stride = horizontal ? STRIDE : width * STRIDE;
+                let a = (horizontal ? line * width : line) * STRIDE;
+                for (let i = 0; i + 1 < length; i++) {
+                    const b = a + stride;
+                    const alphaA = data[a + ALPHA_CHANNEL] / ALPHA_SCALE, alphaB = data[b + ALPHA_CHANNEL] / ALPHA_SCALE;
+                    let step = Math.abs(data[a + ALPHA_CHANNEL] - data[b + ALPHA_CHANNEL]);
+                    step += Math.abs(data[a] * alphaA - data[b] * alphaB);
+                    step += Math.abs(data[a + 1] * alphaA - data[b + 1] * alphaB);
+                    step += Math.abs(data[a + 2] * alphaA - data[b + 2] * alphaB);
+                    values[i] = step;
+                    a = b;
+                }
+                cached.set(line, values);
+            }
+            // Preserve the original ascending source-line summation order for every output step.
+            for (let i = 0; i + 1 < length; i++)
+                steps[k * (length - 1) + i] += values[i];
+        }
+    }
+    return { lines, length: length - 1, steps };
+}
+/** Histogram, in BIN-wide bins, of the distances between boundaries of the same line. */
+function boundaryDistances(image, horizontal) {
+    const { lines, length, steps } = lineSteps(image, horizontal);
+    const histogram = new Float64Array(Math.ceil(MAX_DISTANCE / BIN) + 1);
+    const positive = steps.filter((step) => step > 0).sort();
+    if (!positive.length)
+        return histogram;
+    const threshold = Math.max(EDGE_FLOOR, EDGE_SHARE *
+        positive[Math.min(positive.length - 1, Math.floor(EDGE_QUANTILE * positive.length))]);
+    const boundaries = [];
+    for (let k = 0; k < lines; k++) {
+        const row = k * length;
+        boundaries.length = 0;
+        for (let i = 0; i < length; i++) {
+            const here = steps[row + i], left = i > 0 ? steps[row + i - 1] : 0, right = i + 1 < length ? steps[row + i + 1] : 0;
+            if (here <= threshold || here <= left || here < right)
+                continue;
+            const curvature = left - 2 * here + right;
+            const shift = curvature ? (0.5 * (left - right)) / curvature : 0;
+            boundaries.push(i + Math.max(-0.5, Math.min(0.5, shift)));
+        }
+        for (let a = 0; a < boundaries.length; a++)
+            for (let b = a + 1; b <= Math.min(boundaries.length - 1, a + MAX_LAG); b++) {
+                const distance = boundaries[b] - boundaries[a];
+                if (distance >= MIN_DISTANCE && distance <= MAX_DISTANCE)
+                    histogram[Math.round(distance / BIN)]++;
+            }
+    }
+    return histogram;
+}
+/** Mean of cos(2π distance / step) over the distances of a histogram with bins `bin` wide. */
+function combScore(histogram, bin, step, weighted = false) {
+    let sum = 0, total = 0;
+    for (let i = 0; i < histogram.length; i++) {
+        if (!histogram[i])
+            continue;
+        const distance = i * bin;
+        const weight = histogram[i] * (weighted ? distance / step : 1);
+        sum += weight * Math.cos((2 * Math.PI * distance) / step);
+        total += weight;
+    }
+    return total ? sum / total : 0;
+}
+/** The step refined by a fine search, then by least squares over the multiples it explains. */
+function refine(histogram, step) {
+    const fine = new Float64Array(Math.ceil(MAX_DISTANCE / REFINE_BIN) + 1);
+    for (let i = 0; i < histogram.length; i++)
+        if (histogram[i])
+            fine[Math.round((i * BIN) / REFINE_BIN)] += histogram[i];
+    let best = step, bestScore = -Infinity;
+    for (let s = step * (1 - REFINE_SPAN); s <= step * (1 + REFINE_SPAN); s *= REFINE_RATIO) {
+        const score = combScore(fine, REFINE_BIN, s, true);
+        if (score > bestScore) {
+            bestScore = score;
+            best = s;
+        }
+    }
+    for (let pass = 0; pass < REFINE_PASSES; pass++) {
+        let numerator = 0, denominator = 0;
+        for (let i = 0; i < fine.length; i++) {
+            if (!fine[i])
+                continue;
+            const distance = i * REFINE_BIN;
+            const order = Math.round(distance / best);
+            if (order < 1)
+                continue;
+            const weight = fine[i] *
+                order *
+                Math.max(0, 1 - Math.abs(distance - order * best) / (REFINE_TOLERANCE * best));
+            numerator += weight * order * distance;
+            denominator += weight * order * order;
+        }
+        if (denominator <= 0)
+            break;
+        best = numerator / denominator;
+    }
+    return best;
+}
+/** The standing step of an axis, or null when its boundaries are too few or keep no step. */
+function axisStep(image, horizontal) {
+    const length = horizontal ? image.width : image.height;
+    const longest = Math.min(MAX_STEP, length / MIN_PERIODS);
+    if (longest <= MIN_STEP)
+        return null;
+    const histogram = boundaryDistances(image, horizontal);
+    let total = 0;
+    for (const count of histogram)
+        total += count;
+    if (total < MIN_DISTANCES)
+        return null;
+    const steps = [];
+    for (let step = MIN_STEP; step <= longest; step *= STEP_RATIO)
+        steps.push(step);
+    const scores = steps.map((step) => combScore(histogram, BIN, step));
+    const peaks = [];
+    for (let i = 1; i + 1 < steps.length; i++)
+        if (scores[i] > scores[i - 1] && scores[i] >= scores[i + 1] && scores[i] > 0)
+            peaks.push(i);
+    if (!peaks.length)
+        return null;
+    peaks.sort((a, b) => scores[b] - scores[a]);
+    const top = scores[peaks[0]];
+    const support = (step) => {
+        const window = Math.max(MIN_FUNDAMENTAL_WINDOW, FUNDAMENTAL_WINDOW * step);
+        let near = 0;
+        for (let i = 0; i < histogram.length; i++)
+            if (Math.abs(i * BIN - step) < window)
+                near += histogram[i];
+        return near / total;
+    };
+    const tied = peaks
+        .filter((i) => scores[i] >= TIE_SHARE * top)
+        .sort((a, b) => steps[b] - steps[a])
+        .find((i) => support(steps[i]) >= FUNDAMENTAL_SHARE);
+    return refine(histogram, steps[tied ?? peaks[0]]);
+}
+/**
+ * The lattice covering the image at the cell counts of the axes' standing steps; an axis without
+ * one takes the other's.
+ */
+export function distanceCountGrids(image) {
+    const across = axisStep(image, true), down = axisStep(image, false);
+    const x = across ?? down, y = down ?? across;
+    if (x === null || y === null)
+        return [];
+    const columns = Math.round(image.width / x), rows = Math.round(image.height / y);
+    const fits = (count, length) => count >= MIN_GRID_CELLS && count <= Math.min(length, MAX_RECOVERED_GRID_SIZE);
+    if (!fits(columns, image.width) || !fits(rows, image.height))
+        return [];
+    return [
+        {
+            ...blockPartition(image, columns, rows),
+            confidence: 0,
+            reliable: true,
+            algorithm: PixelationAlgorithm.UniformGrid,
+        },
+    ];
+}

package/dist/grid-phase-field.d.ts

@@ -0,0 +1,11 @@
+import { type ChanceEvidenceFragments, type ChanceEvidenceStop, type StripImage, type StripShear } from "./grid-strip-shift.ts";
+/** The grid read through phase fields, or null when no line of any band moves. */
+export declare function phaseField(strips: StripImage, cutsX: readonly number[], cutsY: readonly number[]): (StripShear & {
+    bandsX: number;
+    bandsY: number;
+}) | null;
+/**
+ * Phase evidence the field search finds without the grid, per sample: on each axis, the most it
+ * finds at the off-pitch factors with the same number of bands, averaged over the two axes.
+ */
+export declare function fieldChanceEvidence(strips: StripImage, cutsX: readonly number[], cutsY: readonly number[], bandsX: number, bandsY: number, stopIfCannotWin?: ChanceEvidenceStop, fragments?: ChanceEvidenceFragments): number;

package/dist/grid-phase-field.js

@@ -0,0 +1,446 @@
+import { colourStepCost, RESIDUAL_FLOOR, } from "./grid-description-length.js";
+import { shiftedGridImage } from "./grid-sampling.js";
+import { intervalEnergy, linePrefix, OFF_PITCH_FACTORS, offPitch, } from "./grid-strip-shift.js";
+import { PixelGridSamplingAxis } from "./types.js";
+/**
+ * Phase fields of a grid: the lattice keeps its pitch, but its phase may drift along the image and
+ * differ from one part of it to another, as a warped upscale or a sheet of separately placed
+ * sprites displaces it. Split the cells across an axis into bands; along every band, each
+ * described line moves the cuts by a whole pixel shift, and the shift holds from line to line
+ * unless a change pays for itself. Each band names its first shift, and every change names its
+ * line and either a step of one pixel or a new shift, so a field that follows noise pays for it
+ * while a smooth warp pays little. Moving lines apart drops the input pixels between them, and
+ * moving a line past the image's end drops the pixels it leaves; the straightened image does not
+ * hold them, so the field pays for coding each on its own. The shifts are chosen by dynamic
+ * programming on the variance left inside the cells, coded at the residual variance, and on the
+ * pixels they drop; the split into bands is the one whose field codes the axis shortest. The
+ * column cuts are settled first, the row cuts then on the straightened columns.
+ *
+ * The twin confines every line's shift to the anti-phase of its own (a quarter to three quarters
+ * of a cell away), and `fieldChanceEvidence` measures the phase evidence the same search finds at
+ * pitches the grid does not have.
+ */
+const CHANNELS = 3;
+const HALF = 0.5;
+const ANTI_PHASE_FROM = 0.25;
+const ANTI_PHASE_TO = 0.75;
+/** Bands of cells an axis may be split into; each band follows its own shifts. */
+const BAND_COUNTS = [1, 2, 3, 4];
+/** Cells a band needs, so that its shifts are read on more than a few features. */
+const MIN_BAND_CELLS = 8;
+/** Dynamic programming passes; each codes the field at the residual variance of the last. */
+const REFITS = 2;
+/**
+ * Cells a shift may reach either way. Beyond half a cell the cuts repeat, but a warp that moves the
+ * content further must be followed there, or the straightened lines would slip a cell apart.
+ */
+const REACH = 1;
+const TIE = 1e-9;
+const dropTables = new WeakMap();
+/**
+ * Per described line, the cumulative nats of coding each pixel's colour against its neighbour
+ * (see colourStepCost). Where a dropped pixel lies follows from the shifts, and the straightened
+ * image holds a repeated pixel in its place, which already pays the residual floor.
+ */
+function dropTable(prefix) {
+    const cached = dropTables.get(prefix);
+    if (cached)
+        return cached;
+    const { length, lines, sums } = prefix;
+    const drops = new Float64Array(lines.length * (length + 1));
+    for (let k = 0; k < lines.length; k++) {
+        // linePrefix accumulates nonnegative squared premultiplied RGB; a zero sum codes a zero line.
+        if (sums[(k + 1) * (length + 1) * (CHANNELS + 1) - 1] === 0)
+            continue;
+        const base = k * (length + 1) * (CHANNELS + 1), row = k * (length + 1);
+        let previousRed = 0, previousGreen = 0, previousBlue = 0;
+        for (let p = 0; p < length; p++) {
+            const at = base + (p + 1) * (CHANNELS + 1), before = at - (CHANNELS + 1);
+            const red = sums[at] - sums[before];
+            const green = sums[at + 1] - sums[before + 1];
+            const blue = sums[at + 2] - sums[before + 2];
+            let neighbourRed = previousRed, neighbourGreen = previousGreen, neighbourBlue = previousBlue;
+            if (p === 0) {
+                const neighbour = Math.min(length - 1, 1);
+                const neighbourAt = base + (neighbour + 1) * (CHANNELS + 1), neighbourBefore = neighbourAt - (CHANNELS + 1);
+                neighbourRed = sums[neighbourAt] - sums[neighbourBefore];
+                neighbourGreen = sums[neighbourAt + 1] - sums[neighbourBefore + 1];
+                neighbourBlue = sums[neighbourAt + 2] - sums[neighbourBefore + 2];
+            }
+            let step = 0;
+            step += (red - neighbourRed) ** 2;
+            step += (green - neighbourGreen) ** 2;
+            step += (blue - neighbourBlue) ** 2;
+            drops[row + p + 1] = drops[row + p] + colourStepCost(step);
+            previousRed = red;
+            previousGreen = green;
+            previousBlue = blue;
+        }
+    }
+    dropTables.set(prefix, drops);
+    return drops;
+}
+function energyTable(prefix, cuts, first, last) {
+    const { length, lines, sums: line } = prefix;
+    const cells = cuts.length - 1, span = last - first + 1;
+    // Every bandEnergy caller uses bandsOf for a supported split, including the anti-field.
+    // Keep all cell additions, storing only the prefixes those splits can query.
+    const needed = new Set([0, cells]);
+    for (const count of BAND_COUNTS) {
+        if (count > 1 && cells < count * MIN_BAND_CELLS)
+            break;
+        for (const boundary of bandsOf(cells, count))
+            needed.add(boundary);
+    }
+    const boundaries = [...needed].sort((a, b) => a - b);
+    const bandStride = boundaries.length;
+    const bandSlots = new Int32Array(cells + 1).fill(-1);
+    for (let slot = 0; slot < bandStride; slot++)
+        bandSlots[boundaries[slot]] = slot;
+    const sums = new Float64Array(lines.length * span * bandStride);
+    // Shifted cut bounds are identical on every described line.
+    const froms = new Float64Array(span * cells), tos = new Float64Array(span * cells);
+    for (let j = 0; j < span; j++) {
+        const shift = first + j;
+        for (let i = 0; i < cells; i++) {
+            const from = i === 0 ? 0 : Math.max(0, Math.min(length, cuts[i] + shift));
+            const to = i + 1 === cells ? length : Math.max(0, Math.min(length, cuts[i + 1] + shift));
+            froms[j * cells + i] = from;
+            tos[j * cells + i] = Math.max(from, to);
+        }
+    }
+    // Different shifts/cells often request the exact same source interval. Evaluate it once,
+    // then retain the original line/shift/cell order of additions into the cumulative table.
+    const ids = new Int32Array(froms.length);
+    const unique = new Map();
+    const uniqueFroms = [], uniqueTos = [];
+    for (let i = 0; i < froms.length; i++) {
+        const key = `${froms[i]},${tos[i]}`;
+        let id = unique.get(key);
+        if (id === undefined) {
+            id = uniqueFroms.length;
+            unique.set(key, id);
+            uniqueFroms.push(froms[i]);
+            uniqueTos.push(tos[i]);
+        }
+        ids[i] = id;
+    }
+    const intervalEnergies = new Float64Array(uniqueFroms.length);
+    // Preserve non-integer typed-array lookup behaviour for fractional cell boundaries.
+    const zeroLineSafe = uniqueFroms.every((from, i) => Number.isInteger(from) &&
+        Number.isInteger(uniqueTos[i]) &&
+        from >= 0 &&
+        from <= length &&
+        uniqueTos[i] >= 0 &&
+        uniqueTos[i] <= length);
+    for (let k = 0; k < lines.length; k++) {
+        // linePrefix accumulates nonnegative squared premultiplied RGB; a zero sum codes a zero line.
+        if (zeroLineSafe && line[(k + 1) * (length + 1) * (CHANNELS + 1) - 1] === 0)
+            continue;
+        const base = k * (length + 1) * (CHANNELS + 1);
+        for (let i = 0; i < intervalEnergies.length; i++)
+            intervalEnergies[i] = intervalEnergy(line, base, uniqueFroms[i], uniqueTos[i]);
+        for (let j = 0; j < span; j++) {
+            const row = (k * span + j) * bandStride, bounds = j * cells;
+            let total = 0, cell = 0;
+            for (let slot = 1; slot < bandStride; slot++) {
+                for (; cell < boundaries[slot]; cell++)
+                    total += intervalEnergies[ids[bounds + cell]];
+                sums[row + slot] = total;
+            }
+        }
+    }
+    return {
+        prefix,
+        cuts,
+        cells,
+        first,
+        span,
+        sums,
+        bandSlots,
+        bandStride,
+        drops: dropTable(prefix),
+    };
+}
+const bandEnergy = (table, k, j, from, to) => {
+    const row = (k * table.span + j) * table.bandStride;
+    return table.sums[row + table.bandSlots[to]] - table.sums[row + table.bandSlots[from]];
+};
+/** Nats of coding the pixels [from, to) of line k on their own. */
+function dropped(table, k, from, to) {
+    const { length } = table.prefix;
+    const low = Math.max(0, Math.min(length, from)), high = Math.max(0, Math.min(length, to));
+    if (high <= low)
+        return 0;
+    const row = k * (length + 1);
+    return table.drops[row + high] - table.drops[row + low];
+}
+/**
+ * The shift of every line along the cells [from, to) that codes them shortest, each pixel's
+ * variance costing `scale` nats and the pixels a shift drops `drop` nats. `window` confines a
+ * line's shifts. Shifts a whole cell apart cut the lines alike, so on equal cuts the path keeps to
+ * the smaller shift.
+ */
+function bandPath(table, from, to, scale, change, window, drop) {
+    const lines = table.prefix.lines.length, { span, first } = table;
+    const back = new Int32Array(lines * span);
+    let previous = new Float64Array(span), current = new Float64Array(span), best = Infinity, bestAt = -1;
+    const tieBias = Float64Array.from({ length: span }, (_, j) => Math.abs(first + j) * TIE);
+    for (let k = 0; k < lines; k++) {
+        const [low, high] = window(k);
+        let nextBest = Infinity, nextBestAt = -1;
+        const jumpCost = best + change.jump;
+        for (let j = 0; j < span; j++) {
+            const shift = first + j;
+            if (shift < low || shift > high) {
+                current[j] = Infinity;
+                continue;
+            }
+            const energy = bandEnergy(table, k, j, from, to) * scale + drop(k, shift) + tieBias[j];
+            if (k === 0) {
+                current[j] = energy;
+                if (current[j] < nextBest) {
+                    nextBest = current[j];
+                    nextBestAt = j;
+                }
+                continue;
+            }
+            let cost = previous[j], source = j;
+            if (j > 0 && previous[j - 1] + change.step < cost) {
+                cost = previous[j - 1] + change.step;
+                source = j - 1;
+            }
+            if (j + 1 < span && previous[j + 1] + change.step < cost) {
+                cost = previous[j + 1] + change.step;
+                source = j + 1;
+            }
+            if (jumpCost < cost) {
+                cost = jumpCost;
+                source = bestAt;
+            }
+            current[j] = cost + energy;
+            if (current[j] < nextBest) {
+                nextBest = current[j];
+                nextBestAt = j;
+            }
+            back[k * span + j] = source;
+        }
+        const scratch = previous;
+        previous = current;
+        current = scratch;
+        best = nextBest;
+        bestAt = nextBestAt;
+    }
+    let at = 0;
+    for (let j = 1; j < span; j++)
+        if (previous[j] < previous[at])
+            at = j;
+    const shifts = new Int32Array(lines);
+    let energy = 0, cost = 0;
+    for (let k = lines - 1; k >= 0; k--) {
+        shifts[k] = first + at;
+        energy += bandEnergy(table, k, at, from, to);
+        cost += drop(k, shifts[k]);
+        if (k > 0) {
+            const before = back[k * span + at];
+            if (before !== at)
+                cost += Math.abs(before - at) === 1 ? change.step : change.jump;
+            at = before;
+        }
+    }
+    return { shifts, energy, cost };
+}
+const pitchOf = (cuts) => (cuts[cuts.length - 1] - cuts[0]) / (cuts.length - 1);
+function shiftRange(cuts) {
+    const pitch = pitchOf(cuts);
+    const reach = Math.round(pitch * REACH);
+    return { low: -reach, high: reach, pitch };
+}
+function bandsOf(cells, count) {
+    return Array.from({ length: count + 1 }, (_, b) => Math.round((b * cells) / count));
+}
+/**
+ * The field of one band split. Without `anchor` every shift lies within REACH; with it, every
+ * line's shift lies in the anti-phase window of the anchor's. A line's pixels between where the
+ * band before it ends and where its own band starts reading, or before the first band and past
+ * the last, drop out of the straightened image; the bands are settled in order, each paying for
+ * the pixels it drops after the one before.
+ */
+function splitField(table, bands, variance, anchor) {
+    const { low, high, pitch } = table.range;
+    const { length } = table.prefix;
+    const options = high - low + 1;
+    const line = Math.log(Math.max(2, table.prefix.lines.length)) + Math.LN2;
+    const change = { step: line + Math.LN2, jump: line + Math.log(options - 1) };
+    const shifts = [];
+    const stationaryWindow = [low, high];
+    let energy = 0, cost = 0;
+    for (let b = 0; b + 1 < bands.length; b++) {
+        const window = anchor
+            ? (k) => [
+                Math.ceil(anchor.shifts[b][k] + ANTI_PHASE_FROM * pitch),
+                Math.floor(anchor.shifts[b][k] + ANTI_PHASE_TO * pitch),
+            ]
+            : () => stationaryWindow;
+        const start = b === 0 ? 0 : table.cuts[bands[b]], before = shifts[b - 1], last = b + 2 === bands.length;
+        const drop = (k, shift) => dropped(table, k, before ? start + before[k] : 0, start + shift) +
+            (last && shift < 0 ? dropped(table, k, length + shift, length) : 0);
+        const path = bandPath(table, bands[b], bands[b + 1], 1 / (2 * variance), change, window, drop);
+        shifts.push(path.shifts);
+        energy += path.energy;
+        cost += Math.log(options) + path.cost;
+    }
+    return { bands: [...bands], shifts, energy, cost };
+}
+function rangedTable(prefix, cuts) {
+    const range = shiftRange(cuts);
+    const last = range.high + Math.floor(ANTI_PHASE_TO * range.pitch);
+    return { ...energyTable(prefix, cuts, range.low, last), range };
+}
+const samplesOf = (prefix) => prefix.lines.length * prefix.length * CHANNELS;
+/** Description length, in nats, of an axis's residual and shifts under a field. */
+const fieldLength = (field, samples) => (samples / 2) * Math.log(field.energy / samples + RESIDUAL_FLOOR) + field.cost;
+/** The band split, and its field, that codes the axis shortest. */
+function bestField(table, bandCounts = BAND_COUNTS) {
+    const samples = samplesOf(table.prefix);
+    let still = 0;
+    for (let k = 0; k < table.prefix.lines.length; k++)
+        still += bandEnergy(table, k, -table.first, 0, table.cells);
+    let best = null;
+    for (const count of bandCounts) {
+        if (count > 1 && table.cells < count * MIN_BAND_CELLS)
+            break;
+        const bands = bandsOf(table.cells, count);
+        let variance = still / samples + RESIDUAL_FLOOR;
+        let field = splitField(table, bands, variance);
+        for (let pass = 1; pass < REFITS; pass++) {
+            variance = field.energy / samples + RESIDUAL_FLOOR;
+            field = splitField(table, bands, variance);
+        }
+        if (!best || fieldLength(field, samples) < fieldLength(best, samples))
+            best = field;
+    }
+    return best;
+}
+/**
+ * The image with each field line moved back by its shift. Reads interpolate by the original
+ * nearest described line rule; an exact midpoint chooses the later line.
+ */
+function unfield(image, vertical, cuts, lines, field) {
+    const count = vertical ? image.width : image.height;
+    const across = [0];
+    for (let i = 1; i < lines.length; i++)
+        across.push(Math.ceil((lines[i - 1] + lines[i]) / 2));
+    across.push(count);
+    return shiftedGridImage(image, {
+        axis: vertical ? PixelGridSamplingAxis.Vertical : PixelGridSamplingAxis.Horizontal,
+        bands: field.bands.map((cell) => cuts[cell]),
+        across,
+        shifts: field.shifts,
+    });
+}
+const moved = (field) => field.shifts.some((shifts) => shifts.some(Boolean));
+/** The field of a table confined to the anti-phase of `anchor`'s shifts, for the twin. */
+function antiField(table, anchor) {
+    const variance = anchor.energy / samplesOf(table.prefix) + RESIDUAL_FLOOR;
+    return splitField(table, anchor.bands, variance, anchor);
+}
+/** Only the most recent x geometry may retain its normal/anti row prefixes. */
+const lastColumns = new WeakMap();
+function columnView(strips, cutsX, table, field) {
+    const once = moved(field)
+        ? unfield(strips.image, false, cutsX, table.prefix.lines, field)
+        : strips.image;
+    return {
+        once,
+        rowPrefix: once === strips.image ? strips.prefix(true) : linePrefix(once, true),
+    };
+}
+function columnsOf(strips, cutsX) {
+    const key = cutsX.join(",");
+    const cached = lastColumns.get(strips);
+    if (cached?.key === key)
+        return cached;
+    const table = rangedTable(strips.prefix(false), cutsX);
+    const field = bestField(table);
+    const entry = { key, table, field, ...columnView(strips, cutsX, table, field) };
+    lastColumns.set(strips, entry);
+    return entry;
+}
+/**
+ * Keep this closure separate from columnsOf/phaseField: retained readings must not retain an
+ * evicted cache entry's normal/anti line prefixes. Only the last WeakMap entry owns those.
+ */
+function fieldTwin(strips, cutsX, cutsY, columnTable, columns, rows) {
+    return () => {
+        const cached = lastColumns.get(strips);
+        const anti = cached?.table === columnTable
+            ? (cached.anti ??= columnView(strips, cutsX, columnTable, antiField(columnTable, columns)))
+            : columnView(strips, cutsX, columnTable, antiField(columnTable, columns));
+        const rowTable = rangedTable(anti.rowPrefix, cutsY);
+        const rowField = antiField(rowTable, rows);
+        return moved(rowField)
+            ? unfield(anti.once, true, cutsY, rowTable.prefix.lines, rowField)
+            : anti.once;
+    };
+}
+/** The grid read through phase fields, or null when no line of any band moves. */
+export function phaseField(strips, cutsX, cutsY) {
+    const { table: columnTable, field: columns, once, rowPrefix } = columnsOf(strips, cutsX);
+    const rowTable = rangedTable(rowPrefix, cutsY);
+    const rows = bestField(rowTable);
+    const straight = moved(rows) ? unfield(once, true, cutsY, rowTable.prefix.lines, rows) : once;
+    if (!moved(columns) && !moved(rows))
+        return null;
+    return {
+        straight,
+        cost: columns.cost + rows.cost,
+        twin: fieldTwin(strips, cutsX, cutsY, columnTable, columns, rows),
+        bandsX: columns.bands.length - 1,
+        bandsY: rows.bands.length - 1,
+    };
+}
+/** Phase evidence, per sample, of one axis's field: its shifts against their anti-phase. */
+function axisEvidence(prefix, cuts, bands) {
+    const table = rangedTable(prefix, cuts);
+    const samples = samplesOf(prefix);
+    const best = bestField(table, [
+        Math.min(bands, Math.max(1, Math.floor(table.cells / MIN_BAND_CELLS))),
+    ]);
+    const anti = antiField(table, best);
+    return (HALF *
+        Math.log((anti.energy / samples + RESIDUAL_FLOOR) / (best.energy / samples + RESIDUAL_FLOOR)));
+}
+/**
+ * Phase evidence the field search finds without the grid, per sample: on each axis, the most it
+ * finds at the off-pitch factors with the same number of bands, averaged over the two axes.
+ */
+export function fieldChanceEvidence(strips, cutsX, cutsY, bandsX, bandsY, stopIfCannotWin, fragments) {
+    const axes = [false, true];
+    let total = 0, remaining = axes.length * OFF_PITCH_FACTORS.length, slot = 0;
+    for (const vertical of axes) {
+        const cuts = vertical ? cutsY : cutsX;
+        let most = 0;
+        for (const factor of OFF_PITCH_FACTORS) {
+            const off = offPitch(cuts, factor);
+            if (off) {
+                let value = fragments?.[slot];
+                if (value === undefined) {
+                    value = axisEvidence(strips.prefix(vertical), off, vertical ? bandsY : bandsX);
+                    if (fragments)
+                        fragments[slot] = value;
+                }
+                most = Math.max(most, value);
+            }
+            slot++;
+            remaining--;
+            if (stopIfCannotWin && remaining > 0) {
+                const lowerBound = (total + most) * HALF;
+                if (Number.isFinite(lowerBound) && lowerBound >= 0 && stopIfCannotWin(lowerBound))
+                    return Infinity;
+            }
+        }
+        total += most;
+    }
+    return total * HALF;
+}