@xprite/pixelate 0.0.0-stage → 0.1.0

package/dist/remove-background.d.ts

@@ -0,0 +1,40 @@
+import type { PixelBuffer, Rgba } from "./base.ts";
+export declare enum RemoveBackgroundMode {
+    Auto = "auto",
+    Manual = "manual"
+}
+export interface RemoveBackgroundOptions {
+    mode?: RemoveBackgroundMode;
+    /** Euclidean RGB distance; Manual default 32. Auto ignores this and picks adaptively. */
+    tolerance?: number;
+    /** Manual key color (RGB used; alpha ignored). Null falls back to Auto border key. */
+    keyColor?: Rgba | null;
+}
+export interface RemoveBackgroundSettings {
+    enabled: boolean;
+    mode: RemoveBackgroundMode;
+    tolerance: number;
+    keyColor: Rgba | null;
+}
+export declare const DEFAULT_REMOVE_BACKGROUND: RemoveBackgroundSettings;
+/** Euclidean RGB distance between a pixel and a key color. */
+export declare function colorKeyDistance(r: number, g: number, b: number, key: readonly [number, number, number] | Rgba): number;
+/**
+ * Most common quantized border color (top/bottom/left/right edges). Matches the research
+ * classical Auto key used on flat sprite backgrounds.
+ */
+export declare function modeBorderColor(image: PixelBuffer): Rgba;
+/**
+ * Edge-seeded flood: candidates within tolerance of `key` that connect to the image border
+ * become transparent. Enclosed subject holes (letter O, etc.) stay opaque.
+ */
+export declare function edgeSeededFloodAlpha(image: PixelBuffer, key: readonly [number, number, number] | Rgba, tolerance: number): Uint8Array;
+/** Pick tolerance by scoring edge-flood masks (Auto path). */
+export declare function adaptiveTolerance(image: PixelBuffer, key: readonly [number, number, number] | Rgba): number;
+/**
+ * Classical Track B remove-background: edge-seeded flood + color tolerance.
+ * Auto samples the mode border color and chooses tolerance; Manual uses key + tolerance.
+ */
+export declare function removeBackground(image: PixelBuffer, options?: RemoveBackgroundOptions): PixelBuffer;
+/** Sample one pixel as an RGBA key for Manual mode (transparent pixels ignored by caller). */
+export declare function sampleKeyColor(image: PixelBuffer, x: number, y: number): Rgba | null;

package/dist/remove-background.js

