@mohasinac/appkit 4.52.4 → 4.53.0

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

@@ -0,0 +1,125 @@
+/*
+ * WHY: One of the nine reference scans is halftone-screened, and its cut-line
+ *      signal measured only ~3x the scan noise against 10-20x on the others.
+ *      The noise there is not random — it is a printing rosette, a regular
+ *      high-frequency pattern — and a ridge detector run on it finds the
+ *      rosette far more enthusiastically than the cut line.
+ * WHAT: Two prefilters that suppress that pattern without blurring the cut line
+ *       away with it.
+ *
+ * 🛑 Ordering is load-bearing: the prefilter must run BEFORE quantisation. A
+ * halftone rosette posterises into hundreds of speckle regions, and the colour
+ * channel then contributes noise rather than signal — making the fused map
+ * worse than not having the second channel at all.
+ *
+ * EXPORTS: toLuminance, medianFilter, bilateralFilter, applyPrefilter
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:ridge,quantise,segment
+ * @tag sideEffects:none
+ */
+/**
+ * Rec. 601 luma. The ridge detector works on a single channel because the
+ * emboss signature is a brightness doublet — it appears in all three channels
+ * at once, so running the detector three times would triple the cost to find
+ * the same edge.
+ */
+export function toLuminance(raster) {
+    const { width, height, data } = raster;
+    const out = new Float32Array(width * height);
+    for (let i = 0, p = 0; i < out.length; i++, p += 4) {
+        out[i] = 0.299 * data[p] + 0.587 * data[p + 1] + 0.114 * data[p + 2];
+    }
+    return out;
+}
+/**
+ * Median over a (2r+1)^2 window.
+ *
+ * Median rather than mean because a rosette is an impulse pattern: the mean of
+ * a dot and its surround is a grey that still carries the dot's energy, while
+ * the median discards it outright. The cut line survives because it is a
+ * CONTINUOUS feature — more than half the window sits on it when the window is
+ * centred there — which is precisely the property a median preserves and a
+ * blur does not.
+ */
+export function medianFilter(src, width, height, radius) {
+    if (radius < 1)
+        return src.slice();
+    const out = new Float32Array(src.length);
+    const size = (radius * 2 + 1) ** 2;
+    const buf = new Float32Array(size);
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            let n = 0;
+            for (let dy = -radius; dy <= radius; dy++) {
+                const sy = Math.min(height - 1, Math.max(0, y + dy));
+                for (let dx = -radius; dx <= radius; dx++) {
+                    const sx = Math.min(width - 1, Math.max(0, x + dx));
+                    buf[n++] = src[sy * width + sx];
+                }
+            }
+            const slice = buf.subarray(0, n);
+            slice.sort();
+            out[y * width + x] = slice[n >> 1];
+        }
+    }
+    return out;
+}
+/**
+ * Edge-preserving smoothing: weight neighbours by both distance and intensity
+ * similarity.
+ *
+ * This is the `precise`/`max` choice because it suppresses the rosette like a
+ * blur while refusing to average across a step — and the cut line IS a step.
+ * A plain Gaussian at the radius needed to kill a rosette also halves the
+ * doublet amplitude, which on the ~3x scan is the whole signal.
+ */
+export function bilateralFilter(src, width, height, radius, sigmaSpace = radius, sigmaRange = 12) {
+    if (radius < 1)
+        return src.slice();
+    const out = new Float32Array(src.length);
+    const spatial = new Float32Array((radius * 2 + 1) ** 2);
+    const ds = 2 * sigmaSpace * sigmaSpace;
+    let k = 0;
+    for (let dy = -radius; dy <= radius; dy++) {
+        for (let dx = -radius; dx <= radius; dx++) {
+            spatial[k++] = Math.exp(-(dx * dx + dy * dy) / ds);
+        }
+    }
+    const dr = 2 * sigmaRange * sigmaRange;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const centre = src[y * width + x];
+            let acc = 0;
+            let weight = 0;
+            let w = 0;
+            for (let dy = -radius; dy <= radius; dy++) {
+                const sy = Math.min(height - 1, Math.max(0, y + dy));
+                for (let dx = -radius; dx <= radius; dx++) {
+                    const sx = Math.min(width - 1, Math.max(0, x + dx));
+                    const v = src[sy * width + sx];
+                    const diff = v - centre;
+                    const g = spatial[w++] * Math.exp(-(diff * diff) / dr);
+                    acc += v * g;
+                    weight += g;
+                }
+            }
+            out[y * width + x] = weight > 0 ? acc / weight : centre;
+        }
+    }
+    return out;
+}
+export function applyPrefilter(luma, width, height, kind, radius) {
+    switch (kind) {
+        case "median":
+            return medianFilter(luma, width, height, radius);
+        case "bilateral":
+            return bilateralFilter(luma, width, height, radius);
+        case "none":
+        default:
+            return luma;
+    }
+}

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

