@xprite/pixelate 0.0.0-stage → 0.1.1

package/dist/outline-prepass.js

@@ -0,0 +1,56 @@
+import { rememberPixeloe, sourceLineMask, } from "./line-guided/pixeloe-entry.js";
+import { pixeloePrepass } from "./pixeloe-prepass.js";
+import { CellColorPicker, LineGuideMode, OutlinePrepass, PixelationAlgorithm, PixelationMode, } from "./types.js";
+/**
+ * Whether these options run stock PixelOE end to end (its contrast downscale and colour match to the
+ * output size) instead of a pre-pass followed by the picker: a PixelOE pre-pass with the Contrast
+ * picker, when the cells are not a grid recovered from the source (a plain convert, or Custom size's
+ * even blocks). This is the PixelOE reference output.
+ */
+export function runsStockPixeloe(options, grid) {
+    if ((options.prepass ?? OutlinePrepass.None) === OutlinePrepass.None)
+        return false;
+    if (options.colorPicker !== CellColorPicker.Contrast)
+        return false;
+    if (options.mode === PixelationMode.Convert)
+        return true;
+    return grid?.algorithm === PixelationAlgorithm.CustomSize;
+}
+/**
+ * The image -> image pre-pass (the original PixelOE pre-pass, optionally line-guided). Recent
+ * results are reused, so a colour or picker change on the same image does not rerun it.
+ */
+export function applyOutlinePrepass(image, cell, prepass, lineGuide = DEFAULT_LINE_GUIDE) {
+    if (prepass === OutlinePrepass.None)
+        return image;
+    // The pre-pass reads the cell size rounded to whole pixels only.
+    const variant = `prepass:${prepass}:${Math.round(cell)}:${prepass === OutlinePrepass.Pixeloe ? "" : lineGuide}`;
+    return rememberPixeloe(image, variant, () => {
+        if (prepass === OutlinePrepass.Pixeloe)
+            return pixeloePrepass(image, cell);
+        const mask = sourceLineMask(image);
+        return pixeloePrepass(image, cell, mask ? { mask, mode: lineGuide } : undefined);
+    });
+}
+/**
+ * The pre-pass every source opens with, whether or not a grid is found: PixelOE + lines (with the
+ * Contrast picker). None, the plain grid recovery, is one choice away in the controls.
+ */
+export const DEFAULT_OUTLINE_PREPASS = OutlinePrepass.PixeloeLines;
+/**
+ * The line guide PixelOE + lines starts with: Lines only (the line mask replaces PixelOE's outline
+ * weight). Add to outlines barely differs from plain PixelOE on line art, while Lines only keeps
+ * continuous drawn lines (e.g. an eye line) through the downscale.
+ */
+export const DEFAULT_LINE_GUIDE = LineGuideMode.Replace;
+/**
+ * A pre-pass from saved settings: the current value, or the old `pixeloePrepass` checkbox
+ * (true -> PixelOE, false -> None).
+ */
+export function readOutlinePrepass(saved) {
+    if (Object.values(OutlinePrepass).includes(saved.prepass))
+        return saved.prepass;
+    if (typeof saved.pixeloePrepass === "boolean")
+        return saved.pixeloePrepass ? OutlinePrepass.Pixeloe : OutlinePrepass.None;
+    return undefined;
+}

package/dist/palette-snap.d.ts

@@ -0,0 +1,4 @@
+import type { PixelBuffer } from "./base.ts";
+import { type PaletteSnapOptions } from "./types.ts";
+/** The recovered image with its colours snapped; the source is never modified. */
+export declare function snapPalette(image: PixelBuffer, options: PaletteSnapOptions): PixelBuffer;

package/dist/palette-snap.js

