@xprite/pixelate 0.0.0-stage → 0.1.0

package/dist/grid-edge-coherence.js

@@ -0,0 +1,158 @@
+import { pixelGridCuts } from "./grid.js";
+/**
+ * Edge coherence of a grid: how much of the image's colour steps fall on its cuts. Each step
+ * between two neighbouring pixels counts with the cosine of its phase inside its cell, so a step on
+ * a cut counts fully, a step at a cell middle counts against the grid, and steps spread evenly over
+ * a cell of two or more whole pixels add up to nothing. The score of a grid is the smaller of its
+ * two axes' shares.
+ *
+ * A soft or noisy upscale describes slightly better through a lattice at a half or third of its
+ * pitch: the finer cells follow the blur and noise inside each source pixel. Such a lattice puts
+ * most of its cuts inside source pixels, where the image has no edges. Auto does not read a grid
+ * the edges reject in either of two ways, which also spares it the cost of reading the grid:
+ *
+ * - Rigid: the steps summed over the whole image, against the grid's own phase. A grid is rejected
+ *   when a proposal of at least COARSER_PITCH times its pitch on both axes reaches MIN_COHERENCE and
+ *   the grid keeps less than COHERENCE_SHARE of it. Only a coarser proposal can reject a grid this
+ *   way: a warped, drifting or re-blocked grid scores low on one rigid lattice, and its true count
+ *   must still compete with the lattices near it.
+ * - Local: the steps summed over BANDS strips, scored in runs of RUN_CELLS cells at whatever phase
+ *   the run takes, so a grid whose phase drifts across the image keeps its coherence. When some
+ *   grid is crisp in the rigid sense (MIN_COHERENCE) and the best local coherence reaches
+ *   MIN_LOCAL_COHERENCE, a grid that keeps less than COHERENCE_SHARE of it is rejected.
+ *   Of the grids left, only the MAX_COHERENT_GRIDS of highest local coherence are read: the rest
+ *   are near-duplicate counts that cost a reading each and do not win.
+ *
+ * Only grids of at least MIN_REJECTING_CELLS cells per axis reject others: on a small sprite, a
+ * lattice of a few large cells lines up with its outline by chance.
+ *
+ * A bilinear or blurred upscale spreads every edge over its cells; no grid reaches the minimums,
+ * and every proposal is read.
+ */
+const STRIDE = 4;
+const CHANNELS = 4;
+const ALPHA_CHANNEL = 3;
+const ALPHA_SCALE = 255;
+/** Share of the coherence that rejects a grid a grid must keep to be read. */
+const COHERENCE_SHARE = 0.6;
+/** Rigid coherence a grid needs to reject others. */
+const MIN_COHERENCE = 0.2;
+/** Local coherence the best grid needs before local coherence rejects others. */
+const MIN_LOCAL_COHERENCE = 0.3;
+/** Cells per axis a grid needs to reject others. */
+const MIN_REJECTING_CELLS = 12;
+/** Pitch ratio, per axis, from which a proposal counts as coarser. */
+const COARSER_PITCH = 1.5;
+/** Grids read at most when local coherence selects them. */
+const MAX_COHERENT_GRIDS = 10;
+/** Strips across each axis the local steps are summed over. */
+const BANDS = 8;
+/** Cells along a strip that share one phase in the local score. */
+const RUN_CELLS = 16;
+/**
+ * Pixels per cell, per axis, a grid needs for the check: cells of one pixel put every step on a
+ * cut. Finer grids are always read and reject none.
+ */
+const MIN_COHERENCE_PITCH = 2;
+/** Colour step (premultiplied RGB and alpha) into each column and row, per strip. */
+function stepProfiles(image) {
+    const { width, height, data } = image;
+    const x = Array.from({ length: BANDS }, () => new Float64Array(width)), y = Array.from({ length: BANDS }, () => new Float64Array(height));
+    const columnBand = Int32Array.from({ length: width }, (_, column) => Math.floor((column * BANDS) / width));
+    // One row of premultiplied colours at a time, with the row above it.
+    let above = new Float64Array(width * CHANNELS), current = new Float64Array(width * CHANNELS);
+    for (let row = 0; row < height; row++) {
+        const across = x[Math.floor((row * BANDS) / height)];
+        for (let column = 0, o = row * width * STRIDE; column < width; column++, o += STRIDE) {
+            const alpha = data[o + ALPHA_CHANNEL] / ALPHA_SCALE, at = column * CHANNELS;
+            current[at] = data[o] * alpha;
+            current[at + 1] = data[o + 1] * alpha;
+            current[at + 2] = data[o + 2] * alpha;
+            current[at + ALPHA_CHANNEL] = data[o + ALPHA_CHANNEL];
+        }
+        for (let column = 0, at = 0; column < width; column++, at += CHANNELS) {
+            let right = 0, down = 0;
+            for (let c = 0; c < CHANNELS; c++) {
+                if (column)
+                    right += Math.abs(current[at + c] - current[at - CHANNELS + c]);
+                if (row)
+                    down += Math.abs(current[at + c] - above[at + c]);
+            }
+            across[column] += right;
+            y[columnBand[column]][row] += down;
+        }
+        [above, current] = [current, above];
+    }
+    return { x, y };
+}
+/**
+ * Share of one axis's steps on the cuts, weighted by the cosine of their phase in the cell. With
+ * `run`, the steps of every `run` cells of each strip add up as phasors and only their length
+ * counts, so each run is scored at its own phase.
+ */
+function axisCoherence(strips, cuts, run) {
+    let aligned = 0, total = 0;
+    const cells = cuts.length - 1;
+    const length = run ?? cells;
+    for (const profile of strips)
+        for (let first = 0; first < cells; first += length) {
+            let real = 0, imaginary = 0;
+            for (let cell = first; cell < Math.min(cells, first + length); cell++) {
+                const from = Math.max(0, Math.ceil(cuts[cell])), to = Math.min(profile.length, Math.ceil(cuts[cell + 1]));
+                const size = cuts[cell + 1] - cuts[cell];
+                for (let p = from; p < to; p++) {
+                    const angle = (2 * Math.PI * (p - cuts[cell])) / size;
+                    real += profile[p] * Math.cos(angle);
+                    if (run)
+                        imaginary += profile[p] * Math.sin(angle);
+                    total += profile[p];
+                }
+            }
+            aligned += run ? Math.hypot(real, imaginary) : real;
+        }
+    return total ? aligned / total : 0;
+}
+const sum = (strips) => {
+    const total = new Float64Array(strips[0].length);
+    for (const strip of strips)
+        for (let p = 0; p < strip.length; p++)
+            total[p] += strip[p];
+    return [total];
+};
+/** The proposals Auto reads, per proposer: those the image's edges do not reject (see above). */
+export function coherentGrids(image, proposals) {
+    if (!proposals.some((grids) => grids.length))
+        return proposals.map((grids) => [...grids]);
+    const bands = stepProfiles(image);
+    const whole = { x: sum(bands.x), y: sum(bands.y) };
+    const scored = proposals.map((grids) => grids.map((grid) => {
+        const cutsX = grid.cutsX ?? pixelGridCuts(image.width, grid.cellWidth, grid.offsetX), cutsY = grid.cutsY ?? pixelGridCuts(image.height, grid.cellHeight, grid.offsetY);
+        const pitchX = image.width / (cutsX.length - 1), pitchY = image.height / (cutsY.length - 1);
+        const checked = pitchX >= MIN_COHERENCE_PITCH && pitchY >= MIN_COHERENCE_PITCH;
+        return {
+            grid,
+            pitchX,
+            pitchY,
+            checked,
+            coherence: checked
+                ? Math.min(axisCoherence(whole.x, cutsX), axisCoherence(whole.y, cutsY))
+                : 0,
+            local: checked
+                ? Math.min(axisCoherence(bands.x, cutsX, RUN_CELLS), axisCoherence(bands.y, cutsY, RUN_CELLS))
+                : 0,
+        };
+    }));
+    const all = scored.flat();
+    const large = all.filter(({ grid }) => Math.min(grid.width, grid.height) >= MIN_REJECTING_CELLS);
+    const rejecters = large.filter(({ coherence }) => coherence >= MIN_COHERENCE);
+    const bestLocal = rejecters.length ? Math.max(...large.map(({ local }) => local)) : 0;
+    const localFloor = bestLocal >= MIN_LOCAL_COHERENCE ? COHERENCE_SHARE * bestLocal : -Infinity;
+    const supported = (grid) => grid.local >= localFloor &&
+        !rejecters.some((rejecter) => rejecter.pitchX >= COARSER_PITCH * grid.pitchX &&
+            rejecter.pitchY >= COARSER_PITCH * grid.pitchY &&
+            grid.coherence < COHERENCE_SHARE * rejecter.coherence);
+    let read = new Set(all.filter((grid) => grid.checked && supported(grid)));
+    if (localFloor > -Infinity && read.size > MAX_COHERENT_GRIDS)
+        read = new Set([...read].sort((a, b) => b.local - a.local).slice(0, MAX_COHERENT_GRIDS));
+    return scored.map((grids) => grids.filter((grid) => !grid.checked || read.has(grid)).map(({ grid }) => grid));
+}

