@mohasinac/appkit 4.52.5 → 4.53.0

package/dist/_internal/shared/features/sticker-trace/export/vectorise-art.js

@@ -0,0 +1,195 @@
+/*
+ * WHY: A flat-colour sticker — a solid red claw, a DRIGER G wordmark — traces
+ *      into clean filled shapes that scale to any size. A gradient or a
+ *      halftone screen does not: it bands, it explodes the node count, and the
+ *      result is worse than the raster it replaced.
+ * WHAT: Optional per-part artwork vectorisation, which MEASURES whether it
+ *       helped and says so.
+ *
+ * 🛑 IT IS OPT-IN PER PART AND THE RASTER ALWAYS SURVIVES. This is the one
+ * export in the suite that can make a part worse, so it never replaces
+ * anything — it produces an additional file, and the report says whether it is
+ * worth using.
+ *
+ * 🛑 IT REPORTS A MEASURED DEVIATION, NOT A CONFIDENCE. The honest question is
+ * "how far does the vector sit from the pixels", and that is computable: fill
+ * the traced regions back into a mask and count the pixels that disagree. A
+ * heuristic score would be a number nobody could check.
+ *
+ * 🛑 Built on the modules that already exist — `quantiseBoundaries`,
+ * `traceContours`, `simplifyRdp`. A second posteriser here would be a second
+ * answer to "which colours are in this image", and the trace pipeline's
+ * fused-channel detector already depends on the first one.
+ *
+ * EXPORTS: VectoriseResult, VectorRegion, vectoriseArtwork
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:sticker-trace/export
+ * @tag sideEffects:none
+ */
+import { simplifyRdp } from "../math/rdp.js";
+import { traceContours } from "../math/marching-squares.js";
+import { quantiseBoundaries } from "../trace/quantise.js";
+/**
+ * Above this share of mismatched pixels, the vector is visibly not the artwork.
+ *
+ * 🛑 PICKED, NOT MEASURED — and said so deliberately. Every other threshold in
+ * this feature was chosen against the nine reference scans; this one has not
+ * been, because nobody has yet run the quantiser over the corpus and compared
+ * the deviation on a flat-colour part against an airbrushed one. 8% is a
+ * starting guess.
+ *
+ * That is exactly why the measured deviation is reported ALONGSIDE the verdict
+ * rather than hidden behind it: the number is trustworthy, the threshold is
+ * not, and an operator can disagree with the verdict using the figure. Run the
+ * corpus and replace this comment with what it says.
+ */
+const DEVIATION_LIMIT = 0.08;
+/**
+ * Above this, Design Space struggles and the file stops being usable.
+ *
+ * Deliberately lower than the machine node budget: that budget applies to the
+ * CUT path, which is one outline per part. This is fill artwork, where a
+ * banded gradient can produce tens of thousands of nodes on its own.
+ */
+const NODE_LIMIT = 20000;
+/**
+ * @param raster the part's own RGBA crop
+ * @param alpha  its cut mask — which pixels belong to the sticker at all
+ */
+export function vectoriseArtwork(raster, alpha, opts = {}) {
+    const colours = Math.max(2, Math.min(32, opts.colours ?? 8));
+    const simplify = opts.simplifyPx ?? 0.75;
+    const { width, height, data: rgba } = raster;
+    /*
+     * The SAME quantiser the trace pipeline's fused detector uses — not a second
+     * posteriser. Two answers to "which colours are in this image" would mean the
+     * artwork banded along boundaries the cut line never saw.
+     */
+    const quant = quantiseBoundaries(raster, colours);
+    const { labels } = quant;
+    /*
+     * Average each region's real colour rather than using the palette entry.
+     * Median cut picks a representative, not a mean, so the palette colour can
+     * sit visibly outside the pixels it stands for — and on a sticker the fill
+     * colour IS the product.
+     */
+    const sums = new Float64Array(colours * 3);
+    const counts = new Int32Array(colours);
+    for (let i = 0; i < width * height; i++) {
+        if ((alpha[i] ?? 0) < 128)
+            continue;
+        const label = labels[i] ?? 0;
+        if (label < 0 || label >= colours)
+            continue;
+        counts[label] += 1;
+        sums[label * 3] += rgba[i * 4] ?? 0;
+        sums[label * 3 + 1] += rgba[i * 4 + 1] ?? 0;
+        sums[label * 3 + 2] += rgba[i * 4 + 2] ?? 0;
+    }
+    const opaque = counts.reduce((a, b) => a + b, 0);
+    if (opaque === 0) {
+        return {
+            regions: [],
+            nodeCount: 0,
+            deviation: 1,
+            notRecommended: true,
+            reason: "This part has no opaque pixels to vectorise.",
+        };
+    }
+    const regions = [];
+    let nodeCount = 0;
+    for (let label = 0; label < colours; label++) {
+        const n = counts[label] ?? 0;
+        if (n === 0)
+            continue;
+        /*
+         * One binary mask per palette entry, traced independently. Tracing all
+         * boundaries at once would give edges with no inside — a filled shape needs
+         * to know which side it is on, and a per-label mask answers that by
+         * construction.
+         */
+        const mask = new Uint8Array(width * height);
+        for (let i = 0; i < width * height; i++) {
+            if ((alpha[i] ?? 0) >= 128 && labels[i] === label)
+                mask[i] = 1;
+        }
+        const rings = traceContours(mask, width, height, 0.5)
+            .map((ring) => simplifyRdp(ring.points, simplify))
+            // A ring of fewer than 3 points encloses no area; keeping it would add
+            // nodes and paint nothing.
+            .filter((pts) => pts.length >= 3);
+        if (rings.length === 0)
+            continue;
+        for (const r of rings)
+            nodeCount += r.length;
+        regions.push({
+            rgb: [
+                Math.round(sums[label * 3] / n),
+                Math.round(sums[label * 3 + 1] / n),
+                Math.round(sums[label * 3 + 2] / n),
+            ],
+            rings,
+            coverage: n / opaque,
+        });
+    }
+    /*
+     * The deviation, MEASURED.
+     *
+     * Every opaque pixel is compared against the colour its own region would
+     * paint. This is a lower bound on the real error — it ignores the rings'
+     * simplification, which moves a boundary by at most `simplifyPx` — and a
+     * lower bound is the honest direction: it never flatters the result.
+     */
+    let wrong = 0;
+    for (let i = 0; i < width * height; i++) {
+        if ((alpha[i] ?? 0) < 128)
+            continue;
+        const label = labels[i] ?? 0;
+        const n = counts[label] ?? 0;
+        if (n === 0)
+            continue;
+        const dr = (rgba[i * 4] ?? 0) - sums[label * 3] / n;
+        const dg = (rgba[i * 4 + 1] ?? 0) - sums[label * 3 + 1] / n;
+        const db = (rgba[i * 4 + 2] ?? 0) - sums[label * 3 + 2] / n;
+        // ~12 levels per channel: below this a human reading a printed sticker
+        // cannot tell the band from the gradient.
+        if (Math.sqrt(dr * dr + dg * dg + db * db) > 20)
+            wrong++;
+    }
+    const deviation = wrong / opaque;
+    const tooFar = deviation > DEVIATION_LIMIT;
+    const tooMany = nodeCount > NODE_LIMIT;
+    return {
+        regions,
+        nodeCount,
+        deviation: Math.round(deviation * 1000) / 1000,
+        notRecommended: tooFar || tooMany,
+        reason: tooFar
+            ? `${Math.round(deviation * 100)}% of this part's pixels shift visibly — it is a gradient or a halftone, and vectorising will band it. Keep the raster.`
+            : tooMany
+                ? `${nodeCount.toLocaleString()} nodes is past what Design Space handles comfortably. Keep the raster, or trace with fewer colours.`
+                : "",
+    };
+}
+/** Serialise the regions to SVG paths, for an artwork layer. */
+export function regionsToSvgPaths(regions) {
+    const hex = (c) => c.toString(16).padStart(2, "0").toUpperCase();
+    return regions
+        .map((region) => {
+        const d = region.rings
+            .map((ring) => `M ${ring.map((p) => `${Math.round(p.x * 100) / 100} ${Math.round(p.y * 100) / 100}`).join(" L ")} Z`)
+            .join(" ");
+        /*
+         * `fill-rule="evenodd"` so a ring inside another ring cuts a hole rather
+         * than painting over it. A letter's counter — the gap in an O — is
+         * exactly this case, and nonzero would fill it solid.
+         */
+        const fill = `#${hex(region.rgb[0])}${hex(region.rgb[1])}${hex(region.rgb[2])}`;
+        return `<path d="${d}" fill="${fill}" fill-rule="evenodd" />`;
+    })
+        .join("\n");
+}

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