@@ -0,0 +1,371 @@
+import { rgbToLab, labToRgb } from "./color-lab.js";
+import { PixelationDither } from "./types.js";
+/**
+ * Optional "snap palette" step for a recovered (small) image: collapse the many near-shades that
+ * AI art and JPEG sources leave behind into a clean, flat palette, or snap to a palette the user
+ * supplies. Rare-but-important colours (skin tones, highlights) are kept by two rules:
+ *  - only near-duplicates (within `MERGE_DELTA` in CIE Lab) are ever merged without a budget, and
+ *  - k-means is seeded by weighted farthest-point selection, so a colour far from everything else
+ *    gets its own palette entry before a frequent shade that is only a little different.
+ * Alpha is never clustered: each pixel keeps its own opacity and fully transparent pixels stay put.
+ * When Limit colors dithering is on, the built palette is applied per pixel with ordered
+ * (Bayer 8×8 → palette, ported from tensorhead/dithering MIT) or Floyd–Steinberg error
+ * diffusion instead of a flat shade remap.
+ */
+const MIN_COLORS = 2;
+const MAX_COLORS = 256;
+const DEFAULT_COLORS = 16;
+/** CIE76 distance below which two colours are the same shade for practical purposes. */
+const MERGE_DELTA = 3;
+/** Seeding score = distance * count^SEED_WEIGHT: mostly distance, a little frequency. */
+const SEED_WEIGHT = 0.25;
+/** Cluster pull = count^PULL_WEIGHT, so large flat areas do not drag centroids off rare colours. */
+const PULL_WEIGHT = 0.5;
+const MAX_ITERATIONS = 32;
+const CHANNELS = 4;
+/**
+ * Bayer 8×8 indices from tensorhead/dithering (MIT). Thresholds use (index + 0.5) / 64.
+ * See https://github.com/tensorhead/dithering — matrices.rs / ordered.rs ordered_palette.
+ */
+const BAYER_8 = [
+    0, 32, 8, 40, 2, 34, 10, 42, 48, 16, 56, 24, 50, 18, 58, 26, 12, 44, 4, 36, 14, 46, 6, 38, 60, 28,
+    52, 20, 62, 30, 54, 22, 3, 35, 11, 43, 1, 33, 9, 41, 51, 19, 59, 27, 49, 17, 57, 25, 15, 47, 7,
+    39, 13, 45, 5, 37, 63, 31, 55, 23, 61, 29, 53, 21,
+];
+const distance = (a, b) => Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+const clampByte = (value) => Math.max(0, Math.min(255, Math.round(value)));
+function histogram(image) {
+    const { data } = image;
+    const pixels = data.length / CHANNELS;
+    const seen = new Map();
+    const shades = [];
+    const index = new Int32Array(pixels).fill(-1);
+    for (let i = 0; i < pixels; i++) {
+        const o = i * CHANNELS;
+        if (data[o + 3] === 0)
+            continue;
+        const key = (data[o] << 16) | (data[o + 1] << 8) | data[o + 2];
+        let at = seen.get(key);
+        if (at === undefined) {
+            at = shades.length;
+            seen.set(key, at);
+            shades.push({
+                rgb: [data[o], data[o + 1], data[o + 2]],
+                lab: rgbToLab(data[o], data[o + 1], data[o + 2]),
+                count: 0,
+            });
+        }
+        shades[at].count += 1;
+        index[i] = at;
+    }
+    return { shades, index };
+}
+/** Greedy leader clustering, heaviest first: only colours within MERGE_DELTA share a group. */
+function mergeNearDuplicates(shades) {
+    const order = shades.map((_, i) => i).sort((a, b) => shades[b].count - shades[a].count || a - b);
+    const groups = [];
+    for (const i of order) {
+        let best = -1, bestDistance = MERGE_DELTA;
+        for (let g = 0; g < groups.length; g++) {
+            const d = distance(shades[i].lab, shades[groups[g][0]].lab);
+            if (d <= bestDistance) {
+                bestDistance = d;
+                best = g;
+            }
+        }
+        if (best < 0)
+            groups.push([i]);
+        else
+            groups[best].push(i);
+    }
+    return groups;
+}
+function toPoints(shades, groups) {
+    return groups.map((members) => {
+        let count = 0;
+        const sum = [0, 0, 0];
+        for (const m of members) {
+            count += shades[m].count;
+            for (let c = 0; c < 3; c++)
+                sum[c] += shades[m].lab[c] * shades[m].count;
+        }
+        return {
+            lab: [sum[0] / count, sum[1] / count, sum[2] / count],
+            count,
+            members,
+        };
+    });
+}
+/** Weighted farthest-point seeding: start from the commonest colour, then keep adding the colour
+ * that is farthest from every seed so far (lightly favouring frequent ones). */
+function seed(points, k) {
+    let first = 0;
+    for (let i = 1; i < points.length; i++)
+        if (points[i].count > points[first].count)
+            first = i;
+    const seeds = [points[first].lab];
+    const nearest = points.map((p) => distance(p.lab, seeds[0]));
+    while (seeds.length < k) {
+        let pick = -1, pickScore = 0;
+        for (let i = 0; i < points.length; i++) {
+            const score = nearest[i] * points[i].count ** SEED_WEIGHT;
+            if (score > pickScore) {
+                pickScore = score;
+                pick = i;
+            }
+        }
+        if (pick < 0)
+            break;
+        seeds.push(points[pick].lab);
+        for (let i = 0; i < points.length; i++)
+            nearest[i] = Math.min(nearest[i], distance(points[i].lab, points[pick].lab));
+    }
+    return seeds;
+}
+function cluster(points, k) {
+    const centers = seed(points, k);
+    const assign = new Int32Array(points.length).fill(-1);
+    for (let iteration = 0; iteration < MAX_ITERATIONS; iteration++) {
+        let changed = false;
+        for (let i = 0; i < points.length; i++) {
+            let best = 0, bestDistance = Infinity;
+            for (let c = 0; c < centers.length; c++) {
+                const d = distance(points[i].lab, centers[c]);
+                if (d < bestDistance) {
+                    bestDistance = d;
+                    best = c;
+                }
+            }
+            if (assign[i] !== best) {
+                assign[i] = best;
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+        const sums = centers.map(() => [0, 0, 0, 0]);
+        for (let i = 0; i < points.length; i++) {
+            const weight = points[i].count ** PULL_WEIGHT;
+            const s = sums[assign[i]];
+            for (let c = 0; c < 3; c++)
+                s[c] += points[i].lab[c] * weight;
+            s[3] += weight;
+        }
+        for (let c = 0; c < centers.length; c++)
+            if (sums[c][3] > 0)
+                centers[c] = [sums[c][0] / sums[c][3], sums[c][1] / sums[c][3], sums[c][2] / sums[c][3]];
+    }
+    return Array.from(assign);
+}
+function paletteLabs(palette) {
+    const visible = palette.filter((color) => color[3] > 0);
+    if (!visible.length)
+        throw new RangeError("Choose a palette containing a visible color.");
+    return {
+        labs: visible.map((c) => rgbToLab(c[0], c[1], c[2])),
+        rgb: visible.map((c) => c),
+    };
+}
+function nearestPaletteRgb(lab, labs, rgb) {
+    let best = 0, bestDistance = Infinity;
+    for (let i = 0; i < labs.length; i++) {
+        const d = distance(lab, labs[i]);
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = i;
+        }
+    }
+    return [rgb[best][0], rgb[best][1], rgb[best][2]];
+}
+/**
+ * Per-channel palette spread used by ordered Bayer→palette (tensorhead/dithering):
+ * (max − min) / (distinct − 1) in each channel; 0 when the channel is constant.
+ */
+function paletteSpread(palette) {
+    const spread = [0, 0, 0];
+    for (let channel = 0; channel < 3; channel++) {
+        const values = [];
+        for (const color of palette) {
+            const value = color[channel];
+            if (!values.includes(value))
+                values.push(value);
+        }
+        values.sort((a, b) => a - b);
+        if (values.length > 1)
+            spread[channel] = (values[values.length - 1] - values[0]) / (values.length - 1);
+    }
+    return spread;
+}
+/** Nearest palette entry by Euclidean RGB distance (working space of tensorhead/dithering). */
+function nearestPaletteRgbEuclidean(r, g, b, palette) {
+    let best = 0, bestDistance = Infinity;
+    for (let i = 0; i < palette.length; i++) {
+        const dr = r - palette[i][0];
+        const dg = g - palette[i][1];
+        const db = b - palette[i][2];
+        const d = dr * dr + dg * dg + db * db;
+        if (d < bestDistance) {
+            bestDistance = d;
+            best = i;
+        }
+    }
+    return [palette[best][0], palette[best][1], palette[best][2]];
+}
+/**
+ * Ordered Bayer 8×8 → palette. Port of tensorhead/dithering `ordered_palette` (MIT):
+ * threshold offset (t − 0.5) scaled by each channel's palette spread, then RGB nearest.
+ * Unlike ±RGB Bayer then Lab nearest, this still dithers when every pixel is already a palette colour.
+ */
+function orderedBayer8ToPalette(image, palette) {
+    const spread = paletteSpread(palette);
+    const output = new Uint8ClampedArray(image.data);
+    const { width, height, data } = image;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const at = (y * width + x) * CHANNELS;
+            if (data[at + 3] === 0)
+                continue;
+            const t = (BAYER_8[(y & 7) * 8 + (x & 7)] + 0.5) / 64 - 0.5;
+            const chosen = nearestPaletteRgbEuclidean(data[at] + t * spread[0], data[at + 1] + t * spread[1], data[at + 2] + t * spread[2], palette);
+            output[at] = chosen[0];
+            output[at + 1] = chosen[1];
+            output[at + 2] = chosen[2];
+        }
+    }
+    return { width, height, data: output };
+}
+/**
+ * Floyd–Steinberg error diffusion to `palette` in Lab-nearest space.
+ * Transparent pixels are left alone.
+ */
+function floydSteinbergToPalette(image, palette) {
+    const { labs, rgb } = paletteLabs(palette);
+    const output = new Uint8ClampedArray(image.data);
+    const { width, height, data } = image;
+    const error = new Float32Array(width * height * 3);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            const at = i * CHANNELS;
+            if (data[at + 3] === 0)
+                continue;
+            const sample = [
+                clampByte(data[at] + error[i * 3]),
+                clampByte(data[at + 1] + error[i * 3 + 1]),
+                clampByte(data[at + 2] + error[i * 3 + 2]),
+            ];
+            const chosen = nearestPaletteRgb(rgbToLab(sample[0], sample[1], sample[2]), labs, rgb);
+            output[at] = chosen[0];
+            output[at + 1] = chosen[1];
+            output[at + 2] = chosen[2];
+            for (let channel = 0; channel < 3; channel++) {
+                const delta = sample[channel] - chosen[channel];
+                if (x + 1 < width)
+                    error[(i + 1) * 3 + channel] += (delta * 7) / 16;
+                if (y + 1 < height) {
+                    if (x > 0)
+                        error[(i + width - 1) * 3 + channel] += (delta * 3) / 16;
+                    error[(i + width) * 3 + channel] += (delta * 5) / 16;
+                    if (x + 1 < width)
+                        error[(i + width + 1) * 3 + channel] += delta / 16;
+                }
+            }
+        }
+    }
+    return { width, height, data: output };
+}
+function ditherToPalette(image, palette, dither) {
+    return dither === PixelationDither.Ordered
+        ? orderedBayer8ToPalette(image, palette)
+        : floydSteinbergToPalette(image, palette);
+}
+/** Build the reduced RGB palette (k-means or the given list); null when the image already fits. */
+function buildPalette(shades, options) {
+    if (options.palette)
+        return paletteLabs(options.palette).rgb;
+    const groups = mergeNearDuplicates(shades);
+    const colors = options.adaptive
+        ? Math.min(groups.length, MAX_COLORS)
+        : Math.max(MIN_COLORS, Math.min(MAX_COLORS, Math.round(options.colors ?? DEFAULT_COLORS)));
+    if (shades.length <= colors)
+        return null;
+    const points = toPoints(shades, groups);
+    const assignment = points.length <= colors ? points.map((_, i) => i) : cluster(points, colors);
+    const sums = new Map();
+    points.forEach((point, i) => {
+        const entry = sums.get(assignment[i]) ?? { lab: [0, 0, 0], count: 0 };
+        for (let c = 0; c < 3; c++)
+            entry.lab[c] += point.lab[c] * point.count;
+        entry.count += point.count;
+        sums.set(assignment[i], entry);
+    });
+    const palette = [];
+    for (const { lab, count } of sums.values()) {
+        const [r, g, b] = labToRgb(lab[0] / count, lab[1] / count, lab[2] / count);
+        palette.push([r, g, b, 255]);
+    }
+    return palette;
+}
+/** Flat nearest-shade remap (no positional dither). */
+function remapShades(image, shades, index, options) {
+    const output = new Uint8ClampedArray(image.data);
+    let target;
+    if (options.palette) {
+        const { labs, rgb } = paletteLabs(options.palette);
+        target = shades.map((shade) => nearestPaletteRgb(shade.lab, labs, rgb));
+    }
+    else {
+        const groups = mergeNearDuplicates(shades);
+        const colors = options.adaptive
+            ? Math.min(groups.length, MAX_COLORS)
+            : Math.max(MIN_COLORS, Math.min(MAX_COLORS, Math.round(options.colors ?? DEFAULT_COLORS)));
+        if (shades.length <= colors)
+            return { width: image.width, height: image.height, data: output };
+        const points = toPoints(shades, groups);
+        const assignment = points.length <= colors ? points.map((_, i) => i) : cluster(points, colors);
+        const sums = new Map();
+        points.forEach((point, i) => {
+            const entry = sums.get(assignment[i]) ?? { lab: [0, 0, 0], count: 0 };
+            for (let c = 0; c < 3; c++)
+                entry.lab[c] += point.lab[c] * point.count;
+            entry.count += point.count;
+            sums.set(assignment[i], entry);
+        });
+        const colorOf = new Map();
+        for (const [id, { lab, count }] of sums)
+            colorOf.set(id, labToRgb(lab[0] / count, lab[1] / count, lab[2] / count));
+        target = Array.from({ length: shades.length }, () => [0, 0, 0]);
+        points.forEach((point, i) => {
+            for (const member of point.members)
+                target[member] = colorOf.get(assignment[i]);
+        });
+    }
+    for (let i = 0; i < index.length; i++) {
+        if (index[i] < 0)
+            continue;
+        const color = target[index[i]];
+        output[i * CHANNELS] = color[0];
+        output[i * CHANNELS + 1] = color[1];
+        output[i * CHANNELS + 2] = color[2];
+    }
+    return { width: image.width, height: image.height, data: output };
+}
+/** The recovered image with its colours snapped; the source is never modified. */
+export function snapPalette(image, options) {
+    const dither = Object.values(PixelationDither).includes(options.dither)
+        ? options.dither
+        : PixelationDither.None;
+    const { shades, index } = histogram(image);
+    if (dither === PixelationDither.None)
+        return remapShades(image, shades, index, options);
+    // Ordered / Floyd–Steinberg need a concrete palette, then per-pixel Lab nearest.
+    const palette = buildPalette(shades, options);
+    if (!palette) {
+        // Already within budget and no user palette: dither among the image's own shades.
+        if (!shades.length)
+            return { width: image.width, height: image.height, data: new Uint8ClampedArray(image.data) };
+        const own = shades.map((shade) => [shade.rgb[0], shade.rgb[1], shade.rgb[2], 255]);
+        return ditherToPalette(image, own, dither);
+    }
+    return ditherToPalette(image, palette, dither);
+}

