@funpixel/tools 0.0.0-stage → 0.1.0

package/dist/commands/parts.js

@@ -0,0 +1,635 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { encodePng } from "../look/png.js";
+import { crop, trim } from "../look/sheet.js";
+import { decodeImageFile, encodeWebp } from "../look/image-io.js";
+import { EXIT } from "./verify.js";
+import { ui } from "../ui.js";
+export const PARTS_DEFAULTS = { pad: 2, merge: 6, tolerance: 40, minShare: 0.002, solid: 128 };
+export function haloShare(img, solid = PARTS_DEFAULTS.solid) {
+    let faint = 0, visible = 0;
+    for (let i = 3; i < img.data.length; i += 4) {
+        const a = img.data[i];
+        if (a > 8) {
+            visible++;
+            if (a < solid)
+                faint++;
+        }
+    }
+    return visible ? faint / visible : 0;
+}
+export function parseGrid(s) {
+    const m = /^(\d{1,3})x(\d{1,3})$/i.exec(s.trim());
+    if (!m)
+        return null;
+    const cols = Number(m[1]), rows = Number(m[2]);
+    return cols >= 1 && rows >= 1 ? { cols, rows } : null;
+}
+export function parseKey(s) {
+    if (s === 'auto' || s === 'none' || s === 'paper')
+        return { kind: s };
+    const m = /^#?([0-9a-f]{6})$/i.exec(s);
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return { kind: 'colour', rgb: [(n >> 16) & 255, (n >> 8) & 255, n & 255] };
+}
+const dist = (d, o, c) => Math.max(Math.abs(d[o] - c[0]), Math.abs(d[o + 1] - c[1]), Math.abs(d[o + 2] - c[2]));
+export function hasAlpha(img) {
+    const { width: w, height: h, data } = img;
+    const corners = [0, w - 1, (h - 1) * w, h * w - 1];
+    if (corners.some((i) => data[i * 4 + 3] < 250))
+        return true;
+    let clear = 0;
+    for (let i = 3; i < data.length; i += 4)
+        if (data[i] < 250)
+            clear++;
+    return clear / (w * h) > 0.01;
+}
+export function cornerGround(img) {
+    const { width: w, height: h, data } = img;
+    const cs = [0, w - 1, (h - 1) * w, h * w - 1].map((i) => [data[i * 4], data[i * 4 + 1], data[i * 4 + 2]]);
+    const med = (k) => { const v = cs.map((c) => c[k]).sort((a, b) => a - b); return Math.round((v[1] + v[2]) / 2); };
+    const rgb = [med(0), med(1), med(2)];
+    return { rgb, agree: cs.every((c) => Math.max(Math.abs(c[0] - rgb[0]), Math.abs(c[1] - rgb[1]), Math.abs(c[2] - rgb[2])) <= PARTS_DEFAULTS.tolerance) };
+}
+export function keyGround(img, rgb, tolerance = PARTS_DEFAULTS.tolerance) {
+    const { width: w, height: h } = img;
+    const data = new Uint8Array(img.data);
+    const seen = new Uint8Array(w * h);
+    const stack = [];
+    const push = (i) => { if (!seen[i] && dist(data, i * 4, rgb) <= tolerance * 1.5) {
+        seen[i] = 1;
+        stack.push(i);
+    } };
+    for (let x = 0; x < w; x++) {
+        push(x);
+        push((h - 1) * w + x);
+    }
+    for (let y = 0; y < h; y++) {
+        push(y * w);
+        push(y * w + w - 1);
+    }
+    while (stack.length) {
+        const i = stack.pop();
+        const d = dist(data, i * 4, rgb);
+        data[i * 4 + 3] = d <= tolerance ? 0 : Math.round(data[i * 4 + 3] * (d - tolerance) / (tolerance * 0.5));
+        const x = i % w, y = (i - x) / w;
+        if (x > 0)
+            push(i - 1);
+        if (x < w - 1)
+            push(i + 1);
+        if (y > 0)
+            push(i - w);
+        if (y < h - 1)
+            push(i + w);
+    }
+    return { width: w, height: h, data };
+}
+export function paperGround(img, band = 6) {
+    const { width: w, height: h, data } = img;
+    const samples = [];
+    const at = (x, y) => { const o = (y * w + x) * 4; samples.push([data[o], data[o + 1], data[o + 2]]); };
+    const b = Math.max(1, Math.min(band, Math.floor(Math.min(w, h) / 4)));
+    const step = Math.max(1, Math.floor((w + h) / 800));
+    for (let x = 0; x < w; x += step)
+        for (let y = 0; y < b; y++) {
+            at(x, y);
+            at(x, h - 1 - y);
+        }
+    for (let y = b; y < h - b; y += step)
+        for (let x = 0; x < b; x++) {
+            at(x, y);
+            at(w - 1 - x, y);
+        }
+    const med = (k) => { const v = samples.map((c) => c[k]).sort((p, q) => p - q); return v[Math.floor(v.length / 2)]; };
+    const rgb = [med(0), med(1), med(2)];
+    const d = samples.map((c) => dist(Uint8Array.from(c), 0, rgb)).sort((p, q) => p - q);
+    const spread = d[Math.floor(d.length * 0.8)] ?? 0;
+    return { rgb, spread, tolerance: Math.max(14, Math.min(48, Math.round(spread * 3 + 12))) };
+}
+export function keyEnclosedPaper(img, rgb, tolerance, flat, minPx = 48) {
+    const { width: w, height: h } = img;
+    const data = new Uint8Array(img.data);
+    const seen = new Uint8Array(w * h);
+    const paper = (i) => data[i * 4 + 3] > 0 && dist(data, i * 4, rgb) <= tolerance;
+    for (let s = 0; s < w * h; s++) {
+        if (seen[s] || !paper(s))
+            continue;
+        const region = [], stack = [s];
+        seen[s] = 1;
+        while (stack.length) {
+            const i = stack.pop();
+            region.push(i);
+            const x = i % w, y = (i - x) / w;
+            for (const j of [x > 0 ? i - 1 : -1, x < w - 1 ? i + 1 : -1, y > 0 ? i - w : -1, y < h - 1 ? i + w : -1]) {
+                if (j >= 0 && !seen[j] && paper(j)) {
+                    seen[j] = 1;
+                    stack.push(j);
+                }
+            }
+        }
+        if (region.length < minPx)
+            continue;
+        const ds = region.map((i) => dist(data, i * 4, rgb)).sort((p, q) => p - q);
+        if (ds[Math.floor(ds.length / 2)] > flat)
+            continue;
+        for (const i of region)
+            data[i * 4 + 3] = 0;
+    }
+    return { width: w, height: h, data };
+}
+export function keyed(img, key) {
+    if (key.kind === 'none')
+        return { img, keyed: 'none (alpha as drawn)' };
+    if (key.kind === 'paper') {
+        if (hasAlpha(img))
+            return { img, keyed: 'the sheet\'s own alpha' };
+        const p = paperGround(img);
+        const hex = `#${p.rgb.map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+        const blotchy = p.spread > 12;
+        return {
+            img: keyEnclosedPaper(keyGround(img, p.rgb, p.tolerance), p.rgb, p.tolerance, Math.max(5, Math.round(p.spread * 2 + 3))), keyed: `paper ${hex} (tolerance ${p.tolerance})`, ground: { rgb: p.rgb, tolerance: p.tolerance },
+            ...(blotchy ? { warning: `the paper varies a lot round the border (${Math.round(p.spread)} levels): a painted backdrop will not key cleanly; check every piece` } : {}),
+        };
+    }
+    if (key.kind === 'colour')
+        return { img: keyGround(img, key.rgb), keyed: `#${key.rgb.map((c) => c.toString(16).padStart(2, '0')).join('')}` };
+    if (hasAlpha(img))
+        return { img, keyed: 'the sheet\'s own alpha' };
+    const g = cornerGround(img);
+    const hex = `#${g.rgb.map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+    return {
+        img: keyGround(img, g.rgb),
+        keyed: `flat ground ${hex}`,
+        ...(g.agree ? {} : { warning: `the corners disagree on the background (keyed ${hex}): a gradient or scene behind the figures will not key cleanly; ask for a flat or transparent background, or pass --key #rrggbb` }),
+    };
+}
+export function findPieces(img, merge = PARTS_DEFAULTS.merge, minShare = PARTS_DEFAULTS.minShare, solid = PARTS_DEFAULTS.solid) {
+    return segment(img, merge, minShare, solid).boxes;
+}
+export function segment(img, merge = PARTS_DEFAULTS.merge, minShare = PARTS_DEFAULTS.minShare, solid = PARTS_DEFAULTS.solid) {
+    const { width: w, height: h, data } = img;
+    const label = new Int32Array(w * h).fill(-1);
+    let boxes = [];
+    const stack = [];
+    for (let s = 0; s < w * h; s++) {
+        if (label[s] !== -1 || data[s * 4 + 3] < solid)
+            continue;
+        const id = boxes.length, b = { x0: w, y0: h, x1: -1, y1: -1, n: 0, ids: [id] };
+        boxes.push(b);
+        label[s] = id;
+        stack.push(s);
+        while (stack.length) {
+            const i = stack.pop(), x = i % w, y = (i - x) / w;
+            b.n++;
+            if (x < b.x0)
+                b.x0 = x;
+            if (x > b.x1)
+                b.x1 = x;
+            if (y < b.y0)
+                b.y0 = y;
+            if (y > b.y1)
+                b.y1 = y;
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dx = -1; dx <= 1; dx++) {
+                    const nx = x + dx, ny = y + dy;
+                    if (nx < 0 || ny < 0 || nx >= w || ny >= h)
+                        continue;
+                    const j = ny * w + nx;
+                    if (label[j] === -1 && data[j * 4 + 3] >= solid) {
+                        label[j] = id;
+                        stack.push(j);
+                    }
+                }
+        }
+    }
+    let front = [];
+    for (let i = 0; i < w * h; i++)
+        if (label[i] !== -1)
+            front.push(i);
+    for (let step = 0; step < 4 && front.length; step++) {
+        const next = [];
+        for (const i of front) {
+            const x = i % w, y = (i - x) / w;
+            for (const j of [x > 0 ? i - 1 : -1, x < w - 1 ? i + 1 : -1, y > 0 ? i - w : -1, y < h - 1 ? i + w : -1]) {
+                if (j >= 0 && label[j] === -1 && data[j * 4 + 3] > 0) {
+                    label[j] = label[i];
+                    next.push(j);
+                }
+            }
+        }
+        front = next;
+    }
+    boxes = boxes.filter((b) => b.n >= 4);
+    for (let changed = true; changed;) {
+        changed = false;
+        for (let a = 0; a < boxes.length && !changed; a++)
+            for (let c = a + 1; c < boxes.length; c++) {
+                const A = boxes[a], C = boxes[c];
+                if (A.x0 - merge > C.x1 || C.x0 - merge > A.x1 || A.y0 - merge > C.y1 || C.y0 - merge > A.y1)
+                    continue;
+                if (Math.min(A.n, C.n) > 0.25 * Math.max(A.n, C.n))
+                    continue;
+                boxes[a] = { x0: Math.min(A.x0, C.x0), y0: Math.min(A.y0, C.y0), x1: Math.max(A.x1, C.x1), y1: Math.max(A.y1, C.y1), n: A.n + C.n, ids: [...A.ids, ...C.ids] };
+                boxes.splice(c, 1);
+                changed = true;
+                break;
+            }
+    }
+    const biggest = Math.max(0, ...boxes.map((b) => b.n));
+    boxes = boxes.filter((b) => b.n >= Math.max(16, biggest * minShare));
+    boxes.sort((p, q) => p.y0 - q.y0);
+    const rows = [];
+    for (const b of boxes) {
+        const row = rows.find((r) => r.some((o) => Math.min(o.y1, b.y1) - Math.max(o.y0, b.y0) > 0.5 * Math.min(o.y1 - o.y0, b.y1 - b.y0)));
+        if (row)
+            row.push(b);
+        else
+            rows.push([b]);
+    }
+    const ordered = rows.flatMap((r) => r.sort((p, q) => p.x0 - q.x0));
+    return { boxes: ordered.map((b) => ({ x: b.x0, y: b.y0, w: b.x1 - b.x0 + 1, h: b.y1 - b.y0 + 1 })), label, owns: ordered.map((b) => b.ids) };
+}
+export function gridBoxes(width, height, cols, rows) {
+    const out = [];
+    for (let r = 0; r < rows; r++)
+        for (let c = 0; c < cols; c++) {
+            const x = Math.round((c * width) / cols), y = Math.round((r * height) / rows);
+            out.push({ x, y, w: Math.round(((c + 1) * width) / cols) - x, h: Math.round(((r + 1) * height) / rows) - y });
+        }
+    return out;
+}
+export function padded(img, pad) {
+    if (pad <= 0)
+        return img;
+    const width = img.width + 2 * pad, height = img.height + 2 * pad, data = new Uint8Array(width * height * 4);
+    for (let y = 0; y < img.height; y++)
+        data.set(img.data.subarray(y * img.width * 4, (y + 1) * img.width * 4), ((y + pad) * width + pad) * 4);
+    return { width, height, data };
+}
+export function pivotOf(width, height, pivot) {
+    return { x: Math.round(width / 2), y: pivot === 'bottom' ? height : pivot === 'top' ? 0 : Math.round(height / 2) };
+}
+export function dropRuledLines(img, share = 0.5, solid = PARTS_DEFAULTS.solid) {
+    const { width: w, height: h } = img;
+    const data = new Uint8Array(img.data);
+    const on = (x, y) => x >= 0 && y >= 0 && x < w && y < h && img.data[(y * w + x) * 4 + 3] >= solid;
+    const thinH = (x, y) => on(x, y) && !on(x, y - 2) && !on(x, y + 2) && (!on(x, y - 1) || !on(x, y + 1));
+    const thinV = (x, y) => on(x, y) && !on(x - 2, y) && !on(x + 2, y) && (!on(x - 1, y) || !on(x + 1, y));
+    let lines = 0, px = 0;
+    const clear = (x, y) => { const o = (y * w + x) * 4 + 3; if (data[o]) {
+        data[o] = 0;
+        px++;
+    } };
+    for (let y = 0; y < h; y++) {
+        let n = 0;
+        for (let x = 0; x < w; x++)
+            if (thinH(x, y))
+                n++;
+        if (n >= w * share) {
+            lines++;
+            for (let x = 0; x < w; x++)
+                if (thinH(x, y))
+                    clear(x, y);
+        }
+    }
+    for (let x = 0; x < w; x++) {
+        let n = 0;
+        for (let y = 0; y < h; y++)
+            if (thinV(x, y))
+                n++;
+        if (n >= h * share) {
+            lines++;
+            for (let y = 0; y < h; y++)
+                if (thinV(x, y))
+                    clear(x, y);
+        }
+    }
+    return { img: { width: w, height: h, data }, lines, px };
+}
+export const CLEAN = {
+    solid: 128,
+    island: 0.08,
+    band: 0.15,
+    lum: [0.42, 0.97], chroma: 0.075,
+    grain: 26,
+};
+export function cleanPiece(src, opts = {}) {
+    const { width: w, height: h } = src;
+    const data = new Uint8Array(src.data);
+    const removed = { halo: 0, shadow: 0, islands: 0, island_px: 0, defringed: 0 };
+    const A = (i) => data[i * 4 + 3];
+    let y0 = h, y1 = -1;
+    for (let i = 0; i < w * h; i++)
+        if (A(i) > 8) {
+            const y = Math.floor(i / w);
+            if (y < y0)
+                y0 = y;
+            if (y > y1)
+                y1 = y;
+        }
+    if (y1 < 0)
+        return { img: { width: w, height: h, data }, removed };
+    const g = opts.ground;
+    if (g && !opts.keepShadows) {
+        const gs = g.rgb[0] + g.rgb[1] + g.rgb[2] || 1;
+        const gc = [g.rgb[0] / gs, g.rgb[1] / gs, g.rgb[2] / gs];
+        const bandTop = Math.floor(y1 - (y1 - y0) * CLEAN.band);
+        const like = (i) => {
+            if (A(i) <= 8)
+                return false;
+            const o = i * 4, s = data[o] + data[o + 1] + data[o + 2];
+            if (!s)
+                return false;
+            const lum = s / gs;
+            if (lum < CLEAN.lum[0] || lum > CLEAN.lum[1])
+                return false;
+            return Math.max(Math.abs(data[o] / s - gc[0]), Math.abs(data[o + 1] / s - gc[1]), Math.abs(data[o + 2] / s - gc[2])) <= CLEAN.chroma;
+        };
+        const step = (i, j) => dist(data, i * 4, [data[j * 4], data[j * 4 + 1], data[j * 4 + 2]]) <= CLEAN.grain;
+        const under = new Uint8Array(w * h);
+        for (let x = 0; x < w; x++) {
+            let fig = 0, run = 0;
+            for (let y = h - 1; y >= Math.max(0, bandTop); y--) {
+                const i = y * w + x;
+                run = A(i) > 8 && !like(i) ? run + 1 : 0;
+                if (run >= 3)
+                    fig = 1;
+                under[i] = fig;
+            }
+        }
+        const shadowAt = (i) => like(i) && !under[i];
+        const seen = new Uint8Array(w * h), stack = [];
+        for (let y = Math.max(0, bandTop); y < h; y++)
+            for (let x = 0; x < w; x++) {
+                const i = y * w + x;
+                if (!shadowAt(i))
+                    continue;
+                const edge = x === 0 || x === w - 1 || y === h - 1 || A(i - 1) <= 8 || A(i + 1) <= 8 || (y + 1 < h && A(i + w) <= 8) || (y > 0 && A(i - w) <= 8);
+                if (edge) {
+                    seen[i] = 1;
+                    stack.push(i);
+                }
+            }
+        const hit = [];
+        while (stack.length) {
+            const i = stack.pop();
+            hit.push(i);
+            const x = i % w, y = (i - x) / w;
+            for (const j of [x > 0 ? i - 1 : -1, x < w - 1 ? i + 1 : -1, y > bandTop ? i - w : -1, y < h - 1 ? i + w : -1]) {
+                if (j >= 0 && !seen[j] && shadowAt(j) && step(i, j)) {
+                    seen[j] = 1;
+                    stack.push(j);
+                }
+            }
+        }
+        for (const i of hit)
+            data[i * 4 + 3] = 0;
+        removed.shadow = hit.length;
+    }
+    for (let i = 0; i < w * h; i++) {
+        const a = A(i);
+        if (a === 0)
+            continue;
+        if (a < CLEAN.solid) {
+            data[i * 4 + 3] = 0;
+            removed.halo++;
+        }
+        else
+            data[i * 4 + 3] = 255;
+    }
+    const label = new Int32Array(w * h).fill(-1), sizes = [];
+    for (let s = 0; s < w * h; s++) {
+        if (label[s] !== -1 || !A(s))
+            continue;
+        const id = sizes.length;
+        let n = 0;
+        const stack = [s];
+        label[s] = id;
+        while (stack.length) {
+            const i = stack.pop();
+            n++;
+            const x = i % w, y = (i - x) / w;
+            for (let dy = -1; dy <= 1; dy++)
+                for (let dx = -1; dx <= 1; dx++) {
+                    const nx = x + dx, ny = y + dy;
+                    if (nx < 0 || ny < 0 || nx >= w || ny >= h)
+                        continue;
+                    const j = ny * w + nx;
+                    if (label[j] === -1 && A(j)) {
+                        label[j] = id;
+                        stack.push(j);
+                    }
+                }
+        }
+        sizes.push(n);
+    }
+    const big = Math.max(0, ...sizes);
+    const drop = sizes.map((n) => n < big * CLEAN.island);
+    removed.islands = drop.filter(Boolean).length;
+    for (let i = 0; i < w * h; i++)
+        if (label[i] !== -1 && drop[label[i]]) {
+            data[i * 4 + 3] = 0;
+            removed.island_px++;
+        }
+    const solid = (x, y) => x >= 0 && y >= 0 && x < w && y < h && data[(y * w + x) * 4 + 3] === 255;
+    const rim = [];
+    for (let y = 0; y < h; y++)
+        for (let x = 0; x < w; x++) {
+            if (!solid(x, y))
+                continue;
+            if (!solid(x - 1, y) || !solid(x + 1, y) || !solid(x, y - 1) || !solid(x, y + 1))
+                rim.push(y * w + x);
+        }
+    const isRim = new Uint8Array(w * h);
+    for (const i of rim)
+        isRim[i] = 1;
+    const out = new Uint8Array(data);
+    for (const i of rim) {
+        const x = i % w, y = (i - x) / w;
+        let r = 0, gg = 0, b = 0, n = 0, around = 0;
+        for (let dy = -2; dy <= 2; dy++)
+            for (let dx = -2; dx <= 2; dx++) {
+                const nx = x + dx, ny = y + dy;
+                if (!solid(nx, ny))
+                    continue;
+                const j = ny * w + nx;
+                if (Math.abs(dx) <= 1 && Math.abs(dy) <= 1)
+                    around++;
+                if (isRim[j])
+                    continue;
+                r += data[j * 4];
+                gg += data[j * 4 + 1];
+                b += data[j * 4 + 2];
+                n++;
+            }
+        if (n) {
+            out[i * 4] = Math.round(r / n);
+            out[i * 4 + 1] = Math.round(gg / n);
+            out[i * 4 + 2] = Math.round(b / n);
+            removed.defringed++;
+        }
+        out[i * 4 + 3] = Math.max(CLEAN.solid, Math.round((255 * around) / 9));
+    }
+    return { img: { width: w, height: h, data: out }, removed };
+}
+const slug = (s) => s.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'part';
+export function cutPieces(sheet, boxes, names, pad, pivot, seg, clean) {
+    const pieces = [], empty = [];
+    const used = new Set();
+    boxes.forEach((b, i) => {
+        let name = slug(names[i] ?? b.name ?? `part-${String(i + 1).padStart(2, '0')}`);
+        for (let n = 2; used.has(name); n++)
+            name = `${slug(names[i] ?? b.name ?? 'part')}-${n}`;
+        used.add(name);
+        let cell = crop(sheet, b.x, b.y, b.w, b.h);
+        if (seg) {
+            const own = new Set(seg.owns[i]);
+            for (let y = 0; y < cell.height; y++)
+                for (let x = 0; x < cell.width; x++) {
+                    const l = seg.label[(b.y + y) * sheet.width + b.x + x];
+                    if (l !== -1 && !own.has(l))
+                        cell.data[(y * cell.width + x) * 4 + 3] = 0;
+                }
+        }
+        let removed;
+        if (clean)
+            ({ img: cell, removed } = cleanPiece(cell, clean));
+        const trimmed = trim(cell);
+        if (!trimmed) {
+            empty.push(name);
+            return;
+        }
+        for (let o = 0; o < trimmed.data.length; o += 4)
+            if (trimmed.data[o + 3] === 0)
+                trimmed.data.fill(0, o, o + 3);
+        let ox = cell.width, oy = cell.height;
+        for (let y = 0; y < cell.height; y++)
+            for (let x = 0; x < cell.width; x++)
+                if (cell.data[(y * cell.width + x) * 4 + 3] > 8) {
+                    if (x < ox)
+                        ox = x;
+                    if (y < oy)
+                        oy = y;
+                }
+        const img = padded(trimmed, pad);
+        const box = { x: b.x + ox, y: b.y + oy, w: trimmed.width, h: trimmed.height };
+        pieces.push({
+            img,
+            part: {
+                name, box, size: { w: img.width, h: img.height }, pivot: pivotOf(img.width, img.height, pivot),
+                touches_edge: box.x <= 0 || box.y <= 0 || box.x + box.w >= sheet.width || box.y + box.h >= sheet.height,
+                ...(removed ? { removed } : {}),
+            },
+        });
+    });
+    return { pieces, empty };
+}
+async function readBoxes(path) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (e) {
+        return `${path}: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    const list = Array.isArray(raw) ? raw : raw?.boxes ?? raw?.parts;
+    if (!Array.isArray(list))
+        return `${path}: expected [{ "name": "head", "x": 0, "y": 0, "w": 64, "h": 64 }, …]`;
+    const out = [];
+    for (const b of list) {
+        const box = b?.box ?? b;
+        const [x, y, w, h] = [box?.x, box?.y, box?.w ?? box?.width, box?.h ?? box?.height].map(Number);
+        if (![x, y, w, h].every(Number.isFinite) || w <= 0 || h <= 0)
+            return `${path}: every box needs numbers x, y, w, h`;
+        out.push({ x, y, w, h, ...(typeof b?.name === 'string' ? { name: b.name } : {}) });
+    }
+    return out;
+}
+export async function parts(opts, io = console) {
+    const u = ui(io, opts.as ?? 'parts');
+    try {
+        const raw = await decodeImageFile(opts.sheet);
+        const k = keyed(raw, opts.key);
+        const ruled = opts.clean ? dropRuledLines(k.img) : null;
+        if (ruled)
+            k.img = ruled.img;
+        let boxes;
+        let mode;
+        let seg;
+        if (opts.boxes) {
+            const b = await readBoxes(opts.boxes);
+            if (typeof b === 'string') {
+                u.error(b);
+                return EXIT.error;
+            }
+            boxes = b;
+            mode = `boxes from ${opts.boxes}`;
+        }
+        else if (opts.grid) {
+            boxes = gridBoxes(raw.width, raw.height, opts.grid.cols, opts.grid.rows);
+            mode = `grid ${opts.grid.cols}x${opts.grid.rows}`;
+        }
+        else {
+            seg = segment(k.img, opts.merge);
+            boxes = seg.boxes;
+            mode = 'every separate figure';
+        }
+        const clean = opts.clean ? { ground: k.ground ?? (opts.key.kind === 'colour' ? { rgb: opts.key.rgb, tolerance: PARTS_DEFAULTS.tolerance } : null), keepShadows: !!opts.keepShadows } : null;
+        const { pieces, empty } = cutPieces(k.img, boxes, opts.names, opts.pad, opts.pivot, seg, clean);
+        if (!pieces.length) {
+            u.error(`nothing visible on ${opts.sheet} after keying (${k.keyed})`, 'try --key none for a sheet with its own alpha, or --key #rrggbb for its background');
+            return EXIT.not_observed;
+        }
+        const out = resolve(opts.out ?? join(dirname(opts.sheet), `${basename(opts.sheet, extname(opts.sheet))}-parts`));
+        await mkdir(out, { recursive: true });
+        const written = [];
+        for (const p of pieces) {
+            const file = join(out, `${p.part.name}.png`);
+            await writeFile(file, encodePng(p.img));
+            let webp;
+            if (opts.webp) {
+                webp = join(out, `${p.part.name}.webp`);
+                await writeFile(webp, await encodeWebp(p.img));
+            }
+            written.push({ ...p.part, file: basename(file), ...(webp ? { webp: basename(webp) } : {}) });
+        }
+        const total = clean ? written.reduce((t, p) => { for (const [n, v] of Object.entries(p.removed ?? {}))
+            t[n] += v; return t; }, { halo: 0, shadow: 0, islands: 0, island_px: 0, defringed: 0 }) : null;
+        const manifest = { sheet: basename(opts.sheet), size: { w: raw.width, h: raw.height }, keyed: k.keyed, mode, pivot: opts.pivot, pad: opts.pad, ...(clean ? { clean: { keep_shadows: !!opts.keepShadows, ruled_lines: ruled?.lines ?? 0, removed: total } } : {}), parts: written };
+        await writeFile(join(out, 'parts.json'), JSON.stringify(manifest, null, 2) + '\n');
+        const warnings = [];
+        if (k.warning)
+            warnings.push(k.warning);
+        const halo = haloShare(k.img);
+        if (halo > 0.05 && !clean)
+            warnings.push(`${Math.round(halo * 100)}% of the visible pixels are a faint glow or shadow${opts.grid || opts.boxes ? '' : ': pieces are found by their solid outline and the glow is cut at each box'}; for clean parts ask the generator for a hard-edged cut-out on a flat or transparent ground`);
+        if (opts.names.length && opts.names.length !== pieces.length + empty.length)
+            warnings.push(`${opts.names.length} name(s) for ${pieces.length + empty.length} piece(s): check the order in parts.json before wiring them`);
+        if (empty.length)
+            warnings.push(`${empty.length} box(es) held nothing visible: ${empty.join(', ')}`);
+        const edge = written.filter((p) => p.touches_edge).map((p) => p.name);
+        if (edge.length)
+            warnings.push(`cut by the sheet's edge (may be missing a piece): ${edge.join(', ')}`);
+        if (opts.json) {
+            io.log(JSON.stringify({ out, ...manifest, warnings }, null, 2));
+            return EXIT.pass;
+        }
+        u.heading(`${opts.as ?? 'parts'} · ${basename(opts.sheet)} ${raw.width}x${raw.height} · ${mode} · keyed ${k.keyed}${clean ? ' · cleaned' : ''}`);
+        const took = (r) => (r ? [r.shadow ? `${r.shadow} px painted shadow` : '', r.halo ? `${r.halo} px halo` : '', r.islands ? `${r.islands} island(s) (${r.island_px} px)` : ''].filter(Boolean).join(', ') || 'nothing to remove' : '');
+        for (const p of written)
+            u.item('pass', `${p.name}  ${p.size.w}x${p.size.h}  pivot ${p.pivot.x},${p.pivot.y}`, `from ${p.box.x},${p.box.y}${p.removed ? ` · removed ${took(p.removed)}` : ''}`);
+        if (total)
+            u.line(`removed in all: ${took(total)}${ruled?.lines ? `, ${ruled.lines} line(s) ruled across the sheet` : ''}; rim colour pulled from inside on ${total.defringed} px${opts.keepShadows ? ' (shadows kept: --keep-shadows)' : ''}`);
+        for (const w of warnings)
+            u.item('warn', w);
+        u.line(join(out, 'parts.json'));
+        u.summary('pass', `${written.length} piece(s) in ${out}; for a rig, set each part's pivot at its joint (shoulder, hip, neck) and check every part stays attached through a walk`);
+        return EXIT.pass;
+    }
+    catch (e) {
+        u.error(`parts failed: ${e instanceof Error ? e.message : String(e)}`);
+        return EXIT.error;
+    }
+}