@xprite/pixelate 0.0.0-stage → 0.1.0

package/dist/analyze.js

@@ -0,0 +1,217 @@
+import { UINT8_MAX } from "./base.js";
+import { assertPixelBuffer } from "./base.js";
+import { detectWithAlgorithm, detectWithAlgorithmAsync, } from "./pixelation-algorithm-registry.js";
+import { PixelArtClassification } from "./types.js";
+import { clamp } from "./base.js";
+const MAX_UNIQUE_SAMPLE_COLORS = 8_192;
+const DEFAULT_MAX_SAMPLE_PIXELS = 131_072;
+function classificationFor(score) {
+    if (score >= 0.24)
+        return PixelArtClassification.LikelyPixelArt;
+    if (score <= -0.24)
+        return PixelArtClassification.LikelyPhoto;
+    return PixelArtClassification.Uncertain;
+}
+function checkedMaxSamples(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_SAMPLE_PIXELS;
+    if (!Number.isSafeInteger(value) || value < 1)
+        throw new RangeError("maxSamplePixels must be a positive integer");
+    return value;
+}
+/**
+ * Estimate whether imported RGBA pixels resemble pixel art or a photograph.
+ * This is intentionally a suggestion: callers should expose the result and
+ * keep the user's override when the heuristic is wrong.
+ */
+function analyzePixelArtWithoutGrid(image, options = {}) {
+    assertPixelBuffer(image);
+    const maxSamples = checkedMaxSamples(options.maxSamplePixels);
+    const totalPixels = image.width * image.height;
+    const stride = Math.max(1, Math.ceil(Math.sqrt(totalPixels / maxSamples)));
+    const data = image.data;
+    const unique = new Set();
+    const histogram = new Uint32Array(32 * 32 * 32);
+    let sampledPixels = 0;
+    let transparentPixels = 0;
+    let opaquePixels = 0;
+    let entropyTotal = 0;
+    for (let y = 0; y < image.height; y += stride) {
+        for (let x = 0; x < image.width; x += stride) {
+            const offset = (y * image.width + x) * 4;
+            const r = data[offset];
+            const g = data[offset + 1];
+            const b = data[offset + 2];
+            const a = data[offset + 3];
+            sampledPixels += 1;
+            if (a === 0)
+                transparentPixels += 1;
+            if (a === UINT8_MAX)
+                opaquePixels += 1;
+            if (unique.size <= MAX_UNIQUE_SAMPLE_COLORS)
+                unique.add((r << 24) | (g << 16) | (b << 8) | a | 0);
+            histogram[(r >>> 3) | ((g >>> 3) << 5) | ((b >>> 3) << 10)] += 1;
+        }
+    }
+    let exactNeighbors = 0;
+    let nearNeighbors = 0;
+    let neighborComparisons = 0;
+    const isNear = (left, right) => {
+        const dr = Math.abs(data[left] - data[right]);
+        const dg = Math.abs(data[left + 1] - data[right + 1]);
+        const db = Math.abs(data[left + 2] - data[right + 2]);
+        const da = Math.abs(data[left + 3] - data[right + 3]);
+        return dr <= 12 && dg <= 12 && db <= 12 && da <= 24;
+    };
+    const isExact = (left, right) => data[left] === data[right] &&
+        data[left + 1] === data[right + 1] &&
+        data[left + 2] === data[right + 2] &&
+        data[left + 3] === data[right + 3];
+    for (let y = 0; y < image.height; y += stride) {
+        for (let x = 0; x < image.width; x += stride) {
+            const offset = (y * image.width + x) * 4;
+            if (x + stride < image.width) {
+                const right = (y * image.width + x + stride) * 4;
+                neighborComparisons += 1;
+                if (isExact(offset, right))
+                    exactNeighbors += 1;
+                if (isNear(offset, right))
+                    nearNeighbors += 1;
+            }
+            if (y + stride < image.height) {
+                const below = ((y + stride) * image.width + x) * 4;
+                neighborComparisons += 1;
+                if (isExact(offset, below))
+                    exactNeighbors += 1;
+                if (isNear(offset, below))
+                    nearNeighbors += 1;
+            }
+        }
+    }
+    for (let i = 0; i < histogram.length; i += 1) {
+        if (histogram[i] === 0)
+            continue;
+        const probability = histogram[i] / sampledPixels;
+        entropyTotal -= probability * Math.log2(probability);
+    }
+    const uniqueColorsCapped = unique.size > MAX_UNIQUE_SAMPLE_COLORS;
+    const uniqueColors = uniqueColorsCapped ? MAX_UNIQUE_SAMPLE_COLORS + 1 : unique.size;
+    const uniqueColorRatio = clamp(uniqueColors / sampledPixels, 0, 1);
+    const exactNeighborRatio = neighborComparisons === 0 ? 1 : exactNeighbors / neighborComparisons;
+    const nearNeighborRatio = neighborComparisons === 0 ? 1 : nearNeighbors / neighborComparisons;
+    const edgeDensity = 1 - nearNeighborRatio;
+    const transparentRatio = transparentPixels / sampledPixels;
+    const opaqueRatio = opaquePixels / sampledPixels;
+    const metrics = {
+        width: image.width,
+        height: image.height,
+        sampledPixels,
+        uniqueColors,
+        uniqueColorsCapped,
+        uniqueColorRatio,
+        exactNeighborRatio,
+        nearNeighborRatio,
+        edgeDensity,
+        colorEntropy: entropyTotal,
+        transparentRatio,
+        opaqueRatio,
+    };
+    let score = 0;
+    const evidence = [];
+    const maxDimension = Math.max(image.width, image.height);
+    if (maxDimension <= 64) {
+        score += 0.3;
+        evidence.push("Small canvas dimensions are common in sprites and tiles.");
+    }
+    else if (maxDimension <= 160) {
+        score += 0.16;
+        evidence.push("The canvas is small enough to be consistent with a sprite.");
+    }
+    else if (maxDimension >= 1024) {
+        score -= 0.14;
+        evidence.push("Large canvas dimensions are more common in photographic imports.");
+    }
+    if (uniqueColorRatio <= 0.05) {
+        score += 0.32;
+        evidence.push("Most sampled pixels come from a small discrete palette.");
+    }
+    else if (uniqueColorRatio <= 0.18) {
+        score += 0.13;
+        evidence.push("The sampled palette is moderately compact.");
+    }
+    else if (uniqueColorRatio >= 0.65) {
+        score -= 0.3;
+        evidence.push("Many sampled pixels have distinct colors, which is common in photos.");
+    }
+    if (exactNeighborRatio >= 0.45) {
+        score += 0.22;
+        evidence.push("Neighboring pixels often repeat exactly, a common pixel-art signal.");
+    }
+    else if (exactNeighborRatio <= 0.06 && edgeDensity > 0.55) {
+        score -= 0.16;
+        evidence.push("Neighbors change frequently without forming large repeated runs.");
+    }
+    if (nearNeighborRatio >= 0.72 && exactNeighborRatio < 0.2) {
+        score -= 0.12;
+        evidence.push("Many neighbors are only slightly different, suggesting smooth tone changes.");
+    }
+    else if (nearNeighborRatio <= 0.35 && uniqueColorRatio <= 0.25) {
+        score += 0.1;
+        evidence.push("Color changes are crisp while the palette remains compact.");
+    }
+    if (entropyTotal <= 3.5) {
+        score += 0.12;
+        evidence.push("Color entropy is low.");
+    }
+    else if (entropyTotal >= 7.5) {
+        score -= 0.1;
+        evidence.push("Color entropy is high.");
+    }
+    if (transparentRatio >= 0.05) {
+        score += 0.08;
+        evidence.push("Transparency is present, which is common for sprites and cutouts.");
+    }
+    score = clamp(score, -1, 1);
+    const suggestedClassification = classificationFor(score);
+    const requestedOverride = options.userOverride;
+    if (requestedOverride !== undefined &&
+        requestedOverride !== null &&
+        ![
+            PixelArtClassification.LikelyPixelArt,
+            PixelArtClassification.LikelyPhoto,
+            PixelArtClassification.Uncertain,
+        ].includes(requestedOverride)) {
+        throw new RangeError("userOverride must be a valid PixelArtClassification");
+    }
+    const userOverride = requestedOverride ?? null;
+    const overrideApplied = userOverride !== null;
+    const classification = userOverride ?? suggestedClassification;
+    if (overrideApplied)
+        evidence.push(`User override retained: ${userOverride}.`);
+    return {
+        classification,
+        suggestedClassification,
+        confidence: overrideApplied ? 1 : clamp(0.5 + Math.abs(score) * 0.5, 0, 0.99),
+        score,
+        evidence,
+        metrics,
+        userOverride,
+        overrideApplied,
+        isHeuristic: true,
+    };
+}
+export function analyzePixelArt(image, options = {}) {
+    return {
+        ...analyzePixelArtWithoutGrid(image, options),
+        grid: detectWithAlgorithm(image, options.algorithm, options.size),
+    };
+}
+/**
+ * Async analyze for product import-worker. Same metrics/classification as analyzePixelArt;
+ * Auto grid uses detectWithAlgorithmAsync (WASM||proposers Promise overlap).
+ */
+export async function analyzePixelArtAsync(image, options = {}) {
+    const base = analyzePixelArtWithoutGrid(image, options);
+    const grid = await detectWithAlgorithmAsync(image, options.algorithm, options.size);
+    return { ...base, grid };
+}