@@ -0,0 +1,2 @@
+import type { DecodedRaster, TraceParams, TraceResult } from "./types";
+export declare function traceStickerSheet(raster: DecodedRaster, params: TraceParams, sourceWidth?: number): TraceResult;

package/dist/_internal/shared/features/sticker-trace/index.js

@@ -0,0 +1,59 @@
+/*
+ * WHY: One entry point, so the browser's live-tuning loop and the Firebase
+ *      Function's full-resolution render provably run the same algorithm rather
+ *      than two implementations that agree today (CLAUDE.md Root Cause #59/#73).
+ * WHAT: `traceStickerSheet(raster, params)` — synchronous, codec-free, pure.
+ *
+ * It takes decoded pixels and returns geometry. It never decodes, never
+ * resizes, never writes, and never touches a file: the memory cap lives in the
+ * codec's `decode`, so by the time anything here runs the raster is already
+ * bounded. That is what keeps a 34 MP scan from becoming a 136 MB Float32Array
+ * inside the maths.
+ *
+ * EXPORTS: traceStickerSheet
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:run,canvas-codec,probe-sticker-trace
+ * @tag sideEffects:none
+ */
+import { TIER_PRESETS } from "./config.js";
+import { clusterParts } from "./trace/cluster.js";
+import { buildPartGeometry } from "./trace/geometry.js";
+import { segmentSheet } from "./trace/segment.js";
+export function traceStickerSheet(raster, params, sourceWidth) {
+    const pxPerMm = raster.dpi ? raster.dpi / 25.4 : null;
+    const subPixel = TIER_PRESETS[params.tier].subPixelContours;
+    const segmented = segmentSheet(raster, params);
+    const geometry = [];
+    let ordinal = 1;
+    for (const stat of segmented.parts) {
+        if (geometry.length >= params.maxParts)
+            break;
+        const part = buildPartGeometry(segmented.labels, raster.width, raster.height, stat, ordinal, params, pxPerMm, subPixel);
+        // A component whose contour would not close is DROPPED rather than emitted
+        // open. An open cut path is a sticker the machine slices most of the way
+        // around and leaves attached — worse than one it never cut at all, because
+        // the sheet is now damaged.
+        if (part) {
+            geometry.push(part);
+            ordinal++;
+        }
+    }
+    const { clusters, assigned } = clusterParts(geometry, pxPerMm, params.clusterGapMm);
+    return {
+        parts: assigned,
+        clusters,
+        diagnostics: segmented.diagnostics,
+        pxPerMm,
+        /*
+         * The scale a caller multiplies this geometry by to reach the SOURCE image.
+         * Carrying vectors rather than masks is what makes that multiplication
+         * exact — a mask would have to be upsampled, and an upsampled mask has
+         * stair-steps the blade would trace.
+         */
+        sourceScale: sourceWidth && raster.width > 0 ? sourceWidth / raster.width : 1,
+    };
+}

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