package/dist/palette.d.ts

@@ -0,0 +1,21 @@
+import type { PixelBuffer, Rgba } from "./base.ts";
+import type { ExtractPaletteOptions, PaletteEntry } from "./types.ts";
+/**
+ * Extract a deterministic, bounded palette. Exact colors are retained for
+ * ordinary sprites; a fixed 32x32x32x16 histogram is used for noisy images so
+ * memory stays bounded instead of growing with every photograph pixel.
+ */
+export declare function extractPalette(image: PixelBuffer, options?: ExtractPaletteOptions): PaletteEntry[];
+/** Count distinct RGBA values with a bounded result for large images. */
+export declare function countDistinctColors(image: PixelBuffer, limit?: number): number;
+/** Perceptual matching with exact RGBA cache keys; colors within a coarse bin may differ. */
+export declare function reduceToPalette(image: PixelBuffer, palette: readonly Rgba[], options?: {
+    preserveAlpha?: boolean;
+}): PixelBuffer;
+/** Palette generation counts visible RGB independently of coverage. */
+export declare function extractPixelationPalette(image: PixelBuffer, options?: ExtractPaletteOptions): PaletteEntry[];
+/** Compact mapped-RGB groups for the bounded Structure/TwoStage palettes. */
+export declare function reduceToPixelationLabels(image: PixelBuffer, palette: readonly Rgba[]): {
+    data: Uint8Array<ArrayBuffer>;
+    keys: number[];
+};