@@ -0,0 +1,10 @@
+import type { DecodedRaster } from "../types";
+export interface QuantiseResult {
+    /** Palette index per pixel. */
+    readonly labels: Int32Array;
+    /** 1 where the label differs from a 4-neighbour — i.e. a region boundary. */
+    readonly boundary: Uint8Array;
+    readonly paletteSize: number;
+    readonly coverage: number;
+}
+export declare function quantiseBoundaries(raster: DecodedRaster, colours: number): QuantiseResult;

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

@@ -0,0 +1,153 @@
+/*
+ * WHY: The ridge detector reads ONE signal — the emboss doublet a kiss cut
+ *      leaves in the sheet. On the halftone-screened scan that signal measured
+ *      only ~3x the noise, against 10-20x everywhere else. A second, INDEPENDENT
+ *      signal is what rescues that case, and colour is independent: it fails
+ *      exactly where the ridge succeeds and succeeds exactly where it fails.
+ *
+ *        torch pegases  (red on red)   ridge +22 strong   colour: nothing
+ *        posiedon       (yellow/yellow) ridge -40/+27      colour: nothing
+ *        Spark_dragoon  (halftone)      ridge ~3x MARGINAL colour: strong
+ *                                       (green panel, yellow rect, purple grad)
+ *
+ * WHAT: Posterise to N colours, then mark pixels where the posterised label
+ *       changes — the boundaries between flat colour regions.
+ *
+ * 🛑 It must run AFTER the prefilter. A halftone rosette posterises into
+ * hundreds of speckle regions, and every speckle edge becomes a boundary — so
+ * un-prefiltered, this channel contributes noise rather than signal and makes
+ * the fused map WORSE than the ridge alone. That ordering is a named check in
+ * the corpus harness rather than a comment anyone can drift from.
+ *
+ * EXPORTS: QuantiseResult, quantiseBoundaries
+ *
+ * @tag domain:sticker-trace
+ * @tag layer:shared
+ * @tag pattern:none
+ * @tag access:isomorphic
+ * @tag consumers:fuse,segment
+ * @tag sideEffects:none
+ */
+/**
+ * Median-cut palette selection.
+ *
+ * k-means would fit the colours better and is the obvious reach, but it is
+ * iterative and its result depends on initialisation — so the same sheet traced
+ * twice could posterise differently and move a cut line. Median cut is
+ * deterministic and single-pass, which matters more here than palette fidelity:
+ * the palette is never rendered, only differenced.
+ */
+function medianCutPalette(data, sampleStride, targetColours) {
+    const pixels = [];
+    for (let p = 0; p < data.length; p += 4 * sampleStride) {
+        pixels.push([data[p], data[p + 1], data[p + 2]]);
+    }
+    if (pixels.length === 0)
+        return [[0, 0, 0]];
+    let buckets = [pixels];
+    while (buckets.length < targetColours) {
+        // Split the bucket with the widest channel range — the one carrying the
+        // most distinguishable colour, rather than simply the most pixels.
+        let widest = -1;
+        let widestRange = -1;
+        let widestChannel = 0;
+        for (let i = 0; i < buckets.length; i++) {
+            const bucket = buckets[i];
+            if (bucket.length < 2)
+                continue;
+            for (let c = 0; c < 3; c++) {
+                let min = 255;
+                let max = 0;
+                for (const px of bucket) {
+                    const v = px[c];
+                    if (v < min)
+                        min = v;
+                    if (v > max)
+                        max = v;
+                }
+                if (max - min > widestRange) {
+                    widestRange = max - min;
+                    widest = i;
+                    widestChannel = c;
+                }
+            }
+        }
+        if (widest < 0 || widestRange <= 0)
+            break;
+        const bucket = buckets[widest];
+        bucket.sort((a, b) => a[widestChannel] - b[widestChannel]);
+        const mid = bucket.length >> 1;
+        buckets = [
+            ...buckets.slice(0, widest),
+            bucket.slice(0, mid),
+            bucket.slice(mid),
+            ...buckets.slice(widest + 1),
+        ];
+    }
+    return buckets
+        .filter((b) => b.length > 0)
+        .map((b) => {
+        let r = 0;
+        let g = 0;
+        let bl = 0;
+        for (const px of b) {
+            r += px[0];
+            g += px[1];
+            bl += px[2];
+        }
+        return [r / b.length, g / b.length, bl / b.length];
+    });
+}
+export function quantiseBoundaries(raster, colours) {
+    const { width, height, data } = raster;
+    // Sample at most ~40k pixels to build the palette. Median cut sorts within
+    // buckets, so feeding it 9 million pixels costs far more than the palette's
+    // extra precision is worth when the output is a boolean boundary map.
+    const stride = Math.max(1, Math.floor((width * height) / 40000));
+    const palette = medianCutPalette(data, stride, colours);
+    const labels = new Int32Array(width * height);
+    for (let i = 0, p = 0; i < labels.length; i++, p += 4) {
+        const r = data[p];
+        const g = data[p + 1];
+        const b = data[p + 2];
+        let best = 0;
+        let bestDist = Infinity;
+        for (let k = 0; k < palette.length; k++) {
+            const c = palette[k];
+            const dr = r - c[0];
+            const dg = g - c[1];
+            const db = b - c[2];
+            const d = 2 * dr * dr + 4 * dg * dg + 3 * db * db;
+            if (d < bestDist) {
+                bestDist = d;
+                best = k;
+            }
+        }
+        labels[i] = best;
+    }
+    const boundary = new Uint8Array(width * height);
+    let set = 0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const i = y * width + x;
+            const l = labels[i];
+            // 4-neighbour only. An 8-neighbour test marks both sides of every
+            // diagonal step, doubling the width of a boundary that is supposed to be
+            // a hairline and smearing the fused barrier.
+            const differs = (x > 0 && labels[i - 1] !== l) ||
+                (x < width - 1 && labels[i + 1] !== l) ||
+                (y > 0 && labels[i - width] !== l) ||
+                (y < height - 1 && labels[i + width] !== l);
+            if (differs) {
+                boundary[i] = 1;
+                set++;
+            }
+        }
+    }
+    return {
+        labels,
+        boundary,
+        paletteSize: palette.length,
+        coverage: set / boundary.length,
+    };
+}

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