@@ -0,0 +1,11 @@
+import type { CutPath, Point } from "../types";
+/**
+ * Fit a closed cubic path through `points`.
+ *
+ * Closed only — a kiss cut is always a closed outline, and an open path would
+ * mean a sticker the machine cuts most of the way around and leaves attached.
+ * The wrap-around indexing is what makes the seam between the last and first
+ * point as smooth as every other joint; fitting open and then closing the gap
+ * leaves a visible corner exactly where the path started.
+ */
+export declare function catmullRomToBezier(points: readonly Point[]): CutPath | null;

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

@@ -0,0 +1,66 @@
+/*
+ * WHY: A simplified polyline is still a polyline, and a blade cutting one
+ *      chatters audibly on every curve — these stickers are almost entirely
+ *      curves. Fitting smooth cubics through the simplified points is what
+ *      turns a traced raster into something a cutter follows cleanly.
+ * WHAT: Uniform Catmull-Rom through the points, converted to cubic Béziers,
+ *       with the control-arm clamp that keeps sharp corners from looping.
+ *
+ * EXPORTS: catmullRomToBezier
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:geometry,export/*
+ * @tag sideEffects:none
+ */
+/**
+ * Cap a control arm's length.
+ *
+ * 🛑 This is not a refinement, it is a correctness fix. Uniform Catmull-Rom
+ * overshoots badly when neighbouring segments differ in length: at a sharp
+ * corner — which every claw-shaped sticker on these sheets has — the arm grows
+ * longer than the segment itself and the curve ties a small loop. A blade cuts
+ * that loop as a nick in the sticker's edge.
+ *
+ * Capping at a third of the span is the standard guard and leaves collinear
+ * runs perfectly straight, so nothing is lost on the flat sections.
+ */
+function clampArm(vx, vy, limit) {
+    const len = Math.hypot(vx, vy);
+    if (len <= limit || len === 0)
+        return { x: vx, y: vy };
+    const s = limit / len;
+    return { x: vx * s, y: vy * s };
+}
+/**
+ * Fit a closed cubic path through `points`.
+ *
+ * Closed only — a kiss cut is always a closed outline, and an open path would
+ * mean a sticker the machine cuts most of the way around and leaves attached.
+ * The wrap-around indexing is what makes the seam between the last and first
+ * point as smooth as every other joint; fitting open and then closing the gap
+ * leaves a visible corner exactly where the path started.
+ */
+export function catmullRomToBezier(points) {
+    const n = points.length;
+    if (n < 3)
+        return null;
+    const segments = [];
+    for (let i = 0; i < n; i++) {
+        const p0 = points[(i - 1 + n) % n];
+        const p1 = points[i];
+        const p2 = points[(i + 1) % n];
+        const p3 = points[(i + 2) % n];
+        const span = Math.hypot(p2.x - p1.x, p2.y - p1.y) / 3;
+        const a1 = clampArm((p2.x - p0.x) / 6, (p2.y - p0.y) / 6, span);
+        const a2 = clampArm((p3.x - p1.x) / 6, (p3.y - p1.y) / 6, span);
+        segments.push({
+            c1: { x: p1.x + a1.x, y: p1.y + a1.y },
+            c2: { x: p2.x - a2.x, y: p2.y - a2.y },
+            to: { x: p2.x, y: p2.y },
+        });
+    }
+    return { start: points[0], segments };
+}

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