@@ -0,0 +1,229 @@
+const CHANNELS = 4;
+const DEFAULT_TOLERANCE = 32;
+const BORDER_QUANT = 8;
+/** Candidate tolerances for Auto adaptive scoring (inclusive of Ryan's ~24–48 band). */
+const AUTO_TOLERANCES = [16, 24, 32, 40, 48, 64, 80, 100];
+export var RemoveBackgroundMode;
+(function (RemoveBackgroundMode) {
+    RemoveBackgroundMode["Auto"] = "auto";
+    RemoveBackgroundMode["Manual"] = "manual";
+})(RemoveBackgroundMode || (RemoveBackgroundMode = {}));
+export const DEFAULT_REMOVE_BACKGROUND = {
+    enabled: false,
+    mode: RemoveBackgroundMode.Auto,
+    tolerance: DEFAULT_TOLERANCE,
+    keyColor: null,
+};
+/** Euclidean RGB distance between a pixel and a key color. */
+export function colorKeyDistance(r, g, b, key) {
+    const dr = r - key[0];
+    const dg = g - key[1];
+    const db = b - key[2];
+    return Math.sqrt(dr * dr + dg * dg + db * db);
+}
+/**
+ * Most common quantized border color (top/bottom/left/right edges). Matches the research
+ * classical Auto key used on flat sprite backgrounds.
+ */
+export function modeBorderColor(image) {
+    const { width, height, data } = image;
+    const counts = new Map();
+    const bump = (x, y) => {
+        const i = (y * width + x) * CHANNELS;
+        if (data[i + 3] === 0)
+            return;
+        const qr = (Math.floor(data[i] / BORDER_QUANT) * BORDER_QUANT + (BORDER_QUANT >> 1)) & 255;
+        const qg = (Math.floor(data[i + 1] / BORDER_QUANT) * BORDER_QUANT + (BORDER_QUANT >> 1)) & 255;
+        const qb = (Math.floor(data[i + 2] / BORDER_QUANT) * BORDER_QUANT + (BORDER_QUANT >> 1)) & 255;
+        const key = (qr << 16) | (qg << 8) | qb;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    };
+    for (let x = 0; x < width; x++) {
+        bump(x, 0);
+        if (height > 1)
+            bump(x, height - 1);
+    }
+    for (let y = 1; y < height - 1; y++) {
+        bump(0, y);
+        if (width > 1)
+            bump(width - 1, y);
+    }
+    let bestKey = 0;
+    let bestCount = -1;
+    for (const [key, count] of counts) {
+        if (count > bestCount) {
+            bestCount = count;
+            bestKey = key;
+        }
+    }
+    if (bestCount < 0)
+        return [0, 0, 0, 255];
+    return [(bestKey >> 16) & 255, (bestKey >> 8) & 255, bestKey & 255, 255];
+}
+/**
+ * Edge-seeded flood: candidates within tolerance of `key` that connect to the image border
+ * become transparent. Enclosed subject holes (letter O, etc.) stay opaque.
+ */
+export function edgeSeededFloodAlpha(image, key, tolerance) {
+    const { width, height, data } = image;
+    const n = width * height;
+    const alpha = new Uint8Array(n);
+    alpha.fill(255);
+    if (n === 0)
+        return alpha;
+    const candidate = new Uint8Array(n);
+    for (let i = 0, p = 0; i < n; i++, p += CHANNELS) {
+        if (data[p + 3] === 0) {
+            candidate[i] = 1;
+            continue;
+        }
+        if (colorKeyDistance(data[p], data[p + 1], data[p + 2], key) <= tolerance)
+            candidate[i] = 1;
+    }
+    const stack = new Int32Array(n);
+    let top = 0;
+    const pushBorder = (i) => {
+        if (!candidate[i] || alpha[i] === 0)
+            return;
+        alpha[i] = 0;
+        stack[top++] = i;
+    };
+    for (let x = 0; x < width; x++) {
+        pushBorder(x);
+        if (height > 1)
+            pushBorder((height - 1) * width + x);
+    }
+    for (let y = 1; y < height - 1; y++) {
+        pushBorder(y * width);
+        if (width > 1)
+            pushBorder(y * width + (width - 1));
+    }
+    while (top > 0) {
+        const i = stack[--top];
+        const x = i % width;
+        const y = (i / width) | 0;
+        if (x > 0)
+            pushBorder(i - 1);
+        if (x + 1 < width)
+            pushBorder(i + 1);
+        if (y > 0)
+            pushBorder(i - width);
+        if (y + 1 < height)
+            pushBorder(i + width);
+    }
+    return alpha;
+}
+function scoreMask(alpha, width, height, dist) {
+    const n = width * height;
+    if (n === 0)
+        return 0;
+    let removed = 0;
+    let borderClear = 0;
+    let borderCount = 0;
+    let centerKeep = 0;
+    let centerCount = 0;
+    let leftoverBg = 0;
+    let holes = 0;
+    const cy0 = (height / 4) | 0;
+    const cy1 = ((3 * height) / 4) | 0;
+    const cx0 = (width / 4) | 0;
+    const cx1 = ((3 * width) / 4) | 0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            const clear = alpha[i] === 0;
+            if (clear)
+                removed++;
+            const onBorder = y === 0 || y === height - 1 || x === 0 || x === width - 1;
+            if (onBorder) {
+                borderCount++;
+                if (clear)
+                    borderClear++;
+            }
+            const inCenter = y >= cy0 && y < cy1 && x >= cx0 && x < cx1;
+            if (inCenter) {
+                centerCount++;
+                if (!clear)
+                    centerKeep++;
+                if (clear && dist[i] > 40)
+                    holes++;
+            }
+            if (!clear && dist[i] <= 18)
+                leftoverBg++;
+        }
+    }
+    const removedRatio = removed / n;
+    const borderRatio = borderCount ? borderClear / borderCount : 0;
+    const centerRatio = centerCount ? centerKeep / centerCount : 1;
+    const leftoverRatio = leftoverBg / n;
+    const holesRatio = centerCount ? holes / centerCount : 0;
+    return (0.35 * borderRatio +
+        0.35 * centerRatio +
+        0.15 * Math.min(removedRatio / 0.45, 1) -
+        0.25 * leftoverRatio -
+        0.4 * holesRatio);
+}
+function distanceField(image, key) {
+    const { width, height, data } = image;
+    const dist = new Float32Array(width * height);
+    for (let i = 0, p = 0; i < dist.length; i++, p += CHANNELS) {
+        if (data[p + 3] === 0) {
+            dist[i] = 0;
+            continue;
+        }
+        dist[i] = colorKeyDistance(data[p], data[p + 1], data[p + 2], key);
+    }
+    return dist;
+}
+/** Pick tolerance by scoring edge-flood masks (Auto path). */
+export function adaptiveTolerance(image, key) {
+    const dist = distanceField(image, key);
+    let bestTol = AUTO_TOLERANCES[0];
+    let bestScore = Number.NEGATIVE_INFINITY;
+    for (const tol of AUTO_TOLERANCES) {
+        const alpha = edgeSeededFloodAlpha(image, key, tol);
+        const score = scoreMask(alpha, image.width, image.height, dist);
+        if (score > bestScore) {
+            bestScore = score;
+            bestTol = tol;
+        }
+    }
+    return bestTol;
+}
+/** Clears every removed pixel, colour included, so the old background leaves no hidden pattern. */
+function applyAlpha(image, alpha) {
+    const data = new Uint8ClampedArray(image.data);
+    for (let i = 0, p = 0; i < alpha.length; i++, p += CHANNELS) {
+        if (alpha[i] === 0)
+            data.fill(0, p, p + CHANNELS);
+    }
+    return { width: image.width, height: image.height, data };
+}
+/**
+ * Classical Track B remove-background: edge-seeded flood + color tolerance.
+ * Auto samples the mode border color and chooses tolerance; Manual uses key + tolerance.
+ */
+export function removeBackground(image, options = {}) {
+    const mode = options.mode ?? RemoveBackgroundMode.Auto;
+    const key = mode === RemoveBackgroundMode.Manual && options.keyColor
+        ? options.keyColor
+        : modeBorderColor(image);
+    const tolerance = mode === RemoveBackgroundMode.Auto
+        ? adaptiveTolerance(image, key)
+        : Number.isFinite(options.tolerance)
+            ? Math.max(0, options.tolerance)
+            : DEFAULT_TOLERANCE;
+    return applyAlpha(image, edgeSeededFloodAlpha(image, key, tolerance));
+}
+/** Sample one pixel as an RGBA key for Manual mode (transparent pixels ignored by caller). */
+export function sampleKeyColor(image, x, y) {
+    const px = Math.floor(x);
+    const py = Math.floor(y);
+    if (px < 0 || py < 0 || px >= image.width || py >= image.height)
+        return null;
+    const i = (py * image.width + px) * CHANNELS;
+    const a = image.data[i + 3];
+    if (a === 0)
+        return null;
+    return [image.data[i], image.data[i + 1], image.data[i + 2], 255];
+}

