@mohasinac/appkit 4.52.4 → 4.53.0

package/dist/_internal/shared/features/sticker-trace/math/label.js

@@ -0,0 +1,156 @@
+/*
+ * WHY: Segmentation ends with "which pixels belong to the same sticker". That is
+ *      connected-component labelling, and it is needed three times — once for
+ *      the parts themselves, once to find the background region the flood
+ *      reached, and once to cluster parts into physical sheets.
+ * WHAT: Two-pass CCL over a binary mask with union-find, returning labels plus
+ *       per-component area and bounding box in one walk.
+ *
+ * 4-connectivity, deliberately. Under 8-connectivity two stickers touching at a
+ * single diagonal pixel — which a hysteresis-linked ridge map produces fairly
+ * often — merge into one component and therefore one cut path, and the sheet
+ * leaves the cutter in one piece. Losing a genuine 1px diagonal bridge inside a
+ * sticker is the cheaper error, and the bridge closing (see trace/segment)
+ * repairs that case on purpose.
+ *
+ * EXPORTS: LabelResult, ComponentStats, labelComponents
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:segment,cluster,flood,geometry
+ * @tag sideEffects:none
+ */
+/**
+ * Union-find with path halving and union by size.
+ *
+ * Path halving rather than full compression because it is a single extra array
+ * write in the find loop and gets the same near-constant amortised behaviour —
+ * on a 9 MP raster the difference in allocation churn is worth more than the
+ * theoretical constant.
+ */
+class UnionFind {
+    constructor(capacity) {
+        this.parent = new Int32Array(capacity);
+        this.size = new Int32Array(capacity);
+    }
+    make(x) {
+        this.parent[x] = x;
+        this.size[x] = 1;
+    }
+    find(x) {
+        let root = x;
+        while (this.parent[root] !== root) {
+            this.parent[root] = this.parent[this.parent[root]];
+            root = this.parent[root];
+        }
+        return root;
+    }
+    union(a, b) {
+        let ra = this.find(a);
+        let rb = this.find(b);
+        if (ra === rb)
+            return;
+        if (this.size[ra] < this.size[rb]) {
+            const t = ra;
+            ra = rb;
+            rb = t;
+        }
+        this.parent[rb] = ra;
+        this.size[ra] = this.size[ra] + this.size[rb];
+    }
+}
+export function labelComponents(mask, width, height) {
+    const labels = new Int32Array(width * height);
+    // Worst case is a checkerboard: every other pixel its own provisional label.
+    const uf = new UnionFind(Math.ceil((width * height) / 2) + 2);
+    let next = 1;
+    // Pass 1 — provisional labels, recording equivalences.
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const i = row + x;
+            if (!mask[i])
+                continue;
+            const left = x > 0 && mask[i - 1] ? labels[i - 1] : 0;
+            const up = y > 0 && mask[i - width] ? labels[i - width] : 0;
+            if (left && up) {
+                labels[i] = left;
+                if (left !== up)
+                    uf.union(left, up);
+            }
+            else if (left) {
+                labels[i] = left;
+            }
+            else if (up) {
+                labels[i] = up;
+            }
+            else {
+                uf.make(next);
+                labels[i] = next;
+                next++;
+            }
+        }
+    }
+    // Pass 2 — resolve to roots, renumber densely, and accumulate stats in the
+    // same walk. A separate stats pass would be a second full traversal of a
+    // 9 MP buffer for numbers we already have in hand.
+    const remap = new Int32Array(next);
+    const areas = [];
+    const minX = [];
+    const minY = [];
+    const maxX = [];
+    const maxY = [];
+    const border = [];
+    let count = 0;
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            const i = row + x;
+            if (!labels[i])
+                continue;
+            const root = uf.find(labels[i]);
+            let dense = remap[root];
+            if (dense === 0) {
+                count++;
+                dense = count;
+                remap[root] = dense;
+                areas.push(0);
+                minX.push(x);
+                minY.push(y);
+                maxX.push(x);
+                maxY.push(y);
+                border.push(false);
+            }
+            labels[i] = dense;
+            const k = dense - 1;
+            areas[k] = areas[k] + 1;
+            if (x < minX[k])
+                minX[k] = x;
+            if (y < minY[k])
+                minY[k] = y;
+            if (x > maxX[k])
+                maxX[k] = x;
+            if (y > maxY[k])
+                maxY[k] = y;
+            if (x === 0 || y === 0 || x === width - 1 || y === height - 1)
+                border[k] = true;
+        }
+    }
+    const stats = [];
+    for (let k = 0; k < count; k++) {
+        stats.push({
+            label: k + 1,
+            area: areas[k],
+            bbox: {
+                x: minX[k],
+                y: minY[k],
+                width: maxX[k] - minX[k] + 1,
+                height: maxY[k] - minY[k] + 1,
+            },
+            touchesBorder: border[k],
+        });
+    }
+    return { labels, count, stats };
+}