@@ -0,0 +1,27 @@
+/**
+ * Squared Euclidean distance from every pixel to the nearest `true` in `mask`.
+ *
+ * Squared because that is what the algorithm computes natively and because
+ * every caller that only needs a comparison (`is this within r?`) can compare
+ * against r*r and skip ~9 million square roots on a 3000px raster.
+ */
+export declare function edtSquared(mask: Uint8Array, width: number, height: number): Float32Array;
+/** Euclidean distance in pixels. Prefer {@link edtSquared} when comparing. */
+export declare function edt(mask: Uint8Array, width: number, height: number): Float32Array;
+export interface EdtIndices {
+    /** Squared distance to the nearest seed. */
+    readonly dist: Float32Array;
+    /** Flat index (y * width + x) of that nearest seed. */
+    readonly index: Int32Array;
+}
+/**
+ * Distance transform that also reports the nearest seed's index.
+ *
+ * The de-halo pass needs this rather than the distance: it repaints the bleed
+ * ring with the colour of the nearest INTERIOR pixel, so it has to know which
+ * pixel that was. Tracking the argmin through both passes is why this is a
+ * separate function — carrying it costs an extra Int32Array and a second
+ * envelope evaluation, which the three callers that only want distance should
+ * not pay.
+ */
+export declare function edtWithIndices(mask: Uint8Array, width: number, height: number): EdtIndices;

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