package/dist/resize.d.ts

@@ -0,0 +1,3 @@
+import type { PixelBuffer } from "./base.ts";
+export declare function resizeNearest(image: PixelBuffer, width: number, height: number): PixelBuffer;
+export declare function resizeBox(image: PixelBuffer, width: number, height: number, alphaMode: "straight" | "premultiplied"): PixelBuffer;

package/dist/resize.js

@@ -0,0 +1,86 @@
+import { UINT8_MAX } from "./base.js";
+import { assertDimension, assertPixelCount, clampByte } from "./base.js";
+export function resizeNearest(image, width, height) {
+    assertDimension(width, "width");
+    assertDimension(height, "height");
+    assertPixelCount(width, height);
+    const output = new Uint8ClampedArray(width * height * 4);
+    const source = image.data;
+    for (let y = 0; y < height; y += 1) {
+        const sourceY = Math.min(image.height - 1, Math.floor((y * image.height) / height));
+        for (let x = 0; x < width; x += 1) {
+            const sourceX = Math.min(image.width - 1, Math.floor((x * image.width) / width));
+            const sourceOffset = (sourceY * image.width + sourceX) * 4;
+            const outputOffset = (y * width + x) * 4;
+            output[outputOffset] = source[sourceOffset];
+            output[outputOffset + 1] = source[sourceOffset + 1];
+            output[outputOffset + 2] = source[sourceOffset + 2];
+            output[outputOffset + 3] = source[sourceOffset + 3];
+        }
+    }
+    return { width, height, data: output };
+}
+export function resizeBox(image, width, height, alphaMode) {
+    assertDimension(width, "width");
+    assertDimension(height, "height");
+    assertPixelCount(width, height);
+    const output = new Uint8ClampedArray(width * height * 4);
+    const source = image.data;
+    for (let y = 0; y < height; y += 1) {
+        const sourceTop = (y * image.height) / height;
+        const sourceBottom = ((y + 1) * image.height) / height;
+        const firstY = Math.floor(sourceTop);
+        const lastY = Math.min(image.height - 1, Math.ceil(sourceBottom) - 1);
+        for (let x = 0; x < width; x += 1) {
+            const sourceLeft = (x * image.width) / width;
+            const sourceRight = ((x + 1) * image.width) / width;
+            const firstX = Math.floor(sourceLeft);
+            const lastX = Math.min(image.width - 1, Math.ceil(sourceRight) - 1);
+            let weightTotal = 0;
+            let red = 0;
+            let green = 0;
+            let blue = 0;
+            let alpha = 0;
+            for (let sourceY = firstY; sourceY <= lastY; sourceY += 1) {
+                const yWeight = Math.min(sourceBottom, sourceY + 1) - Math.max(sourceTop, sourceY);
+                if (yWeight <= 0)
+                    continue;
+                for (let sourceX = firstX; sourceX <= lastX; sourceX += 1) {
+                    const weight = yWeight * (Math.min(sourceRight, sourceX + 1) - Math.max(sourceLeft, sourceX));
+                    if (weight <= 0)
+                        continue;
+                    const sourceOffset = (sourceY * image.width + sourceX) * 4;
+                    const sourceAlpha = source[sourceOffset + 3];
+                    weightTotal += weight;
+                    alpha += sourceAlpha * weight;
+                    if (alphaMode === "premultiplied") {
+                        const alphaWeight = sourceAlpha / UINT8_MAX;
+                        red += source[sourceOffset] * alphaWeight * weight;
+                        green += source[sourceOffset + 1] * alphaWeight * weight;
+                        blue += source[sourceOffset + 2] * alphaWeight * weight;
+                    }
+                    else {
+                        red += source[sourceOffset] * weight;
+                        green += source[sourceOffset + 1] * weight;
+                        blue += source[sourceOffset + 2] * weight;
+                    }
+                }
+            }
+            const outputOffset = (y * width + x) * 4;
+            const averageAlpha = weightTotal === 0 ? 0 : alpha / weightTotal;
+            output[outputOffset + 3] = clampByte(averageAlpha);
+            if (alphaMode === "premultiplied") {
+                const alphaTotal = alpha / UINT8_MAX;
+                output[outputOffset] = clampByte(alphaTotal === 0 ? 0 : red / alphaTotal);
+                output[outputOffset + 1] = clampByte(alphaTotal === 0 ? 0 : green / alphaTotal);
+                output[outputOffset + 2] = clampByte(alphaTotal === 0 ? 0 : blue / alphaTotal);
+            }
+            else {
+                output[outputOffset] = clampByte(weightTotal === 0 ? 0 : red / weightTotal);
+                output[outputOffset + 1] = clampByte(weightTotal === 0 ? 0 : green / weightTotal);
+                output[outputOffset + 2] = clampByte(weightTotal === 0 ? 0 : blue / weightTotal);
+            }
+        }
+    }
+    return { width, height, data: output };
+}