package/dist/grid-edge-path.d.ts

@@ -0,0 +1,9 @@
+import type { PixelBuffer } from "./base.ts";
+import { type PixelGridAnalysis } from "./types.ts";
+/** The cuts of one axis along its step profile at `pitch`; null when the axis has no content. */
+export declare function edgePath(profile: Float64Array, pitch: number): number[] | null;
+/**
+ * Edge-path meshes at the pitches of the given proposals, strongest proposals first, one per pitch
+ * pair (see above).
+ */
+export declare function edgePathGrids(image: PixelBuffer, proposals: readonly PixelGridAnalysis[]): PixelGridAnalysis[];

package/dist/grid-edge-path.js

@@ -0,0 +1,201 @@
+import { pixelGridCuts } from "./grid.js";
+import { PixelationAlgorithm } from "./types.js";
+/**
+ * Edge paths: a mesh whose cuts follow the colour edges at a pitch another proposer found.
+ *
+ * A generator does not draw its cells at one width. Along an axis the cells of a generated sprite
+ * are 0.8 to 1.2 times the pitch, and the width wanders across the image, so every lattice falls
+ * out of step with the art somewhere and cuts through its pixels. The edge mesh (grid-detect) only
+ * keeps cuts on sharp, consistent edges, which a soft generated image rarely has everywhere.
+ *
+ * Per axis, the colour steps into each column (or row) are summed over the image, and the cuts are
+ * the path through them, from the first strong step to the last, that gathers the most step energy
+ * (EDGE_GAIN per cut, relative to the mean step) at cell widths between MIN_WIDTH and MAX_WIDTH of
+ * the pitch. A width away from the pitch costs PITCH_WEIGHT, a change of width from one cell to
+ * the next SMOOTH_WEIGHT, both on the square of the change as a share of the pitch, so across a
+ * stretch of one colour the path keeps the pitch and at an edge it moves onto it. Outside the
+ * content the cuts continue at the pitch. Arbitration reads the paths as free meshes: each cut pays
+ * for itself, so a path wins only where the art does not keep one pitch. A path already sits on
+ * the edges, so it is read as placed, without strip shifts or a phase field.
+ */
+const STRIDE = 4;
+const CHANNELS = 4;
+const ALPHA_CHANNEL = 3;
+const ALPHA_SCALE = 255;
+const MIN_WIDTH = 0.75;
+const MAX_WIDTH = 1.25;
+const PITCH_WEIGHT = 10;
+const SMOOTH_WEIGHT = 8;
+/** Share of the strongest step a step needs to start or end the content. */
+const CONTENT_STEP = 0.05;
+/** A border cell narrower than this share of the pitch joins its neighbour. */
+const SLIVER = 0.5;
+/** Pitches of at least this many pixels are followed; finer ones have no room to move. */
+const MIN_PITCH = 4;
+/** Cells per axis a path needs. */
+const MIN_CELLS = 8;
+/** Pitch pairs within this many pixels on both axes share one path. */
+const PITCH_TOLERANCE = 0.5;
+/** Paths proposed at most: each costs a reading. */
+const MAX_PATHS = 3;
+/** Colour step into every column and row, summed over the image (premultiplied RGB and alpha). */
+function stepProfiles(image) {
+    const { width, height, data } = image;
+    const x = new Float64Array(width), y = new Float64Array(height);
+    let above = new Float64Array(width * CHANNELS), current = new Float64Array(width * CHANNELS);
+    for (let row = 0; row < height; row++) {
+        for (let column = 0, o = row * width * STRIDE; column < width; column++, o += STRIDE) {
+            const alpha = data[o + ALPHA_CHANNEL] / ALPHA_SCALE, at = column * CHANNELS;
+            current[at] = data[o] * alpha;
+            current[at + 1] = data[o + 1] * alpha;
+            current[at + 2] = data[o + 2] * alpha;
+            current[at + ALPHA_CHANNEL] = data[o + ALPHA_CHANNEL];
+        }
+        for (let column = 0, at = 0; column < width; column++, at += CHANNELS) {
+            let right = 0, down = 0;
+            for (let c = 0; c < CHANNELS; c++) {
+                if (column)
+                    right += Math.abs(current[at + c] - current[at - CHANNELS + c]);
+                if (row)
+                    down += Math.abs(current[at + c] - above[at + c]);
+            }
+            x[column] += right;
+            y[row] += down;
+        }
+        [above, current] = [current, above];
+    }
+    return { x, y };
+}
+/** The cuts of one axis along its step profile at `pitch`; null when the axis has no content. */
+export function edgePath(profile, pitch) {
+    const length = profile.length;
+    let peak = 0;
+    for (let p = 1; p < length; p++)
+        peak = Math.max(peak, profile[p]);
+    if (!peak)
+        return null;
+    let first = -1, last = -1;
+    for (let p = 1; p < length; p++)
+        if (profile[p] >= CONTENT_STEP * peak) {
+            if (first < 0)
+                first = p;
+            last = p;
+        }
+    const narrow = Math.max(2, Math.round(MIN_WIDTH * pitch)), wide = Math.max(narrow, Math.round(MAX_WIDTH * pitch));
+    if (first < 0 || last - first < narrow)
+        return null;
+    let mean = 0;
+    for (let p = first; p <= last; p++)
+        mean += profile[p];
+    mean /= last - first + 1;
+    const gain = (p) => (p < length ? profile[p] / mean - 1 : -1);
+    const widths = wide - narrow + 1;
+    const span = last - first;
+    // score[q][w]: best path from `first` to a cut at first + q whose last cell is narrow + w wide.
+    const score = new Float64Array((span + wide + 1) * widths).fill(-Infinity);
+    const from = new Int32Array((span + wide + 1) * widths).fill(-1);
+    const cost = (w) => PITCH_WEIGHT * ((narrow + w - pitch) / pitch) ** 2;
+    for (let w = 0; w < widths; w++) {
+        const q = narrow + w;
+        if (q <= span + wide)
+            score[q * widths + w] = gain(first) + gain(first + q) - cost(w);
+    }
+    for (let q = narrow; q <= span; q++)
+        for (let w = 0; w < widths; w++) {
+            const here = score[q * widths + w];
+            if (here === -Infinity)
+                continue;
+            for (let next = 0; next < widths; next++) {
+                const to = q + narrow + next;
+                if (to > span + wide)
+                    break;
+                const change = (next - w) / pitch;
+                const value = here + gain(first + to) - cost(next) - SMOOTH_WEIGHT * change * change;
+                if (value > score[to * widths + next]) {
+                    score[to * widths + next] = value;
+                    from[to * widths + next] = q * widths + w;
+                }
+            }
+        }
+    let end = -1, best = -Infinity;
+    // The path ends on the last content step, or within one narrow cell past it.
+    for (let q = span; q <= Math.min(span + narrow, span + wide); q++)
+        for (let w = 0; w < widths; w++)
+            if (score[q * widths + w] > best) {
+                best = score[q * widths + w];
+                end = q * widths + w;
+            }
+    if (end < 0)
+        return null;
+    const inner = [];
+    for (let at = end; at >= 0; at = from[at]) {
+        const q = Math.floor(at / widths);
+        inner.push(first + q);
+        if (from[at] < 0)
+            inner.push(first);
+    }
+    inner.reverse();
+    // Continue at the pitch to both ends of the axis.
+    const cuts = inner.filter((c) => c > 0 && c < length);
+    while (cuts[0] - pitch > 0)
+        cuts.unshift(cuts[0] - pitch);
+    while (cuts[cuts.length - 1] + pitch < length)
+        cuts.push(cuts[cuts.length - 1] + pitch);
+    if (cuts[0] < SLIVER * pitch)
+        cuts.shift();
+    if (length - cuts[cuts.length - 1] < SLIVER * pitch)
+        cuts.pop();
+    return [0, ...cuts.map((c) => Math.round(c * 100) / 100), length];
+}
+const pitchOf = (cuts) => (cuts[cuts.length - 1] - cuts[0]) / (cuts.length - 1);
+/**
+ * Edge-path meshes at the pitches of the given proposals, strongest proposals first, one per pitch
+ * pair (see above).
+ */
+export function edgePathGrids(image, proposals) {
+    const pitches = [];
+    for (const grid of [...proposals].sort((a, b) => b.confidence - a.confidence)) {
+        if (!grid.reliable)
+            continue;
+        const x = pitchOf(grid.cutsX ?? pixelGridCuts(image.width, grid.cellWidth, grid.offsetX)), y = pitchOf(grid.cutsY ?? pixelGridCuts(image.height, grid.cellHeight, grid.offsetY));
+        if (Math.min(x, y) < MIN_PITCH)
+            continue;
+        if (pitches.some((p) => Math.abs(p.x - x) <= PITCH_TOLERANCE && Math.abs(p.y - y) <= PITCH_TOLERANCE))
+            continue;
+        pitches.push({ x, y, confidence: grid.confidence });
+        if (pitches.length === MAX_PATHS)
+            break;
+    }
+    if (!pitches.length)
+        return [];
+    const profiles = stepProfiles(image);
+    const grids = [];
+    const seen = new Set();
+    for (const { x, y, confidence } of pitches) {
+        const cutsX = edgePath(profiles.x, x), cutsY = edgePath(profiles.y, y);
+        if (!cutsX || !cutsY)
+            continue;
+        const columns = cutsX.length - 1, rows = cutsY.length - 1;
+        if (Math.min(columns, rows) < MIN_CELLS)
+            continue;
+        const key = `${cutsX.join(",")}|${cutsY.join(",")}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        grids.push({
+            width: columns,
+            height: rows,
+            cellWidth: image.width / columns,
+            cellHeight: image.height / rows,
+            offsetX: 0,
+            offsetY: 0,
+            cutsX,
+            cutsY,
+            confidence,
+            reliable: true,
+            algorithm: PixelationAlgorithm.EdgeGrid,
+            placed: true,
+        });
+    }
+    return grids;
+}

package/dist/grid-frame-lattice.d.ts

@@ -0,0 +1,25 @@
+import type { PixelBuffer } from "./base.ts";
+import { type PixelGridAnalysis } from "./types.ts";
+/** How the native cells were resampled onto the frame. */
+export declare enum FrameModel {
+    /** Bilinear-like: the profile kinks at each cell's sample point. */
+    Soft = "soft",
+    /** Nearest-like: colour steps on each cell boundary. */
+    Hard = "hard"
+}
+interface AxisComb {
+    first: number;
+    significance: Float64Array;
+}
+/**
+ * Projection of the profile onto the comb of every count from `first` to `last`, in units of its
+ * standard deviation were the profile structureless: positive when the energy gathers on the
+ * sample points (soft) or on the cell boundaries (hard).
+ */
+export declare function combSignificance(profile: Float64Array, first: number, last: number, model: FrameModel): AxisComb;
+/**
+ * The frame-aligned lattice of each of `models` that passes the significance, reconstruction,
+ * alias and subdivision tests. Cells are square up to SQUARE_TOLERANCE.
+ */
+export declare function detectFrameLattices(image: PixelBuffer, models?: readonly FrameModel[]): PixelGridAnalysis[];
+export {};