@@ -0,0 +1,165 @@
+/*
+ * WHY: Four separate things this tracer does are the same operation underneath —
+ *      morphological dilate/erode by a true disc, the bleed ring, pushing solid
+ *      colour outward into that ring, and measuring a sticker's narrowest neck.
+ *      All four are "distance to the nearest set pixel", so there is one exact
+ *      distance transform rather than four approximations.
+ * WHAT: Felzenszwalb & Huttenlocher's exact Euclidean distance transform, O(n)
+ *       per row and column, plus a variant that also reports WHICH seed pixel
+ *       was nearest (the de-halo pass needs the index, not the distance).
+ *
+ * Exact matters here. A chamfer/approximate transform is off by a few percent,
+ * which is invisible on a screen and is a real error on a 0.4 mm bleed ring —
+ * and it rounds corners anisotropically, so a dilated outline comes out
+ * subtly faceted in a way a blade traces.
+ *
+ * EXPORTS: edtSquared, edt, edtWithIndices
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:morphology,geometry,dehalo,segment
+ * @tag sideEffects:none
+ */
+const INF = 1e20;
+/**
+ * Lower envelope of parabolas along one axis.
+ *
+ * `f` is the squared-distance cost at each position, `d` receives the result.
+ * `v` (parabola vertices) and `z` (intersection boundaries) are scratch buffers
+ * owned by the caller so the 2-D driver allocates them once rather than once
+ * per row — on a 3000px raster that is the difference between 3000 small
+ * allocations and none.
+ */
+function lowerEnvelope(f, d, v, z, n) {
+    let k = 0;
+    v[0] = 0;
+    z[0] = -INF;
+    z[1] = INF;
+    for (let q = 1; q < n; q++) {
+        // Intersection of the parabola at q with the one currently on top.
+        let s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        while (s <= z[k]) {
+            k--;
+            s = (f[q] + q * q - (f[v[k]] + v[k] * v[k])) / (2 * q - 2 * v[k]);
+        }
+        k++;
+        v[k] = q;
+        z[k] = s;
+        z[k + 1] = INF;
+    }
+    k = 0;
+    for (let q = 0; q < n; q++) {
+        while (z[k + 1] < q)
+            k++;
+        const dx = q - v[k];
+        d[q] = dx * dx + f[v[k]];
+    }
+}
+/**
+ * Squared Euclidean distance from every pixel to the nearest `true` in `mask`.
+ *
+ * Squared because that is what the algorithm computes natively and because
+ * every caller that only needs a comparison (`is this within r?`) can compare
+ * against r*r and skip ~9 million square roots on a 3000px raster.
+ */
+export function edtSquared(mask, width, height) {
+    const out = new Float32Array(width * height);
+    const maxDim = Math.max(width, height);
+    const f = new Float64Array(maxDim);
+    const d = new Float64Array(maxDim);
+    const v = new Int32Array(maxDim);
+    const z = new Float64Array(maxDim + 1);
+    // Columns first.
+    for (let x = 0; x < width; x++) {
+        for (let y = 0; y < height; y++) {
+            f[y] = mask[y * width + x] ? 0 : INF;
+        }
+        lowerEnvelope(f, d, v, z, height);
+        for (let y = 0; y < height; y++) {
+            out[y * width + x] = d[y];
+        }
+    }
+    // Then rows, over the column result.
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            f[x] = out[row + x];
+        }
+        lowerEnvelope(f, d, v, z, width);
+        for (let x = 0; x < width; x++) {
+            out[row + x] = d[x];
+        }
+    }
+    return out;
+}
+/** Euclidean distance in pixels. Prefer {@link edtSquared} when comparing. */
+export function edt(mask, width, height) {
+    const sq = edtSquared(mask, width, height);
+    for (let i = 0; i < sq.length; i++)
+        sq[i] = Math.sqrt(sq[i]);
+    return sq;
+}
+/**
+ * Distance transform that also reports the nearest seed's index.
+ *
+ * The de-halo pass needs this rather than the distance: it repaints the bleed
+ * ring with the colour of the nearest INTERIOR pixel, so it has to know which
+ * pixel that was. Tracking the argmin through both passes is why this is a
+ * separate function — carrying it costs an extra Int32Array and a second
+ * envelope evaluation, which the three callers that only want distance should
+ * not pay.
+ */
+export function edtWithIndices(mask, width, height) {
+    const dist = new Float32Array(width * height);
+    const index = new Int32Array(width * height);
+    const maxDim = Math.max(width, height);
+    const f = new Float64Array(maxDim);
+    const d = new Float64Array(maxDim);
+    const v = new Int32Array(maxDim);
+    const z = new Float64Array(maxDim + 1);
+    // Nearest source position along the axis currently being processed.
+    const srcAxis = new Int32Array(maxDim);
+    // The y the column pass settled on, carried into the row pass.
+    const colSrcY = new Int32Array(width * height);
+    for (let x = 0; x < width; x++) {
+        for (let y = 0; y < height; y++) {
+            f[y] = mask[y * width + x] ? 0 : INF;
+        }
+        lowerEnvelope(f, d, v, z, height);
+        // Re-walk the envelope to recover which vertex each position resolved to.
+        let k = 0;
+        for (let y = 0; y < height; y++) {
+            while (z[k + 1] < y)
+                k++;
+            srcAxis[y] = v[k];
+        }
+        for (let y = 0; y < height; y++) {
+            dist[y * width + x] = d[y];
+            colSrcY[y * width + x] = srcAxis[y];
+        }
+    }
+    for (let y = 0; y < height; y++) {
+        const row = y * width;
+        for (let x = 0; x < width; x++) {
+            f[x] = dist[row + x];
+        }
+        lowerEnvelope(f, d, v, z, width);
+        let k = 0;
+        for (let x = 0; x < width; x++) {
+            while (z[k + 1] < x)
+                k++;
+            srcAxis[x] = v[k];
+        }
+        for (let x = 0; x < width; x++) {
+            const srcX = srcAxis[x];
+            dist[row + x] = d[x];
+            // The seed is at (srcX, the y the COLUMN pass chose for srcX) — not at
+            // (srcX, y). Reading the current row here is the classic way to get a
+            // plausible-looking but wrong nearest-neighbour field.
+            index[row + x] = colSrcY[row + srcX] * width + srcX;
+        }
+    }
+    return { dist, index };
+}

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

@@ -0,0 +1,15 @@
+import type { Rect } from "../types";
+export interface ComponentStats {
+    readonly label: number;
+    readonly area: number;
+    readonly bbox: Rect;
+    /** True when the component touches the raster edge — see trace/segment. */
+    readonly touchesBorder: boolean;
+}
+export interface LabelResult {
+    /** 0 = background; components are 1..count. */
+    readonly labels: Int32Array;
+    readonly count: number;
+    readonly stats: readonly ComponentStats[];
+}
+export declare function labelComponents(mask: Uint8Array, width: number, height: number): LabelResult;