package/dist/base.d.ts

@@ -0,0 +1,18 @@
+/** Pixel data and checks shared by the importer. Kept free of editor types. */
+export type Rgba = readonly [number, number, number, number];
+/** Straight-alpha RGBA pixels, row by row. */
+export interface PixelBuffer {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}
+export declare const UINT8_MAX = 255;
+/** Keep accidental allocations bounded while allowing ordinary 4K imports. */
+export declare const MAX_IMAGE_DIMENSION = 32768;
+export declare const MAX_IMAGE_PIXELS = 64000000;
+/** Constrains a number to an inclusive interval. */
+export declare function clamp(value: number, minimum: number, maximum: number): number;
+export declare function clampByte(value: number): number;
+export declare function assertDimension(value: number, label: string): number;
+export declare function assertPixelCount(width: number, height: number, label?: string): void;
+export declare function assertPixelBuffer(image: PixelBuffer, label?: string): void;

package/dist/base.js

@@ -0,0 +1,42 @@
+/** Pixel data and checks shared by the importer. Kept free of editor types. */
+export const UINT8_MAX = 255;
+/** Keep accidental allocations bounded while allowing ordinary 4K imports. */
+export const MAX_IMAGE_DIMENSION = 32_768;
+export const MAX_IMAGE_PIXELS = 64_000_000;
+const CHANNELS = 4;
+/** Constrains a number to an inclusive interval. */
+export function clamp(value, minimum, maximum) {
+    return Math.max(minimum, Math.min(maximum, value));
+}
+export function clampByte(value) {
+    return clamp(Math.round(value), 0, UINT8_MAX);
+}
+export function assertDimension(value, label) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > MAX_IMAGE_DIMENSION) {
+        throw new RangeError(`${label} must be an integer from 1 to ${MAX_IMAGE_DIMENSION}`);
+    }
+    return value;
+}
+export function assertPixelCount(width, height, label = "image") {
+    if (width * height > MAX_IMAGE_PIXELS) {
+        throw new RangeError(`${label} is too large; at most ${MAX_IMAGE_PIXELS} pixels are supported`);
+    }
+}
+export function assertPixelBuffer(image, label = "image") {
+    if (!image || typeof image !== "object") {
+        throw new TypeError(`${label} must be a PixelBuffer`);
+    }
+    assertDimension(image.width, `${label}.width`);
+    assertDimension(image.height, `${label}.height`);
+    const pixels = image.width * image.height;
+    if (!Number.isSafeInteger(pixels) || pixels > MAX_IMAGE_PIXELS) {
+        throw new RangeError(`${label} is too large; at most ${MAX_IMAGE_PIXELS} pixels are supported`);
+    }
+    if (!(image.data instanceof Uint8ClampedArray)) {
+        throw new TypeError(`${label}.data must be a Uint8ClampedArray`);
+    }
+    const expectedLength = pixels * CHANNELS;
+    if (image.data.length !== expectedLength) {
+        throw new RangeError(`${label}.data must contain exactly ${expectedLength} bytes`);
+    }
+}