package/dist/sampling.d.ts

@@ -0,0 +1,7 @@
+import type { PixelBuffer } from "./base.ts";
+import { PixelationMethod } from "./types.ts";
+/** RGB is taken from the winning region. Conversion keeps area alpha; recovery keeps the chosen region’s original alpha. */
+export declare function samplePixelation(image: PixelBuffer, width: number, height: number, method: PixelationMethod, cuts?: {
+    x: readonly number[];
+    y: readonly number[];
+}): PixelBuffer;

package/dist/sampling.js

@@ -0,0 +1,301 @@
+import { UINT8_MAX } from "./base.js";
+import { assertDimension, assertPixelCount, clampByte } from "./base.js";
+import { extractPixelationPalette, reduceToPixelationLabels, } from "./palette.js";
+import { paletteCoordinates } from "./quantization.js";
+import { PixelationMethod } from "./types.js";
+const CHANNELS = 4;
+const COLOR_CHANNELS = 3;
+const CLUSTERS = 2;
+const ITERATIONS = 6;
+const CENTER_FLOOR = 0.25;
+const STRUCTURE_COLORS = 48;
+const TWO_STAGE_MIN_COLORS = 16;
+const TWO_STAGE_MAX_COLORS = 48;
+const TWO_STAGE_COLOR_BINS = 16 ** COLOR_CHANNELS;
+const CONVERGENCE = 1e-7;
+const MAX_COORDINATE_COLORS = 65_536;
+function cell(image, left, top, right, bottom, recovery) {
+    left = Math.max(0, left);
+    top = Math.max(0, top);
+    right = Math.min(image.width, right);
+    bottom = Math.min(image.height, bottom);
+    const samples = [];
+    let area = 0, alphaSum = 0;
+    for (let y = Math.floor(top); y < Math.ceil(bottom); y++)
+        for (let x = Math.floor(left); x < Math.ceil(right); x++) {
+            const coverage = (Math.min(right, x + 1) - Math.max(left, x)) * (Math.min(bottom, y + 1) - Math.max(top, y));
+            if (coverage <= 0)
+                continue;
+            const index = y * image.width + x;
+            const alpha = image.data[index * CHANNELS + COLOR_CHANNELS];
+            area += coverage;
+            alphaSum += coverage * alpha;
+            if (!alpha && !recovery)
+                continue;
+            const fx = (Math.max(left, x) + Math.min(right, x + 1)) / 2;
+            const fy = (Math.max(top, y) + Math.min(bottom, y + 1)) / 2;
+            const horizontal = 1 - Math.abs((2 * (fx - left)) / (right - left) - 1);
+            const vertical = 1 - Math.abs((2 * (fy - top)) / (bottom - top) - 1);
+            const weight = coverage * (CENTER_FLOOR + (1 - CENTER_FLOOR) * horizontal * vertical);
+            samples.push({
+                index,
+                weight,
+                visibleWeight: (weight * alpha) / UINT8_MAX,
+                voteWeight: recovery ? weight : (weight * alpha) / UINT8_MAX,
+            });
+        }
+    return { samples, alpha: area ? clampByte(alphaSum / area) : 0 };
+}
+/**
+ * Compute adaptive K for TwoStage method (Fixer-aligned).
+ * Counts 4-bit RGB bins (R/16, G/16, B/16) with share ≥ 0.003 of opaque pixels.
+ * Clamps to [TWO_STAGE_MIN_COLORS, TWO_STAGE_MAX_COLORS].
+ */
+function adaptiveTwoStageK(image) {
+    const bins = new Uint32Array(TWO_STAGE_COLOR_BINS);
+    let opaqueCount = 0;
+    for (let i = 0; i < image.data.length; i += CHANNELS) {
+        const alpha = image.data[i + COLOR_CHANNELS];
+        if (alpha === 0)
+            continue;
+        opaqueCount++;
+        // 4-bit RGB: divide each channel by 16
+        const r4 = image.data[i] >> 4;
+        const g4 = image.data[i + 1] >> 4;
+        const b4 = image.data[i + 2] >> 4;
+        const key = (r4 << 8) | (g4 << 4) | b4;
+        bins[key] += 1;
+    }
+    if (opaqueCount === 0)
+        return TWO_STAGE_MIN_COLORS;
+    const threshold = opaqueCount * 0.003;
+    let count = 0;
+    for (const binCount of bins) {
+        if (binCount >= threshold)
+            count++;
+    }
+    return Math.max(TWO_STAGE_MIN_COLORS, Math.min(TWO_STAGE_MAX_COLORS, count));
+}
+function coordinateLookup(image, axes) {
+    const cache = new Map();
+    return (sample, local) => {
+        const offset = sample.index * CHANNELS;
+        const alpha = axes === CHANNELS ? image.data[offset + COLOR_CHANNELS] : UINT8_MAX;
+        const key = alpha
+            ? (image.data[offset] << 24) |
+                (image.data[offset + 1] << 16) |
+                (image.data[offset + 2] << 8) |
+                alpha
+            : 0;
+        const cached = cache.get(key) ?? local.get(key);
+        if (cached)
+            return cached;
+        const value = paletteCoordinates([
+            image.data[offset],
+            image.data[offset + 1],
+            image.data[offset + 2],
+            alpha,
+        ]);
+        if (cache.size < MAX_COORDINATE_COLORS)
+            cache.set(key, value);
+        else
+            local.set(key, value);
+        return value;
+    };
+}
+function distance(sample, center) {
+    let sum = 0;
+    for (let axis = 0; axis < center.length; axis++)
+        sum += (sample.point[axis] - center[axis]) ** 2;
+    return sum;
+}
+function dominant(samples, axes) {
+    if (samples.length < CLUSTERS)
+        return samples;
+    const mean = Array.from({ length: axes }, () => 0);
+    let total = 0;
+    for (const sample of samples) {
+        total += sample.voteWeight;
+        for (let c = 0; c < axes; c++)
+            mean[c] += sample.point[c] * sample.voteWeight;
+    }
+    for (let c = 0; c < axes; c++)
+        mean[c] /= total;
+    const farthest = (center) => samples.reduce((best, point) => distance(point, center) > distance(best, center) ? point : best);
+    const first = farthest(mean);
+    const center = (sample) => sample.point.slice(0, axes);
+    const centers = [center(first), center(farthest(center(first)))];
+    let groups = [[], []];
+    for (let iteration = 0; iteration < ITERATIONS; iteration++) {
+        groups = [[], []];
+        for (const sample of samples)
+            groups[distance(sample, centers[0]) <= distance(sample, centers[1]) ? 0 : 1].push(sample);
+        let movement = 0;
+        for (let cluster = 0; cluster < CLUSTERS; cluster++) {
+            const values = Array.from({ length: axes }, () => 0);
+            let weight = 0;
+            for (const sample of groups[cluster]) {
+                weight += sample.voteWeight;
+                for (let c = 0; c < axes; c++)
+                    values[c] += sample.point[c] * sample.voteWeight;
+            }
+            if (!weight)
+                continue;
+            for (let c = 0; c < axes; c++) {
+                values[c] /= weight;
+                movement += (values[c] - centers[cluster][c]) ** 2;
+            }
+            centers[cluster] = values;
+        }
+        if (movement <= CONVERGENCE)
+            break;
+    }
+    const weight = (group) => group.reduce((sum, sample) => sum + sample.voteWeight, 0);
+    return weight(groups[0]) >= weight(groups[1]) ? groups[0] : groups[1];
+}
+/** Reuse one bounded set of statistics for every cell, in the original sample order. */
+function labelSampler(image, labels, recovery, triangular) {
+    const groups = labels.keys.length;
+    const touched = new Uint8Array(groups);
+    const active = new Uint16Array(groups);
+    let activeCount = 0;
+    const weights = new Float64Array(groups);
+    const alphaSums = new Float64Array(groups);
+    const visibleWeights = new Float64Array(groups);
+    const redSums = new Float64Array(groups);
+    const greenSums = new Float64Array(groups);
+    const blueSums = new Float64Array(groups);
+    return (left, top, right, bottom, output, outputOffset) => {
+        for (let index = 0; index < activeCount; index++) {
+            const group = active[index];
+            touched[group] = 0;
+            weights[group] = 0;
+            alphaSums[group] = 0;
+            visibleWeights[group] = 0;
+            redSums[group] = 0;
+            greenSums[group] = 0;
+            blueSums[group] = 0;
+        }
+        activeCount = 0;
+        left = Math.max(0, left);
+        top = Math.max(0, top);
+        right = Math.min(image.width, right);
+        bottom = Math.min(image.height, bottom);
+        let area = 0, alphaSum = 0;
+        for (let y = Math.floor(top); y < Math.ceil(bottom); y++)
+            for (let x = Math.floor(left); x < Math.ceil(right); x++) {
+                const coverage = (Math.min(right, x + 1) - Math.max(left, x)) *
+                    (Math.min(bottom, y + 1) - Math.max(top, y));
+                if (coverage <= 0)
+                    continue;
+                const index = y * image.width + x;
+                const offset = index * CHANNELS;
+                const alpha = image.data[offset + COLOR_CHANNELS];
+                area += coverage;
+                alphaSum += coverage * alpha;
+                if (!alpha && !recovery)
+                    continue;
+                const fx = (Math.max(left, x) + Math.min(right, x + 1)) / 2;
+                const fy = (Math.max(top, y) + Math.min(bottom, y + 1)) / 2;
+                const horizontal = 1 - Math.abs((2 * (fx - left)) / (right - left) - 1);
+                const vertical = 1 - Math.abs((2 * (fy - top)) / (bottom - top) - 1);
+                const weight = triangular
+                    ? coverage * horizontal * vertical
+                    : coverage * (CENTER_FLOOR + (1 - CENTER_FLOOR) * horizontal * vertical);
+                const visibleWeight = (weight * alpha) / UINT8_MAX;
+                // Label zero also contains opaque black, matching the original RGB grouping.
+                const group = labels.data[index];
+                if (!touched[group]) {
+                    touched[group] = 1;
+                    active[activeCount++] = group;
+                }
+                weights[group] += weight;
+                alphaSums[group] += weight * alpha;
+                visibleWeights[group] += visibleWeight;
+                redSums[group] += image.data[offset] * visibleWeight;
+                greenSums[group] += image.data[offset + 1] * visibleWeight;
+                blueSums[group] += image.data[offset + 2] * visibleWeight;
+            }
+        const alpha = area ? clampByte(alphaSum / area) : 0;
+        output[outputOffset + COLOR_CHANNELS] = alpha;
+        if (!alpha)
+            return;
+        let winner = -1, vote = -1;
+        for (let index = 0; index < activeCount; index++) {
+            const group = active[index];
+            if (visibleWeights[group] > vote ||
+                (visibleWeights[group] === vote && labels.keys[group] < labels.keys[winner])) {
+                winner = group;
+                vote = visibleWeights[group];
+            }
+        }
+        if (winner < 0)
+            return;
+        if (recovery)
+            output[outputOffset + COLOR_CHANNELS] = clampByte(weights[winner] ? alphaSums[winner] / weights[winner] : 0);
+        const visible = visibleWeights[winner];
+        output[outputOffset] = clampByte(visible ? redSums[winner] / visible : 0);
+        output[outputOffset + 1] = clampByte(visible ? greenSums[winner] / visible : 0);
+        output[outputOffset + 2] = clampByte(visible ? blueSums[winner] / visible : 0);
+    };
+}
+/** RGB is taken from the winning region. Conversion keeps area alpha; recovery keeps the chosen region’s original alpha. */
+export function samplePixelation(image, width, height, method, cuts) {
+    assertDimension(width, "width");
+    assertDimension(height, "height");
+    assertPixelCount(width, height);
+    const recovery = cuts !== undefined;
+    const axes = recovery ? CHANNELS : COLOR_CHANNELS;
+    const points = method === PixelationMethod.Dominant ? coordinateLookup(image, axes) : undefined;
+    const useStructure = method === PixelationMethod.Structure;
+    const useTwoStage = method === PixelationMethod.TwoStage;
+    const palette = useStructure
+        ? extractPixelationPalette(image, {
+            maxColors: STRUCTURE_COLORS,
+        }).map((entry) => entry.color)
+        : useTwoStage
+            ? extractPixelationPalette(image, {
+                maxColors: adaptiveTwoStageK(image),
+            }).map((entry) => entry.color)
+            : undefined;
+    const labels = palette ? reduceToPixelationLabels(image, palette) : undefined;
+    const data = new Uint8ClampedArray(width * height * CHANNELS);
+    const sampleLabel = labels ? labelSampler(image, labels, recovery, useTwoStage) : undefined;
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            const left = cuts?.x[x] ?? (x * image.width) / width;
+            const top = cuts?.y[y] ?? (y * image.height) / height;
+            const right = cuts?.x[x + 1] ?? ((x + 1) * image.width) / width;
+            const bottom = cuts?.y[y + 1] ?? ((y + 1) * image.height) / height;
+            const offset = (y * width + x) * CHANNELS;
+            if (sampleLabel) {
+                sampleLabel(left, top, right, bottom, data, offset);
+                continue;
+            }
+            const current = cell(image, left, top, right, bottom, recovery);
+            data[offset + COLOR_CHANNELS] = current.alpha;
+            if (!current.alpha || !current.samples.length)
+                continue;
+            if (points) {
+                const local = new Map();
+                for (const sample of current.samples)
+                    sample.point = points(sample, local);
+            }
+            const selected = points ? dominant(current.samples, axes) : current.samples;
+            if (recovery) {
+                const area = selected.reduce((sum, sample) => sum + sample.weight, 0);
+                const alpha = selected.reduce((sum, sample) => sum + sample.weight * image.data[sample.index * CHANNELS + COLOR_CHANNELS], 0);
+                data[offset + COLOR_CHANNELS] = clampByte(area ? alpha / area : 0);
+            }
+            const sums = [0, 0, 0];
+            let weight = 0;
+            for (const sample of selected) {
+                weight += sample.visibleWeight;
+                for (let c = 0; c < COLOR_CHANNELS; c++)
+                    sums[c] += image.data[sample.index * CHANNELS + c] * sample.visibleWeight;
+            }
+            for (let c = 0; c < COLOR_CHANNELS; c++)
+                data[offset + c] = clampByte(weight ? sums[c] / weight : 0);
+        }
+    return { width, height, data };
+}