@@ -0,0 +1,88 @@
+export interface RidgeResult {
+    /** Continuous response, roughly in luminance units. */
+    readonly response: Float32Array;
+    /** 1 where a ridge survived hysteresis linking. */
+    readonly barrier: Uint8Array;
+    /** Fraction of pixels in `barrier`; a diagnostic, see TraceDiagnostics. */
+    readonly coverage: number;
+}
+/**
+ * Hysteresis against a LOCAL threshold rather than a global one.
+ *
+ * 🛑 This replaced both a fixed-value and a fixed-percentile threshold, and the
+ * measurements that killed each are worth keeping:
+ *
+ *   absolute (low=9, high=18)  — barrier coverage 34-61% across the corpus. The
+ *     median response spans 0.1 (Driger: clean paper) to 14.1 (Poseidon: JPEG
+ *     cream field), so one pair of numbers is simultaneously far too low for
+ *     one scan and far too high for another.
+ *   percentile (p60/p80)       — coverage pinned at ~38% on EVERY scan, which is
+ *     what a quantile does by construction rather than what a detector does.
+ *     Worse, Poseidon's cream-field cut line (response 12-16) fell below that
+ *     scan's own p60 and vanished completely.
+ *
+ * The second failure is the informative one: a response of 12-16 is plainly a
+ * line on a flat cream field and plainly noise inside dense artwork, so NO
+ * single global number can separate them. Significance is local, so the
+ * threshold is local — Niblack/Sauvola-style, `localMean + k * localStdDev`
+ * over a window much larger than a cut line but much smaller than a sticker.
+ *
+ * Both statistics come from box blurs (mean, and mean-of-squares for the
+ * variance), so the whole thing stays O(n) and independent of window size.
+ */
+/**
+ * Threshold ANY response field against its own robust local background.
+ *
+ * Exported because the art path feeds it a Hessian line response rather than
+ * this module's edge response — the thresholding policy (local, robust,
+ * hysteresis-linked) is right for both and must not be written twice.
+ */
+export declare function thresholdAdaptive(response: Float32Array, width: number, height: number, kLow: number, kHigh: number): Uint8Array;
+/**
+ * Detect cut lines.
+ *
+ * 🛑 Thresholds are PERCENTILES of this scan's own response, not absolute
+ * luminance values, and that is a measured correction rather than a
+ * preference. Across the reference corpus the median response spans two orders
+ * of magnitude — 0.1 on the Driger G sheet (clean white paper, almost no
+ * texture) against 14.1 on the Poseidon scan (JPEG, printed cream field) — so
+ * any fixed pair of numbers is simultaneously far too high for one scan and far
+ * too low for another. Measured with absolute low=9/high=18, barrier coverage
+ * came out between 34% and 61%, which floods nothing.
+ *
+ * The cut line is only ~2.8-3.2x the median on the two hardest sheets, so the
+ * separation that matters is NOT cut-line-versus-artwork — a logo edge is a
+ * genuine edge and will exceed a cut line. It is cut-line-versus-BACKGROUND.
+ * Interior artwork edges joining the barrier is harmless: the flood arrives
+ * from outside and is already stopped by the outer cut line before it can ever
+ * reach them.
+ *
+ * Three steps, each answering one objection to the previous:
+ *
+ *   1. DETREND. Subtract a large-window mean. Without this the detector sees
+ *      the airbrushed gradient under a sticker as a huge slow ramp and the cut
+ *      line as a rounding error on top of it. This is the step that exposed the
+ *      signal in the measurements above.
+ *   2. LOCAL RANGE. The doublet's signature is a trough and a ridge within a
+ *      pixel or two of each other, so the local max-minus-min of the detrended
+ *      field is large on a cut line and ~0 on flat ink. A plain gradient
+ *      magnitude fires equally on one-sided edges; the range specifically
+ *      rewards the paired shape an impression makes.
+ *   3. HYSTERESIS. Continuity beats amplitude — see above.
+ */
+export declare function detectRidges(luma: Float32Array, width: number, height: number, opts: {
+    /** Percentile in 0..1 for the grow threshold. */
+    low: number;
+    /** Percentile in 0..1 for the seed threshold. */
+    high: number;
+    kernelScale: number;
+    /** Escape hatch: absolute response values, bypassing the percentiles. */
+    absolute?: {
+        low: number;
+        high: number;
+    };
+    /** Independent second channel — see trace/quantise and trace/fuse. */
+    assist?: Uint8Array;
+    /** 0..1. How far the assist may lower the ridge's own bar. */
+    assistWeight?: number;
+}): RidgeResult;