package/dist/cell-color-picker.d.ts

@@ -0,0 +1,14 @@
+import type { PixelBuffer } from "./base.ts";
+import { CellColorPicker } from "./types.ts";
+type Rgba4 = [number, number, number, number];
+export interface CellColorPickerEntry {
+    /** i18n key of the label shown in the import dialog and preferences. */
+    readonly label: string;
+    /** One RGBA colour for the cell [x0,x1) x [y0,y1), or null when it is mostly transparent. */
+    pick(image: PixelBuffer, x0: number, y0: number, x1: number, y1: number): Rgba4 | null;
+    /** Optional pass over the finished output (RGBA data), e.g. merging near-duplicate colours. */
+    finish?(data: Uint8ClampedArray): void;
+}
+export declare function getColorPickerEntry(picker: CellColorPicker): CellColorPickerEntry;
+export declare function getAllColorPickers(): readonly CellColorPicker[];
+export {};

package/dist/cell-color-picker.js

@@ -0,0 +1,278 @@
+import { labToRgb, rgbToLab } from "./color-lab.js";
+import { CellColorPicker } from "./types.js";
+/**
+ * Per-cell colour choice and output colour merging follow KennethJAllen/proper-pixel-art (MIT):
+ * the dominant colour of a cell is the median of the fullest bin of two offset RGB binnings, and
+ * near-duplicate output colours then collapse to the most frequent one. No quantise-first step.
+ */
+const CHANNELS = 4;
+const BIN_SIZE = 52;
+const BINS = Math.floor(255 / BIN_SIZE) + 1;
+const BIN_OFFSET = Math.floor(BIN_SIZE / 2);
+const MERGE_DISTANCE = 12;
+const MIN_OPAQUE_SHARE = 0.5;
+function median(values) {
+    values.sort((a, b) => a - b);
+    const mid = values.length >> 1;
+    return values.length % 2 ? values[mid] : Math.round((values[mid - 1] + values[mid]) / 2);
+}
+/** RGBA of one cell, or null when it is mostly transparent. */
+function dominantColor(image, x0, y0, x1, y1) {
+    const pixels = [];
+    let total = 0;
+    for (let y = y0; y < y1; y++)
+        for (let x = x0; x < x1; x++) {
+            total++;
+            const o = (y * image.width + x) * CHANNELS;
+            if (image.data[o + 3] > 0)
+                pixels.push(o);
+        }
+    if (!total || pixels.length < MIN_OPAQUE_SHARE * total)
+        return null;
+    const channel = (list, c) => list.map((o) => image.data[o + c]);
+    const pick = (list) => [
+        median(channel(list, 0)),
+        median(channel(list, 1)),
+        median(channel(list, 2)),
+        Math.round(channel(list, 3).reduce((a, b) => a + b, 0) / list.length),
+    ];
+    if (pixels.length <= 3)
+        return pick(pixels);
+    const counts = [new Uint32Array(BINS ** 3), new Uint32Array(BINS ** 3)];
+    const keys = [new Int32Array(pixels.length), new Int32Array(pixels.length)];
+    pixels.forEach((o, i) => {
+        for (let grid = 0; grid < 2; grid++) {
+            const shift = grid ? BIN_OFFSET : 0;
+            const bin = (c) => Math.floor(Math.min(255, image.data[o + c] + shift) / BIN_SIZE);
+            const key = (bin(0) * BINS + bin(1)) * BINS + bin(2);
+            keys[grid][i] = key;
+            counts[grid][key]++;
+        }
+    });
+    const best = counts.map((table) => {
+        let key = 0;
+        for (let i = 1; i < table.length; i++)
+            if (table[i] > table[key])
+                key = i;
+        return key;
+    });
+    const grid = counts[0][best[0]] >= counts[1][best[1]] ? 0 : 1;
+    return pick(pixels.filter((_, i) => keys[grid][i] === best[grid]));
+}
+/** Map every colour to the most frequent colour within MERGE_DISTANCE of it. */
+function mergeColors(data) {
+    const counts = new Map();
+    for (let i = 0; i < data.length; i += CHANNELS) {
+        if (!data[i + 3])
+            continue;
+        const key = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const ordered = [...counts].sort((a, b) => b[1] - a[1] || a[0] - b[0]).map(([key]) => key);
+    const reps = [];
+    const mapping = new Map();
+    for (const key of ordered) {
+        const r = key >> 16, g = (key >> 8) & 255, b = key & 255;
+        const rep = reps.find((candidate) => {
+            const dr = (candidate >> 16) - r, dg = ((candidate >> 8) & 255) - g, db = (candidate & 255) - b;
+            return dr * dr + dg * dg + db * db <= MERGE_DISTANCE * MERGE_DISTANCE;
+        });
+        if (rep === undefined)
+            reps.push(key);
+        mapping.set(key, rep ?? key);
+    }
+    for (let i = 0; i < data.length; i += CHANNELS) {
+        if (!data[i + 3])
+            continue;
+        const to = mapping.get((data[i] << 16) | (data[i + 1] << 8) | data[i + 2]);
+        data[i] = to >> 16;
+        data[i + 1] = (to >> 8) & 255;
+        data[i + 2] = to & 255;
+    }
+}
+/** Opaque pixel offsets of a cell, or null when the cell is mostly transparent. */
+function opaqueOffsets(image, x0, y0, x1, y1) {
+    const offsets = [];
+    let total = 0;
+    for (let y = y0; y < y1; y++)
+        for (let x = x0; x < x1; x++) {
+            total++;
+            const o = (y * image.width + x) * CHANNELS;
+            if (image.data[o + 3] > 0)
+                offsets.push(o);
+        }
+    return total && offsets.length >= MIN_OPAQUE_SHARE * total ? offsets : null;
+}
+const channelsOf = (image, offsets, c) => offsets.map((o) => image.data[o + c]);
+const meanOf = (values) => Math.round(values.reduce((a, b) => a + b, 0) / values.length);
+const KMEANS_K = 3;
+const KMEANS_ROUNDS = 8;
+const rgbaAt = (image, o) => [
+    image.data[o],
+    image.data[o + 1],
+    image.data[o + 2],
+    image.data[o + 3],
+];
+const distance2 = (a, b) => (a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2;
+/**
+ * Per-cell k-means (k=3) on RGB; the largest cluster's mean wins. Inspired by the k-centroid
+ * downscaling in PixelOE (Apache-2.0, https://github.com/KohakuBlueleaf/PixelOE); this is an
+ * independent reimplementation with deterministic seeding (darkest, lightest, farthest pixel).
+ */
+function kMeansColor(image, offsets) {
+    const points = offsets.map((o) => rgbaAt(image, o));
+    const luma = (p) => p[0] * 0.299 + p[1] * 0.587 + p[2] * 0.114;
+    const sorted = [...points].sort((a, b) => luma(a) - luma(b));
+    const centers = [sorted[0], sorted[sorted.length - 1]];
+    while (centers.length < KMEANS_K) {
+        let far = points[0];
+        let best = -1;
+        for (const p of points) {
+            const d = Math.min(...centers.map((c) => distance2(p, c)));
+            if (d > best) {
+                best = d;
+                far = p;
+            }
+        }
+        centers.push(far);
+    }
+    let assign = new Int32Array(points.length);
+    for (let round = 0; round < KMEANS_ROUNDS; round++) {
+        assign = Int32Array.from(points, (p) => {
+            let k = 0;
+            for (let i = 1; i < centers.length; i++)
+                if (distance2(p, centers[i]) < distance2(p, centers[k]))
+                    k = i;
+            return k;
+        });
+        for (let k = 0; k < centers.length; k++) {
+            const members = points.filter((_, i) => assign[i] === k);
+            if (members.length)
+                centers[k] = [0, 1, 2].map((c) => members.reduce((s, p) => s + p[c], 0) / members.length);
+        }
+    }
+    const sizes = centers.map((_, k) => assign.filter((a) => a === k).length);
+    const winner = sizes.indexOf(Math.max(...sizes));
+    const members = points.filter((_, i) => assign[i] === winner);
+    return [0, 1, 2, 3].map((c) => meanOf(members.map((p) => p[c])));
+}
+/**
+ * PixelOE's contrast-based patch pick (Apache-2.0, KohakuBlueleaf/PixelOE `find_pixel_luminance`),
+ * reimplemented. A*, b* are the patch medians. L* is the centre pixel's, unless the patch is skewed:
+ * median below mean and the max farther from the median than the min -> the patch minimum;
+ * median above mean and the max nearer the median than the min -> the patch maximum.
+ * The reference runs this on the outline-expanded image; we run it on the source cells.
+ */
+function contrastColor(image, offsets, centre) {
+    const n = offsets.length;
+    const ls = new Float64Array(n);
+    const as = new Float64Array(n);
+    const bs = new Float64Array(n);
+    let sum = 0;
+    let lo = Infinity;
+    let hi = -Infinity;
+    let alpha = 0;
+    for (let i = 0; i < n; i++) {
+        const o = offsets[i];
+        const [l, a, b] = rgbToLab(image.data[o], image.data[o + 1], image.data[o + 2]);
+        ls[i] = l;
+        as[i] = a;
+        bs[i] = b;
+        sum += l;
+        if (l < lo)
+            lo = l;
+        if (l > hi)
+            hi = l;
+        alpha += image.data[o + 3];
+    }
+    const mean = sum / n;
+    const l = sortedMedian(ls);
+    let lightness = rgbToLab(image.data[centre], image.data[centre + 1], image.data[centre + 2])[0];
+    if (l < mean && hi - l > l - lo)
+        lightness = lo;
+    else if (l > mean && hi - l < l - lo)
+        lightness = hi;
+    return [
+        ...labToRgb(lightness, sortedMedian(as), sortedMedian(bs)),
+        Math.round(alpha / n),
+    ];
+}
+/** Median of a typed array; sorts it in place. */
+function sortedMedian(values) {
+    values.sort();
+    const mid = values.length >> 1;
+    return values.length % 2 ? values[mid] : (values[mid - 1] + values[mid]) / 2;
+}
+/** Colour picker table: every picker works on any grid, whichever detector found it. */
+const PICKERS = {
+    [CellColorPicker.MostCommon]: {
+        label: "import.picker.most-common",
+        pick: dominantColor,
+        finish: mergeColors,
+    },
+    [CellColorPicker.Average]: {
+        label: "import.picker.average",
+        pick: (image, x0, y0, x1, y1) => {
+            const o = opaqueOffsets(image, x0, y0, x1, y1);
+            return o && [0, 1, 2, 3].map((c) => meanOf(channelsOf(image, o, c)));
+        },
+    },
+    [CellColorPicker.Median]: {
+        label: "import.picker.median",
+        pick: (image, x0, y0, x1, y1) => {
+            const o = opaqueOffsets(image, x0, y0, x1, y1);
+            return (o &&
+                [
+                    median(channelsOf(image, o, 0)),
+                    median(channelsOf(image, o, 1)),
+                    median(channelsOf(image, o, 2)),
+                    meanOf(channelsOf(image, o, 3)),
+                ]);
+        },
+    },
+    [CellColorPicker.KMeans]: {
+        label: "import.picker.k-means",
+        pick: (image, x0, y0, x1, y1) => {
+            const o = opaqueOffsets(image, x0, y0, x1, y1);
+            return o && kMeansColor(image, o);
+        },
+    },
+    [CellColorPicker.Contrast]: {
+        label: "import.picker.contrast",
+        pick: (image, x0, y0, x1, y1) => {
+            const o = opaqueOffsets(image, x0, y0, x1, y1);
+            const cx = (x0 + x1) >> 1;
+            const cy = (y0 + y1) >> 1;
+            const centre = (cy * image.width + cx) * CHANNELS;
+            return o && contrastColor(image, o, image.data[centre + 3] ? centre : o[o.length >> 1]);
+        },
+    },
+    [CellColorPicker.Nearest]: {
+        label: "import.picker.nearest",
+        pick: (image, x0, y0, x1, y1) => opaqueOffsets(image, x0, y0, x1, y1) &&
+            rgbaAt(image, (((y0 + y1 - 1) >> 1) * image.width + ((x0 + x1 - 1) >> 1)) * CHANNELS),
+    },
+    // Structure, TwoStage and DualRtTwoStage are handled specially in recoverGrid via samplePixelation,
+    // but need placeholder entries here for completeness.
+    [CellColorPicker.Structure]: {
+        label: "import.picker.structure",
+        pick: () => null, // Not used; handled in recoverGrid
+    },
+    [CellColorPicker.TwoStage]: {
+        label: "import.picker.two-stage",
+        pick: () => null, // Not used; handled in recoverGrid
+    },
+    [CellColorPicker.DualRtTwoStage]: {
+        label: "import.picker.dual-rt-two-stage",
+        pick: () => null, // Not used; handled in recoverGrid
+    },
+};
+export function getColorPickerEntry(picker) {
+    const entry = PICKERS[picker];
+    if (!entry)
+        throw new RangeError(`Unknown cell color picker: ${picker}`);
+    return entry;
+}
+export function getAllColorPickers() {
+    return Object.keys(PICKERS);
+}

package/dist/color-lab.d.ts

@@ -0,0 +1,3 @@
+export type Lab = [l: number, a: number, b: number];
+export declare function rgbToLab(r: number, g: number, b: number): Lab;
+export declare function labToRgb(l: number, a: number, b: number): [number, number, number];

package/dist/color-lab.js

@@ -0,0 +1,31 @@
+/** sRGB <-> CIE L*a*b* (D65), channels 0-255 in and out. */
+const WHITE = [0.95047, 1, 1.08883];
+const EPSILON = 216 / 24389;
+const KAPPA = 24389 / 27;
+const toLinear = (v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+};
+/** 8-bit sRGB to linear light, tabulated: the pow() per channel dominated whole-image conversions. */
+const LINEAR = Float64Array.from({ length: 256 }, (_, v) => toLinear(v));
+const fromLinear = (c) => Math.round(255 * Math.min(1, Math.max(0, c <= 0.0031308 ? c * 12.92 : 1.055 * c ** (1 / 2.4) - 0.055)));
+const forward = (t) => (t > EPSILON ? Math.cbrt(t) : (KAPPA * t + 16) / 116);
+const inverse = (f) => (f ** 3 > EPSILON ? f ** 3 : (116 * f - 16) / KAPPA);
+export function rgbToLab(r, g, b) {
+    const lr = LINEAR[r] ?? toLinear(r), lg = LINEAR[g] ?? toLinear(g), lb = LINEAR[b] ?? toLinear(b);
+    const x = forward((0.4124564 * lr + 0.3575761 * lg + 0.1804375 * lb) / WHITE[0]);
+    const y = forward(0.2126729 * lr + 0.7151522 * lg + 0.072175 * lb);
+    const z = forward((0.0193339 * lr + 0.119192 * lg + 0.9503041 * lb) / WHITE[2]);
+    return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+}
+export function labToRgb(l, a, b) {
+    const fy = (l + 16) / 116;
+    const x = inverse(fy + a / 500) * WHITE[0];
+    const y = inverse(fy);
+    const z = inverse(fy - b / 200) * WHITE[2];
+    return [
+        fromLinear(3.2404542 * x - 1.5371385 * y - 0.4985314 * z),
+        fromLinear(-0.969266 * x + 1.8760108 * y + 0.041556 * z),
+        fromLinear(0.0556434 * x - 0.2040259 * y + 1.0572252 * z),
+    ];
+}

package/dist/color-step.d.ts

@@ -0,0 +1,33 @@
+import type { PixelBuffer } from "./base.ts";
+/** `m / 255` for every whole channel difference m, as doubles and as float32. */
+export declare const OPAQUE_STEPS: Float64Array<ArrayBuffer>;
+export declare const OPAQUE_STEPS_32: Float32Array<ArrayBuffer>;
+/** Step code of a pair that is not opaque on both sides: its step is computed in full. */
+export declare const TRANSLUCENT: number;
+/**
+ * The colour step (0..1) between two RGBA pixels: the largest premultiplied channel or alpha
+ * difference.
+ */
+export declare function colorStep(data: Uint8ClampedArray, first: number, second: number): number;
+/**
+ * Every pixel's step to its right and lower neighbour, as codes: for two opaque pixels the step is
+ * the largest channel difference m over 255 exactly, so m is kept; other pairs are marked
+ * {@link TRANSLUCENT}. Tilt estimation and grid detection read the same image's pairs, so the last
+ * image's codes are kept.
+ */
+export interface NeighbourSteps {
+    image: PixelBuffer;
+    /** Code of the step from pixel p to p + 1 (unused in the last column). */
+    right: Uint16Array;
+    /** Code of the step from pixel p to p + width (unused in the last row). */
+    down: Uint16Array;
+}
+export declare function neighbourSteps(image: PixelBuffer): NeighbourSteps;
+/** Drop the kept codes once the image's edge analysis is done. */
+export declare function releaseNeighbourSteps(image: PixelBuffer): void;
+/** Drop the kept codes, whichever image they belong to. */
+export declare function forgetNeighbourSteps(): void;
+/** The step (a double, as {@link colorStep}) of the pair from pixel p to p + offset. */
+export declare function stepOf(codes: Uint16Array, data: Uint8ClampedArray, p: number, offset: number): number;
+/** The same step rounded to float32. */
+export declare function step32Of(codes: Uint16Array, data: Uint8ClampedArray, p: number, offset: number): number;