package/dist/_internal/shared/features/sticker-trace/math/marching-squares.d.ts

@@ -0,0 +1,16 @@
+import type { Point } from "../types";
+export interface Ring {
+    readonly points: readonly Point[];
+    /** Signed area; positive is counter-clockwise in image coordinates. */
+    readonly signedArea: number;
+    /** True when the ring closed back on itself, which every valid cut path must. */
+    readonly closed: boolean;
+}
+/**
+ * Extract every closed ring at `iso`.
+ *
+ * `field` may be the binary mask itself or a blurred copy; both are read as
+ * numbers, and the iso level decides. Rings shorter than 8 points are dropped —
+ * at this scale they are single-pixel speckle, never a sticker.
+ */
+export declare function traceContours(field: Uint8Array | Float32Array, width: number, height: number, iso?: number): Ring[];

package/dist/_internal/shared/features/sticker-trace/math/marching-squares.js

@@ -0,0 +1,242 @@
+/*
+ * WHY: A cut path is a closed outline, and the segmentation produces a raster
+ *      mask. Turning one into the other has to be exact about closure: a ring
+ *      that fails to close is a cut the machine starts and never finishes, and
+ *      a ring that self-intersects is a nick in the sticker.
+ * WHAT: Marching squares at an iso level, linked into guaranteed-closed rings.
+ *
+ * Linking is done by EDGE IDENTITY, not by coordinate proximity. Each cell
+ * boundary crossing lands on one specific grid edge, and adjacent cells
+ * produce the identical edge id — so chaining is exact integer bookkeeping
+ * rather than "are these two floats close enough", which is the usual source
+ * of a contour that almost closes.
+ *
+ * EXPORTS: Ring, traceContours
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:geometry
+ * @tag sideEffects:none
+ */
+/**
+ * Grid edges are identified rather than located.
+ *
+ * A horizontal edge spans (x,y)->(x+1,y); a vertical edge spans (x,y)->(x,y+1).
+ * Two cells sharing a boundary compute the SAME id, which is what makes ring
+ * assembly exact.
+ */
+function hEdge(x, y, width) {
+    return (y * width + x) * 2;
+}
+function vEdge(x, y, width) {
+    return (y * width + x) * 2 + 1;
+}
+/**
+ * Where the iso level crosses between two samples.
+ *
+ * On a binary mask this always returns the midpoint, which is the correct
+ * half-pixel "crack" between set and unset. On a smoothed field it returns a
+ * genuine sub-pixel position — which is the entire difference the `precise`
+ * and `max` tiers buy, and why they blur before tracing rather than tracing
+ * harder.
+ */
+function lerp(a, b, iso) {
+    const d = b - a;
+    if (Math.abs(d) < 1e-9)
+        return 0.5;
+    const t = (iso - a) / d;
+    return t < 0 ? 0 : t > 1 ? 1 : t;
+}
+/**
+ * Cases 5 and 10 are the SADDLES: two diagonal corners inside, two outside.
+ *
+ * Both have two geometrically valid pairings, and the one chosen decides
+ * whether the two regions pinch together at this cell or stay apart. Choosing
+ * inconsistently across neighbouring cells produces rings that cross
+ * themselves, which survives every later stage — RDP simplifies it, the Bézier
+ * fit smooths it, and it emerges as a cut path that doubles back.
+ *
+ * Resolve by the cell's MEAN, which keeps the choice continuous with the
+ * surrounding field instead of arbitrary.
+ *
+ * 🛑 The two codes take OPPOSITE pairings for the same centre value — they are
+ * mirror configurations. Sharing one branch without the inversion would join
+ * the wrong corners on half of all saddles, and the output would still be a
+ * plausible set of closed rings.
+ *
+ * Extracted from the switch rather than inlined: at that depth it tripped
+ * `audit-code-quality`'s DEEP_NESTING, and the two cases had independently
+ * re-derived the same mean.
+ *
+ * 🛑 MEASURED 2026-10-18: this branch is NOT REACHED by any of the reference
+ * scans, at `standard` or at `precise`. Inverting the rule on purpose changed
+ * nothing — not part counts, not total Bézier node counts, not closure — on
+ * five scans at both tiers. The reason is upstream: `close` and
+ * `curvatureSmooth` eliminate the checkerboard-like local patterns a true
+ * diagonal saddle requires, and `softenForSubPixel`'s blur removes what little
+ * survives.
+ *
+ * So the correctness of the inversion rests on INSPECTION (all four
+ * code×centre combinations hand-checked), never on measurement. Do not read
+ * the corpus harness agreeing with itself as evidence about this function.
+ * It is kept because a future tier that traces a less-smoothed field, or any
+ * path that skips the cleaning stages, reaches it immediately — and because
+ * the failure it prevents is a self-crossing cut path, which survives RDP and
+ * the Bézier fit and emerges looking like a plausible outline.
+ */
+function connectSaddle(code, corners, iso, edges, connect) {
+    const mean = (corners.tl + corners.tr + corners.br + corners.bl) / 4;
+    const centreInside = mean >= iso;
+    const joinLeftToTop = code === 5 ? centreInside : !centreInside;
+    if (joinLeftToTop) {
+        connect(edges.left, edges.top);
+        connect(edges.bottom, edges.right);
+    }
+    else {
+        connect(edges.left, edges.bottom);
+        connect(edges.top, edges.right);
+    }
+}
+/**
+ * Extract every closed ring at `iso`.
+ *
+ * `field` may be the binary mask itself or a blurred copy; both are read as
+ * numbers, and the iso level decides. Rings shorter than 8 points are dropped —
+ * at this scale they are single-pixel speckle, never a sticker.
+ */
+export function traceContours(field, width, height, iso = 0.5) {
+    // edge id -> the interpolated point on that edge
+    const points = new Map();
+    // edge id -> the edge ids it is connected to (at most 2)
+    const links = new Map();
+    const connect = (a, b) => {
+        const la = links.get(a);
+        if (la)
+            la.push(b);
+        else
+            links.set(a, [b]);
+        const lb = links.get(b);
+        if (lb)
+            lb.push(a);
+        else
+            links.set(b, [a]);
+    };
+    const at = (x, y) => field[y * width + x];
+    for (let y = 0; y < height - 1; y++) {
+        for (let x = 0; x < width - 1; x++) {
+            const tl = at(x, y);
+            const tr = at(x + 1, y);
+            const br = at(x + 1, y + 1);
+            const bl = at(x, y + 1);
+            const code = (tl >= iso ? 8 : 0) | (tr >= iso ? 4 : 0) | (br >= iso ? 2 : 0) | (bl >= iso ? 1 : 0);
+            if (code === 0 || code === 15)
+                continue;
+            const top = hEdge(x, y, width);
+            const right = vEdge(x + 1, y, width);
+            const bottom = hEdge(x, y + 1, width);
+            const left = vEdge(x, y, width);
+            if (!points.has(top))
+                points.set(top, { x: x + lerp(tl, tr, iso), y });
+            if (!points.has(right))
+                points.set(right, { x: x + 1, y: y + lerp(tr, br, iso) });
+            if (!points.has(bottom))
+                points.set(bottom, { x: x + lerp(bl, br, iso), y: y + 1 });
+            if (!points.has(left))
+                points.set(left, { x, y: y + lerp(tl, bl, iso) });
+            switch (code) {
+                case 1:
+                case 14:
+                    connect(left, bottom);
+                    break;
+                case 2:
+                case 13:
+                    connect(bottom, right);
+                    break;
+                case 3:
+                case 12:
+                    connect(left, right);
+                    break;
+                case 4:
+                case 11:
+                    connect(top, right);
+                    break;
+                case 6:
+                case 9:
+                    connect(top, bottom);
+                    break;
+                case 7:
+                case 8:
+                    connect(left, top);
+                    break;
+                /*
+                 * The two saddles — see `connectSaddle` for why they are not one case.
+                 *
+                 * Split rather than shared so each passes a LITERAL: `code` is a
+                 * `number` here (it comes out of a bitwise OR), so a shared
+                 * `case 5: case 10:` would not narrow it and the helper would have to
+                 * accept `number` — making 7 a representable argument for a function
+                 * that has no correct answer for it.
+                 */
+                case 5:
+                    connectSaddle(5, { tl, tr, br, bl }, iso, { top, right, bottom, left }, connect);
+                    break;
+                case 10:
+                    connectSaddle(10, { tl, tr, br, bl }, iso, { top, right, bottom, left }, connect);
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+    const visited = new Set();
+    const rings = [];
+    for (const startEdge of links.keys()) {
+        if (visited.has(startEdge))
+            continue;
+        const chain = [];
+        let current = startEdge;
+        let previous = -1;
+        let closed = false;
+        for (;;) {
+            visited.add(current);
+            const p = points.get(current);
+            if (p)
+                chain.push(p);
+            const neighbours = links.get(current);
+            if (!neighbours)
+                break;
+            let nextEdge = -1;
+            for (const n of neighbours) {
+                if (n === previous)
+                    continue;
+                if (n === startEdge && chain.length > 2) {
+                    closed = true;
+                    break;
+                }
+                if (!visited.has(n)) {
+                    nextEdge = n;
+                    break;
+                }
+            }
+            if (closed || nextEdge === -1)
+                break;
+            previous = current;
+            current = nextEdge;
+        }
+        if (chain.length < 8)
+            continue;
+        rings.push({ points: chain, signedArea: shoelace(chain), closed });
+    }
+    return rings;
+}
+function shoelace(points) {
+    let sum = 0;
+    for (let i = 0; i < points.length; i++) {
+        const a = points[i];
+        const b = points[(i + 1) % points.length];
+        sum += a.x * b.y - b.x * a.y;
+    }
+    return sum / 2;
+}

package/dist/_internal/shared/features/sticker-trace/math/morphology.d.ts

@@ -0,0 +1,46 @@
+/** Outward offset by a true Euclidean radius, in pixels. */
+export declare function dilate(mask: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/**
+ * Inward offset. Note this erodes against the mask's complement, so pixels
+ * outside the raster count as background — a component touching the edge
+ * erodes inward from that edge too, which is what the de-halo pass wants.
+ */
+export declare function erode(mask: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/** Erode then dilate — removes speckle smaller than the disc. */
+export declare function open(mask: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/**
+ * Dilate then erode — bridges channels narrower than 2*radius.
+ *
+ * This is how a sticker that thresholding split in two is rejoined: a white
+ * band reaching the sticker's outer edge is not an enclosed hole, so no
+ * hole-filling can recover it, and the sticker would otherwise arrive as two
+ * components with two cut paths. The radius must sit between the widest
+ * intra-sticker band and the narrowest real gap between neighbours — measure
+ * both before changing it.
+ */
+export declare function close(mask: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/**
+ * Curvature-smooth a silhouette.
+ *
+ * A scan rings at every ink/paper boundary, and thresholding that gradient
+ * freezes the ringing into the mask as comb teeth a few tenths of a millimetre
+ * deep. A blade traces every one of them.
+ *
+ * 🛑 This is NOT an open/close pair at the same radius, and the difference is
+ * the point. Blurring then re-thresholding at 0.5 is a curvature flow: it
+ * erases high-frequency teeth while leaving the edge where it was. An
+ * open/close pair at the same radius rounds REAL corners much harder for the
+ * same despeckling — on these sheets that visibly blunts the points of every
+ * claw-shaped sticker.
+ */
+export declare function curvatureSmooth(mask: Uint8Array, width: number, height: number, radius: number): Uint8Array;
+/**
+ * The radius of the largest disc that fits inside the component — i.e. half its
+ * narrowest neck.
+ *
+ * Cricut's minimum reliable detail is 0.25in; a part whose neck is below that
+ * tears rather than cuts. Measuring it is one EDT over the component mask and
+ * a max, so it is cheap enough to report for every part rather than only on
+ * request.
+ */
+export declare function minFeatureRadius(mask: Uint8Array, width: number, height: number): number;

package/dist/_internal/shared/features/sticker-trace/math/morphology.js

@@ -0,0 +1,168 @@
+/*
+ * WHY: The old Python tracer used scipy's structuring elements, and the two
+ *      operations that mattered most — the bleed offset and the curvature
+ *      smoothing — were both documented there as needing a TRUE disc rather
+ *      than a square kernel, because a blade rounds convex corners the way a
+ *      circle does and not the way a 3x3 box does.
+ * WHAT: Morphology expressed as distance-transform thresholds, which gives an
+ *       exact disc of any radius at no extra cost and in O(n) regardless of
+ *       radius — a separable box kernel cannot do the first and a naive disc
+ *       kernel cannot do the second.
+ *
+ * The identity this file rests on: dilate(mask, r) is exactly "every pixel
+ * within r of a set pixel", i.e. edt(¬mask) <= r. Erosion is the dual on the
+ * complement. Open and close are then the usual compositions, and because the
+ * radius never enters a loop bound, a 20px disc costs the same as a 2px one.
+ *
+ * EXPORTS: dilate, erode, open, close, curvatureSmooth, minFeatureRadius
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:segment,geometry,ridge,flood
+ * @tag sideEffects:none
+ */
+import { edtSquared } from "./edt.js";
+function invert(mask) {
+    const out = new Uint8Array(mask.length);
+    for (let i = 0; i < mask.length; i++)
+        out[i] = mask[i] ? 0 : 1;
+    return out;
+}
+/** Outward offset by a true Euclidean radius, in pixels. */
+export function dilate(mask, width, height, radius) {
+    if (radius <= 0)
+        return mask.slice();
+    const dist = edtSquared(mask, width, height);
+    const r2 = radius * radius;
+    const out = new Uint8Array(mask.length);
+    for (let i = 0; i < out.length; i++)
+        out[i] = dist[i] <= r2 ? 1 : 0;
+    return out;
+}
+/**
+ * Inward offset. Note this erodes against the mask's complement, so pixels
+ * outside the raster count as background — a component touching the edge
+ * erodes inward from that edge too, which is what the de-halo pass wants.
+ */
+export function erode(mask, width, height, radius) {
+    if (radius <= 0)
+        return mask.slice();
+    const dist = edtSquared(invert(mask), width, height);
+    const r2 = radius * radius;
+    const out = new Uint8Array(mask.length);
+    for (let i = 0; i < out.length; i++)
+        out[i] = dist[i] > r2 ? 1 : 0;
+    return out;
+}
+/** Erode then dilate — removes speckle smaller than the disc. */
+export function open(mask, width, height, radius) {
+    if (radius <= 0)
+        return mask.slice();
+    return dilate(erode(mask, width, height, radius), width, height, radius);
+}
+/**
+ * Dilate then erode — bridges channels narrower than 2*radius.
+ *
+ * This is how a sticker that thresholding split in two is rejoined: a white
+ * band reaching the sticker's outer edge is not an enclosed hole, so no
+ * hole-filling can recover it, and the sticker would otherwise arrive as two
+ * components with two cut paths. The radius must sit between the widest
+ * intra-sticker band and the narrowest real gap between neighbours — measure
+ * both before changing it.
+ */
+export function close(mask, width, height, radius) {
+    if (radius <= 0)
+        return mask.slice();
+    return erode(dilate(mask, width, height, radius), width, height, radius);
+}
+/**
+ * Curvature-smooth a silhouette.
+ *
+ * A scan rings at every ink/paper boundary, and thresholding that gradient
+ * freezes the ringing into the mask as comb teeth a few tenths of a millimetre
+ * deep. A blade traces every one of them.
+ *
+ * 🛑 This is NOT an open/close pair at the same radius, and the difference is
+ * the point. Blurring then re-thresholding at 0.5 is a curvature flow: it
+ * erases high-frequency teeth while leaving the edge where it was. An
+ * open/close pair at the same radius rounds REAL corners much harder for the
+ * same despeckling — on these sheets that visibly blunts the points of every
+ * claw-shaped sticker.
+ */
+export function curvatureSmooth(mask, width, height, radius) {
+    if (radius < 0.5)
+        return mask.slice();
+    const pre = open(mask, width, height, radius * 0.5);
+    const blurred = gaussianBlur(pre, width, height, radius);
+    const out = new Uint8Array(mask.length);
+    for (let i = 0; i < out.length; i++)
+        out[i] = blurred[i] >= 0.5 ? 1 : 0;
+    return out;
+}
+/**
+ * Separable Gaussian over a binary mask, returning floats in 0..1.
+ *
+ * Separable because a 2-D kernel at radius 6 is 169 multiplies per pixel
+ * against 26 for two 1-D passes, and on a 9 MP raster that is the difference
+ * between a noticeable pause and none.
+ */
+function gaussianBlur(mask, width, height, sigma) {
+    const radius = Math.max(1, Math.ceil(sigma * 3));
+    const kernel = new Float32Array(radius * 2 + 1);
+    const denom = 2 * sigma * sigma;
+    let sum = 0;
+    for (let i = -radius; i <= radius; i++) {
+        const v = Math.exp(-(i * i) / denom);
+        kernel[i + radius] = v;
+        sum += v;
+    }
+    for (let i = 0; i < kernel.length; i++)
+        kernel[i] = kernel[i] / sum;
+    const tmp = new Float32Array(width * height);
+    const out = new Float32Array(width * height);
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            let acc = 0;
+            for (let k = -radius; k <= radius; k++) {
+                // Clamp at the edge rather than wrapping or zero-padding: zero-padding
+                // pulls the silhouette inward at the raster border, which on a scan
+                // whose sheet runs to the edge would shave the outermost stickers.
+                const sx = Math.min(width - 1, Math.max(0, x + k));
+                acc += mask[row + sx] * kernel[k + radius];
+            }
+            tmp[row + x] = acc;
+        }
+    }
+    for (let x = 0; x < width; x++) {
+        for (let y = 0; y < height; y++) {
+            let acc = 0;
+            for (let k = -radius; k <= radius; k++) {
+                const sy = Math.min(height - 1, Math.max(0, y + k));
+                acc += tmp[sy * width + x] * kernel[k + radius];
+            }
+            out[y * width + x] = acc;
+        }
+    }
+    return out;
+}
+/**
+ * The radius of the largest disc that fits inside the component — i.e. half its
+ * narrowest neck.
+ *
+ * Cricut's minimum reliable detail is 0.25in; a part whose neck is below that
+ * tears rather than cuts. Measuring it is one EDT over the component mask and
+ * a max, so it is cheap enough to report for every part rather than only on
+ * request.
+ */
+export function minFeatureRadius(mask, width, height) {
+    const dist = edtSquared(invert(mask), width, height);
+    let max = 0;
+    for (let i = 0; i < dist.length; i++) {
+        if (mask[i] && dist[i] > max)
+            max = dist[i];
+    }
+    return Math.sqrt(max);
+}