@xprite/pixelate 0.0.0-stage → 0.1.1

package/dist/grid-period-boundary.js

@@ -0,0 +1,255 @@
+import { MAX_GRID_CELL_SIZE, MAX_RECOVERED_GRID_SIZE, pixelGridCuts, } from "./grid.js";
+import { PixelationAlgorithm } from "./types.js";
+/**
+ * Boundary run-length comb period detection for painterly and similar inputs where soft pitch
+ * search and edge detection may fail. Counts run lengths of the same boundary color along the
+ * image edges, scores uniform step hypotheses by how well they comb those runs, and proposes
+ * lattices whose periods match the detected step on each axis.
+ *
+ * This is an additional candidate source that feeds the arbiter alongside edge/uniform/pitch
+ * detectors; it does not replace them. The arbiter's min-DL still chooses the final grid among
+ * all proposals and the passthrough baseline.
+ */
+const MIN_STEP = 2.0;
+const MIN_CELLS = 4;
+const MIN_GRID_CELLS = 16;
+const MAX_STEP_SEARCH = 48; // Expanded to cover larger periods
+const STEP_INCREMENT = 0.05; // Finer granularity for better precision
+/** Number of top-scoring periods to consider per axis. */
+const MAX_CANDIDATES_PER_AXIS = 8;
+/** Exponential weight decay for successive comb teeth (k0 in the reference). */
+const DECAY_CONSTANT = 12.0;
+/** Maximum teeth count (comb order) when scoring a period. */
+const MAX_COMB_ORDER = 24;
+/**
+ * Extract run lengths of consecutive similar colors across sampled lines.
+ * Uses a more permissive threshold to catch soft edges in painterly inputs.
+ */
+function extractColorRuns(image, horizontal) {
+    const { width, height, data } = image;
+    const scanLength = horizontal ? width : height;
+    const crossLength = horizontal ? height : width;
+    // Sample more lines for better statistics
+    const maxSampledLines = 128;
+    const stride = Math.max(1, Math.floor(crossLength / maxSampledLines));
+    const runs = [];
+    // Looser threshold for painterly/blurred edges
+    const COLOR_THRESHOLD = 30;
+    for (let line = 0; line < crossLength; line += stride) {
+        let runLength = 0;
+        let lastR = -1, lastG = -1, lastB = -1, lastA = -1;
+        for (let i = 0; i < scanLength; i++) {
+            const pixelIndex = horizontal ? (line * width + i) * 4 : (i * width + line) * 4;
+            const r = data[pixelIndex];
+            const g = data[pixelIndex + 1];
+            const b = data[pixelIndex + 2];
+            const a = data[pixelIndex + 3];
+            // Check if color is similar to previous pixel
+            let similar = false;
+            if (lastR >= 0) {
+                const dist = Math.sqrt((r - lastR) ** 2 + (g - lastG) ** 2 + (b - lastB) ** 2);
+                const alphaDiff = Math.abs(a - lastA);
+                similar = dist <= COLOR_THRESHOLD && alphaDiff <= 40;
+            }
+            if (i === 0 || similar) {
+                runLength++;
+            }
+            else {
+                if (runLength > 0)
+                    runs.push(runLength);
+                runLength = 1;
+            }
+            lastR = r;
+            lastG = g;
+            lastB = b;
+            lastA = a;
+        }
+        if (runLength > 0)
+            runs.push(runLength);
+    }
+    return runs;
+}
+/**
+ * Score a period hypothesis using a comb-anticomb approach on run lengths.
+ * Comb peaks at k*step, anticomb at k*step ± 0.5*step.
+ * A true period will have strong alignment at multiples of the step.
+ */
+function runHistogram(runs) {
+    const tally = new Map();
+    let longest = 0;
+    for (const run of runs) {
+        tally.set(run, (tally.get(run) || 0) + 1);
+        longest = Math.max(longest, run);
+    }
+    return { lengths: [...tally.keys()], counts: [...tally.values()], total: runs.length, longest };
+}
+function scorePeriod(histogram, step) {
+    const { lengths, counts, total: totalRuns, longest: maxRun } = histogram;
+    if (totalRuns < 2 || step < MIN_STEP)
+        return -1;
+    const maxK = Math.min(MAX_COMB_ORDER, Math.floor(maxRun / step));
+    if (maxK < 2)
+        return -1;
+    let combScore = 0;
+    let antiCombScore = 0;
+    let totalWeight = 0;
+    // Comb-anticomb scoring: measure alignment vs offset
+    for (let k = 1; k <= maxK; k++) {
+        const target = k * step;
+        const weight = Math.exp(-(k - 1) / DECAY_CONSTANT);
+        totalWeight += weight;
+        // Window for "near" the target
+        const window = Math.max(0.5, step * 0.12);
+        // Comb: count runs near k*step
+        let combCount = 0;
+        // Anticomb: count runs near k*step ± 0.5*step
+        let antiCombCount = 0;
+        const offsetLeft = target - 0.5 * step;
+        const offsetRight = target + 0.5 * step;
+        for (let h = 0; h < lengths.length; h++) {
+            const runLength = lengths[h], count = counts[h];
+            const distTarget = Math.abs(runLength - target);
+            const distLeft = Math.abs(runLength - offsetLeft);
+            const distRight = Math.abs(runLength - offsetRight);
+            if (distTarget <= window) {
+                combCount += count;
+            }
+            if (distLeft <= window || distRight <= window) {
+                antiCombCount += count;
+            }
+        }
+        combScore += weight * combCount;
+        antiCombScore += weight * antiCombCount;
+    }
+    // Normalize by total weight and runs
+    if (totalWeight === 0 || totalRuns === 0)
+        return -1;
+    const normalizedComb = combScore / (totalWeight * totalRuns);
+    const normalizedAntiComb = antiCombScore / (totalWeight * totalRuns);
+    // Return comb - anticomb difference
+    return normalizedComb - normalizedAntiComb;
+}
+/**
+ * Search for the best period (step size) on one axis by scoring many candidates
+ * and returning the top scorers.
+ */
+function searchAxisPeriod(runs, maxStep) {
+    const candidates = [];
+    const histogram = runHistogram(runs);
+    for (let step = MIN_STEP; step <= maxStep; step += STEP_INCREMENT) {
+        const score = scorePeriod(histogram, step);
+        if (score > 0) {
+            candidates.push({ step, score });
+        }
+    }
+    // Sort by score descending and take top candidates
+    candidates.sort((a, b) => b.score - a.score);
+    return candidates.slice(0, MAX_CANDIDATES_PER_AXIS);
+}
+/**
+ * Detect a grid using boundary run-length comb period search. Returns multiple
+ * candidates (one per top-scoring period combination) for the arbiter to evaluate.
+ */
+export function detectBoundaryPeriodGrids(image) {
+    const { width, height } = image;
+    const minStep = Math.max(MIN_STEP, Math.max(width, height) / MAX_RECOVERED_GRID_SIZE);
+    const maxStepX = Math.min(MAX_STEP_SEARCH, Math.min(MAX_GRID_CELL_SIZE, width / MIN_CELLS));
+    const maxStepY = Math.min(MAX_STEP_SEARCH, Math.min(MAX_GRID_CELL_SIZE, height / MIN_CELLS));
+    if (maxStepX < minStep || maxStepY < minStep)
+        return [];
+    // Extract color runs across sampled lines
+    const xRuns = extractColorRuns(image, true);
+    const yRuns = extractColorRuns(image, false);
+    if (xRuns.length < 2 || yRuns.length < 2)
+        return [];
+    // Search for periods on each axis
+    const xCandidates = searchAxisPeriod(xRuns, maxStepX);
+    const yCandidates = searchAxisPeriod(yRuns, maxStepY);
+    if (xCandidates.length === 0 || yCandidates.length === 0)
+        return [];
+    // Generate grid proposals from period combinations.
+    // For each axis step, emit covering lattices at floor/round/ceil cell counts so a step
+    // that lands between two integers (e.g. 826/2.35 ≈ 351.5) still proposes the true count.
+    const grids = [];
+    const seen = new Set();
+    /**
+     * Covering cell counts for a period: always the nearest integer, plus the other side when
+     * length/step is near halfway (so 826/2.35 ≈ 351.5 still proposes 352). Far-from-half
+     * fractions (545/2.35 ≈ 231.91) keep only the rounded count — emitting the farther floor
+     * let a lower-residual wrong height win on painterly inputs.
+     */
+    const countNeighbors = (length, step) => {
+        const exact = length / step;
+        if (!Number.isFinite(exact) || exact <= 0)
+            return [];
+        const rounded = Math.round(exact);
+        const neighbors = [rounded];
+        const frac = exact - Math.floor(exact);
+        if (frac > 0.35 && frac < 0.65) {
+            const other = frac >= 0.5 ? Math.floor(exact) : Math.ceil(exact);
+            if (other > 0 && other !== rounded)
+                neighbors.push(other);
+        }
+        return neighbors;
+    };
+    for (const xCand of xCandidates.slice(0, 3)) {
+        for (const yCand of yCandidates.slice(0, 3)) {
+            const confidence = Math.min(xCand.score, yCand.score);
+            for (const cols of countNeighbors(width, xCand.step)) {
+                for (const rows of countNeighbors(height, yCand.step)) {
+                    if (cols < MIN_CELLS ||
+                        rows < MIN_CELLS ||
+                        cols * rows < MIN_GRID_CELLS ||
+                        cols > MAX_RECOVERED_GRID_SIZE ||
+                        rows > MAX_RECOVERED_GRID_SIZE) {
+                        continue;
+                    }
+                    const key = `${cols}x${rows}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    // Image-covering lattice for the cell counts (not the raw float step).
+                    const coverWidth = width / cols;
+                    const coverHeight = height / rows;
+                    const cutsX = pixelGridCuts(width, coverWidth, 0);
+                    const cutsY = pixelGridCuts(height, coverHeight, 0);
+                    grids.push({
+                        width: cols,
+                        height: rows,
+                        cellWidth: coverWidth,
+                        cellHeight: coverHeight,
+                        offsetX: 0,
+                        offsetY: 0,
+                        cutsX,
+                        cutsY,
+                        confidence,
+                        reliable: true,
+                        algorithm: PixelationAlgorithm.UniformGrid,
+                    });
+                }
+            }
+        }
+    }
+    return grids;
+}
+/**
+ * Returns the top-scored boundary period grid, or unreliable when none found.
+ * This is the single-hypothesis interface for registry entries; the multi-hypothesis
+ * version above feeds the arbiter's candidate pool.
+ */
+export function detectBoundaryPeriodGrid(image) {
+    const grids = detectBoundaryPeriodGrids(image);
+    if (grids.length === 0) {
+        return {
+            width: 1,
+            height: 1,
+            cellWidth: image.width,
+            cellHeight: image.height,
+            offsetX: 0,
+            offsetY: 0,
+            confidence: 0,
+            reliable: false,
+        };
+    }
+    return grids[0];
+}

package/dist/grid-period-comb.d.ts

@@ -0,0 +1,4 @@
+import type { PixelBuffer } from "./base.ts";
+import { type PixelGridAnalysis } from "./types.ts";
+/** Lattices covering the image at the cell counts of the strongest steps of either axis. */
+export declare function combCountGrids(image: PixelBuffer): PixelGridAnalysis[];

package/dist/grid-period-comb.js

@@ -0,0 +1,230 @@
+import { blockPartition, MAX_RECOVERED_GRID_SIZE } from "./grid.js";
+import { PixelationAlgorithm } from "./types.js";
+/**
+ * Cell counts read from the period of the colour steps, for upscales whose cells keep a steady
+ * count but not a steady phase (warped, re-blocked or locally shifted grids), where no single
+ * lattice lines up with the whole image.
+ *
+ * Each axis is read through the first and second differences of the colour, summed over short
+ * bands of lines and over all lines. Every band's autocorrelation is normalised on its own, so a
+ * band whose cuts are shifted against another's still peaks at the same lag; their mean is
+ * phase-free. A step scores the autocorrelation on its multiples against the midpoints between
+ * them (a comb), less half the best score of its own fractions, so the fundamental of a harmonic
+ * train outranks its multiples. The strongest steps propose lattices that cover the whole image at
+ * the counts the steps round to.
+ */
+const CHANNELS = 3;
+const STRIDE = 4;
+const ALPHA_SCALE = 255;
+const ALPHA_CHANNEL = 3;
+/** Lines summed into one band of the profile. */
+const BAND_LINES = 16;
+/** Bands read per axis; taller images read evenly spread bands. */
+const MAX_BANDS = 64;
+const MIN_STEP = 2.5;
+const MAX_STEP = 64;
+/** The longest step is this fraction of the axis, so its comb holds several teeth. */
+const MIN_PERIODS = 4;
+/** Relative spacing of the steps the comb scores. */
+const STEP_RATIO = 1.0025;
+const COMB_TEETH = 24;
+/** Lags the autocorrelation covers, in multiples of the longest step. */
+const LAG_PERIODS = 12;
+/** Teeth weigh exp(-(k - 1) / COMB_DECAY), so the near multiples count most. */
+const COMB_DECAY = 12;
+const HALF = 0.5;
+const SUBHARMONICS = [2, 3, 4, 5];
+const SUBHARMONIC_PENALTY = 0.5;
+/** Steps kept per axis. */
+const STEPS_PER_AXIS = 3;
+/** Half-width of the window a refined tooth is looked for in, as a share of the step. */
+const TOOTH_WINDOW = 0.3;
+const MIN_TOOTH_WINDOW = 2;
+const MIN_TOOTH_TOLERANCE = 1.5;
+const REFINE_PASSES = 3;
+/** A refined step stays within this ratio of the step the comb found. */
+const REFINE_LIMIT = 1.25;
+const MIN_GRID_CELLS = 2;
+var Difference;
+(function (Difference) {
+    Difference[Difference["First"] = 1] = "First";
+    Difference[Difference["Second"] = 2] = "Second";
+})(Difference || (Difference = {}));
+/** Absolute colour difference of the given order at every pixel along each line of an axis. */
+function differences(image, horizontal, order) {
+    const { width, height, data } = image;
+    const length = horizontal ? width : height;
+    const lines = horizontal ? height : width;
+    const out = new Float64Array(lines * length);
+    const value = (along, line, c) => {
+        const o = (horizontal ? line * width + along : along * width + line) * STRIDE;
+        return (data[o + c] * data[o + ALPHA_CHANNEL]) / ALPHA_SCALE;
+    };
+    const end = order === Difference.Second ? length - 1 : length;
+    for (let line = 0; line < lines; line++)
+        for (let i = 1; i < end; i++) {
+            let energy = 0;
+            for (let c = 0; c < CHANNELS; c++) {
+                const here = value(i, line, c), before = value(i - 1, line, c);
+                energy += Math.abs(order === Difference.Second ? value(i + 1, line, c) - 2 * here + before : here - before);
+            }
+            out[line * length + i] = energy;
+        }
+    return { lines, length, data: out };
+}
+/** Mean over bands of `band` lines of each band's unbiased autocorrelation, normalised at lag 0. */
+function bandAutocorrelation(feature, band, maxLag) {
+    const { lines, length, data } = feature;
+    const size = Math.min(band, lines);
+    const bands = Math.max(1, Math.floor(lines / size));
+    const read = Math.min(bands, MAX_BANDS);
+    const sum = new Float64Array(maxLag + 1);
+    const profile = new Float64Array(length);
+    let used = 0;
+    for (let k = 0; k < read; k++) {
+        const first = Math.floor((k * bands) / read) * size;
+        profile.fill(0);
+        for (let line = first; line < first + size; line++)
+            for (let i = 0; i < length; i++)
+                profile[i] += data[line * length + i];
+        let mean = 0;
+        for (let i = 0; i < length; i++)
+            mean += profile[i];
+        mean /= length;
+        let energy = 0;
+        for (let i = 0; i < length; i++) {
+            profile[i] -= mean;
+            energy += profile[i] * profile[i];
+        }
+        if (!energy)
+            continue;
+        used++;
+        for (let lag = 0; lag <= maxLag; lag++) {
+            let s = 0;
+            for (let i = 0; i + lag < length; i++)
+                s += profile[i] * profile[i + lag];
+            sum[lag] += (s / energy) * (length / (length - lag));
+        }
+    }
+    if (used)
+        for (let lag = 0; lag <= maxLag; lag++)
+            sum[lag] /= used;
+    return sum;
+}
+function at(values, position) {
+    const i = Math.max(0, Math.min(values.length - 2, Math.floor(position)));
+    const t = position - i;
+    return values[i] * (1 - t) + values[i + 1] * t;
+}
+/** Weighted mean of the autocorrelation on the multiples of `step` less that between them. */
+function comb(correlation, step) {
+    const teeth = Math.min(Math.floor((correlation.length - 2) / step), COMB_TEETH);
+    if (teeth < 2)
+        return -Infinity;
+    let sum = 0, weights = 0;
+    for (let k = 1; k <= teeth; k++) {
+        const weight = Math.exp(-(k - 1) / COMB_DECAY);
+        const between = HALF * (at(correlation, (k - HALF) * step) + at(correlation, (k + HALF) * step));
+        sum += weight * (at(correlation, k * step) - between);
+        weights += weight;
+    }
+    return sum / weights;
+}
+/** The step of the line through the peaks of the autocorrelation near each multiple of `step`. */
+function refine(correlation, step) {
+    const n = correlation.length;
+    const teeth = Math.min(Math.floor((n - 3) / step), COMB_TEETH);
+    const peaks = [];
+    const window = Math.max(MIN_TOOTH_WINDOW, Math.floor(TOOTH_WINDOW * step));
+    for (let k = 1; k <= teeth; k++) {
+        const low = Math.max(1, Math.floor(k * step - window)), high = Math.min(n - 2, Math.ceil(k * step + window));
+        let i = low;
+        for (let j = low; j <= high; j++)
+            if (correlation[j] > correlation[i])
+                i = j;
+        if (i <= low || i >= high)
+            continue;
+        const curvature = correlation[i - 1] - 2 * correlation[i] + correlation[i + 1];
+        const shift = curvature ? (correlation[i - 1] - correlation[i + 1]) / (2 * curvature) : 0;
+        peaks.push({
+            position: i + Math.max(-1, Math.min(1, shift)),
+            order: k,
+            weight: Math.max(Number.EPSILON, correlation[i]),
+        });
+    }
+    let refined = step;
+    const tolerance = Math.max(MIN_TOOTH_TOLERANCE, TOOTH_WINDOW * step);
+    for (let pass = 0; pass < REFINE_PASSES; pass++) {
+        let numerator = 0, denominator = 0, kept = 0;
+        for (const { position, order, weight } of peaks)
+            if (Math.abs(position - order * refined) <= tolerance) {
+                numerator += weight * position * order;
+                denominator += weight * order * order;
+                kept++;
+            }
+        if (kept < 2)
+            break;
+        refined = numerator / denominator;
+    }
+    return refined >= step / REFINE_LIMIT && refined <= step * REFINE_LIMIT ? refined : step;
+}
+/** The strongest cell steps along one axis, strongest first. */
+function combSteps(image, horizontal) {
+    const length = horizontal ? image.width : image.height;
+    const longest = Math.min(MAX_STEP, length / MIN_PERIODS);
+    if (longest <= MIN_STEP)
+        return [];
+    const maxLag = Math.min(length - 2, Math.ceil(longest * LAG_PERIODS));
+    const correlation = new Float64Array(maxLag + 1);
+    const readings = [];
+    for (const order of [Difference.First, Difference.Second]) {
+        const feature = differences(image, horizontal, order);
+        for (const band of [BAND_LINES, feature.lines])
+            readings.push(bandAutocorrelation(feature, band, maxLag));
+    }
+    for (const reading of readings)
+        for (let lag = 0; lag <= maxLag; lag++)
+            correlation[lag] += reading[lag] / readings.length;
+    const steps = [];
+    for (let step = MIN_STEP; step <= longest; step *= STEP_RATIO)
+        steps.push(step);
+    const raw = steps.map((step) => comb(correlation, step));
+    const rawAt = (step) => {
+        const index = Math.round(Math.log(step / MIN_STEP) / Math.log(STEP_RATIO));
+        return index < 0 ? -Infinity : raw[Math.min(raw.length - 1, index)];
+    };
+    const selective = steps.map((step, i) => {
+        let fraction = 0;
+        for (const m of SUBHARMONICS)
+            if (step / m >= MIN_STEP)
+                fraction = Math.max(fraction, rawAt(step / m));
+        return raw[i] - SUBHARMONIC_PENALTY * fraction;
+    });
+    const peaks = [];
+    for (let i = 1; i + 1 < steps.length; i++)
+        if (selective[i] > selective[i - 1] && selective[i] >= selective[i + 1])
+            peaks.push(i);
+    peaks.sort((a, b) => selective[b] - selective[a]);
+    return peaks.slice(0, STEPS_PER_AXIS).map((i) => refine(correlation, steps[i]));
+}
+/** Lattices covering the image at the cell counts of the strongest steps of either axis. */
+export function combCountGrids(image) {
+    const steps = [...combSteps(image, true), ...combSteps(image, false)];
+    const grids = [];
+    const seen = new Set();
+    const limit = (count, length) => count >= MIN_GRID_CELLS && count <= Math.min(length, MAX_RECOVERED_GRID_SIZE);
+    for (const step of steps) {
+        const columns = Math.round(image.width / step), rows = Math.round(image.height / step);
+        const key = `${columns}x${rows}`;
+        if (seen.has(key) || !limit(columns, image.width) || !limit(rows, image.height))
+            continue;
+        seen.add(key);
+        grids.push({
+            ...blockPartition(image, columns, rows),
+            confidence: 0,
+            reliable: true,
+            algorithm: PixelationAlgorithm.UniformGrid,
+        });
+    }
+    return grids;
+}

package/dist/grid-period-distance.d.ts

@@ -0,0 +1,7 @@
+import type { PixelBuffer } from "./base.ts";
+import { type PixelGridAnalysis } from "./types.ts";
+/**
+ * The lattice covering the image at the cell counts of the axes' standing steps; an axis without
+ * one takes the other's.
+ */
+export declare function distanceCountGrids(image: PixelBuffer): PixelGridAnalysis[];