tapirscan 1.0.0

package/dist/detail-20260914/scanner.mjs

@@ -0,0 +1,64 @@
+import { IndependentScanner } from "./host.mjs";
+import { evidencePlan } from "./source-evidence.mjs";
+import { recoverDirectSeed } from "./direct-recovery.mjs";
+/** Workbench composition. Each crop keeps its own candidate-index namespace. */
+export class DetailScanner {
+    constructor(primary, recovery, directions) {
+        this.primary = primary;
+        this.recovery = recovery;
+        this.directions = directions;
+    }
+    static async create(primaryBytes, recoveryBytes, directions) {
+        if (![1, 2, 3].includes(directions))
+            throw new Error("Invalid recovery direction budget");
+        const primary = await IndependentScanner.create(primaryBytes);
+        try {
+            return new DetailScanner(primary, await IndependentScanner.create(recoveryBytes), directions);
+        }
+        catch (error) {
+            primary.dispose();
+            throw error;
+        }
+    }
+    scanLocalized(image, policy, fitLimit, fullFrame) {
+        // The source samplers use tightly packed RGBA, as supplied by the camera worker.
+        if (image.channels !== 4 || image.stride !== image.width * 4)
+            throw new Error("Detail discovery requires tightly packed RGBA");
+        const start = performance.now();
+        const found = this.primary.scanLocalized(image, policy, fitLimit, fullFrame, (localization) => evidencePlan(image, localization, 48));
+        const recovery = recoverDirectSeed(image, this.recovery, policy, found, 64, 3, true, true, 1, this.directions);
+        return {
+            ...found,
+            // Do not concatenate crop-local candidate indices into the primary frame.
+            // Consumers use detailRegions; raw frames and coordinate transforms stay inspectable.
+            recovery,
+            detailRegions: detailRegions(found, recovery),
+            scanMs: performance.now() - start,
+        };
+    }
+    dispose() {
+        this.primary.dispose();
+        this.recovery.dispose();
+    }
+}
+/** Preserve undecoded geometry without assigning crop indices to primary proposals. */
+export function detailRegions(found, recovery) {
+    const decoded = new Set(found.scan.barcodes.flatMap((barcode) => barcode.candidate_indices));
+    const regions = recovery.barcodes.map((barcode) => ({
+        text: barcode.text,
+        polygon: barcode.polygon,
+        support: barcode.support,
+    }));
+    found.localization.proposals.forEach((proposal, index) => {
+        if (!decoded.has(index))
+            regions.push({ text: "", polygon: proposal.polygon, score: proposal.score });
+    });
+    for (const attempt of recovery.attempts) {
+        const accepted = new Set(attempt.reads.flatMap((barcode) => barcode.candidate_indices));
+        attempt.proposals.forEach((proposal, index) => {
+            if (!accepted.has(index))
+                regions.push({ text: "", polygon: proposal.polygon, score: proposal.score });
+        });
+    }
+    return regions;
+}

package/dist/detail-20260914/source-evidence.d.mts

@@ -0,0 +1,10 @@
+/** Cheap alternating-run evidence. It prioritizes geometry, never accepts digits. */
+export function sourceEvidence(image: any, polygon: any, local?: boolean, target?: number): {
+    transitions: number;
+    localTransitions: number;
+    rows: number;
+    contrast: number;
+};
+export function evidenceFilter(image: any, localization: any, minimum?: number): any;
+/** Retain all candidates. Evidence stops once eligibility is established; counts are lower bounds. */
+export function evidencePlan(image: any, localization: any, minimum?: number): any;

package/dist/detail-20260914/source-evidence.mjs

@@ -0,0 +1,94 @@
+/** Cheap alternating-run evidence. It prioritizes geometry, never accepts digits. */
+export function sourceEvidence(image, polygon, local = false, target = Infinity) {
+    const { data, width, height } = image;
+    const gray = (x, y) => {
+        x = Math.max(0, Math.min(width - 1, x));
+        y = Math.max(0, Math.min(height - 1, y));
+        const x0 = Math.floor(x), y0 = Math.floor(y), x1 = Math.min(width - 1, x0 + 1), y1 = Math.min(height - 1, y0 + 1), fx = x - x0, fy = y - y0;
+        const v = (a, b) => {
+            const i = (b * width + a) * 4;
+            return (77 * data[i] + 150 * data[i + 1] + 29 * data[i + 2]) / 256;
+        };
+        return ((v(x0, y0) * (1 - fx) + v(x1, y0) * fx) * (1 - fy) +
+            (v(x0, y1) * (1 - fx) + v(x1, y1) * fx) * fy);
+    };
+    let best = 0, localBest = 0, rows = 0, contrast = 0;
+    for (let axis = 0; axis < 2; axis++)
+        for (const f of [0.2, 0.4, 0.6, 0.8]) {
+            const a = polygon[axis], b = polygon[(axis + 1) % 4], c = polygon[(axis + 2) % 4], d = polygon[(axis + 3) % 4];
+            const p = [a[0] * (1 - f) + d[0] * f, a[1] * (1 - f) + d[1] * f], q = [b[0] * (1 - f) + c[0] * f, b[1] * (1 - f) + c[1] * f];
+            const n = Math.min(2048, Math.max(64, Math.ceil(Math.hypot(q[0] - p[0], q[1] - p[1]) * 1.25)));
+            const samples = new Float32Array(n);
+            let lo = 255, hi = 0;
+            for (let i = 0; i < n; i++) {
+                const t = -0.125 + (1.25 * i) / (n - 1), v = gray(p[0] + (q[0] - p[0]) * t, p[1] + (q[1] - p[1]) * t);
+                samples[i] = v;
+                lo = Math.min(lo, v);
+                hi = Math.max(hi, v);
+            }
+            contrast = Math.max(contrast, hi - lo);
+            if (hi - lo < (local ? 12 : 20))
+                continue;
+            const threshold = (lo + hi) / 2, hysteresis = (hi - lo) * 0.06;
+            let state = samples[0] > threshold, runs = 0;
+            for (const v of samples) {
+                if (state ? v < threshold - hysteresis : v > threshold + hysteresis) {
+                    state = !state;
+                    runs++;
+                }
+            }
+            best = Math.max(best, runs);
+            if (runs >= 20)
+                rows++;
+            if (best >= target)
+                return { transitions: best, localTransitions: localBest, rows, contrast };
+            if (local) {
+                const sum = new Float64Array(n + 1);
+                for (let i = 0; i < n; i++)
+                    sum[i + 1] = sum[i] + samples[i];
+                let previous, localRuns = 0;
+                for (let i = 0; i < n; i++) {
+                    const left = Math.max(0, i - 8), right = Math.min(n, i + 9), mean = (sum[right] - sum[left]) / (right - left);
+                    const next = samples[i] > mean + 2 ? true : samples[i] < mean - 2 ? false : undefined;
+                    if (next !== undefined) {
+                        if (previous !== undefined && previous !== next)
+                            localRuns++;
+                        previous = next;
+                    }
+                }
+                localBest = Math.max(localBest, localRuns);
+                if (localBest >= target)
+                    return { transitions: best, localTransitions: localBest, rows, contrast };
+            }
+        }
+    return { transitions: best, localTransitions: localBest, rows, contrast };
+}
+export function evidenceFilter(image, localization, minimum = 20) {
+    const ranked = localization.proposals.map((p) => ({
+        ...p,
+        evidence: sourceEvidence(image, p.polygon),
+    }));
+    const proposals = ranked.filter((p) => p.evidence.transitions >= minimum), deferred = ranked.filter((p) => p.evidence.transitions < minimum);
+    return {
+        ...localization,
+        proposals,
+        deferred,
+        workLimited: localization.workLimited || deferred.length > 0,
+    };
+}
+/** Retain all candidates. Evidence stops once eligibility is established; counts are lower bounds. */
+export function evidencePlan(image, localization, minimum = 20) {
+    const proposals = localization.proposals.map((p) => ({
+        ...p,
+        evidence: sourceEvidence(image, p.polygon, false, minimum),
+    }));
+    const masks = [0, 0];
+    proposals.forEach((p, i) => {
+        if (p.evidence.transitions >= minimum)
+            masks[i >>> 5] |= 1 << (i & 31);
+    });
+    const fullFrame = proposals.length;
+    if (fullFrame < 64)
+        masks[fullFrame >>> 5] |= 1 << (fullFrame & 31);
+    return { ...localization, proposals, retryMask: masks.map((x) => x >>> 0) };
+}

package/dist/detail-canvas.d.ts

@@ -0,0 +1,35 @@
+/** Canvas interpolation in browsers; deterministic bilinear RGB interpolation in Node. */
+interface Pixels {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+export declare function makeCanvas(width: number, height: number): {
+    width: number;
+    height: number;
+    getContext(): {
+        imageSmoothingEnabled: boolean;
+        putImageData(value: Pixels): void;
+        getImageData(): Pixels;
+        drawImage(source: {
+            getContext(): {
+                getImageData(): Pixels;
+            };
+        }, _x: number, _y: number, w: number, h: number): void;
+    };
+} | {
+    width: number;
+    height: number;
+    native: OffscreenCanvas;
+    getContext(_kind: string, options?: {
+        willReadFrequently?: boolean;
+    }): {
+        imageSmoothingEnabled: boolean;
+        putImageData(pixels: Pixels, x: number, y: number): void;
+        drawImage(source: {
+            native: OffscreenCanvas;
+        }, x: number, y: number, w: number, h: number): void;
+        getImageData(x: number, y: number, w: number, h: number): ImageData;
+    };
+};
+export {};

package/dist/detail-canvas.js

@@ -0,0 +1,73 @@
+export function makeCanvas(width, height) {
+    if (typeof OffscreenCanvas !== "undefined") {
+        const canvas = new OffscreenCanvas(width, height);
+        return {
+            get width() {
+                return canvas.width;
+            },
+            set width(value) {
+                canvas.width = value;
+            },
+            get height() {
+                return canvas.height;
+            },
+            set height(value) {
+                canvas.height = value;
+            },
+            native: canvas,
+            getContext(_kind, options) {
+                const context = canvas.getContext("2d", options);
+                if (!context)
+                    throw Error("Could not create recovery canvas");
+                return {
+                    imageSmoothingEnabled: true,
+                    putImageData(pixels, x, y) {
+                        context.putImageData(new ImageData(new Uint8ClampedArray(pixels.data), pixels.width, pixels.height), x, y);
+                    },
+                    drawImage(source, x, y, w, h) {
+                        context.imageSmoothingEnabled = true;
+                        context.drawImage(source.native, x, y, w, h);
+                    },
+                    getImageData(x, y, w, h) {
+                        return context.getImageData(x, y, w, h);
+                    },
+                };
+            },
+        };
+    }
+    let pixels = { data: new Uint8ClampedArray(), width, height };
+    const canvas = {
+        width,
+        height,
+        getContext() {
+            return {
+                imageSmoothingEnabled: true,
+                putImageData(value) {
+                    pixels = value;
+                },
+                getImageData() {
+                    return pixels;
+                },
+                drawImage(source, _x, _y, w, h) {
+                    const input = source.getContext().getImageData();
+                    const data = new Uint8ClampedArray(w * h * 4);
+                    for (let y = 0; y < h; y++) {
+                        const sy = Math.max(0, Math.min(input.height - 1, ((y + 0.5) * input.height) / h - 0.5));
+                        const y0 = Math.floor(sy), y1 = Math.min(input.height - 1, y0 + 1), fy = sy - y0;
+                        for (let x = 0; x < w; x++) {
+                            const sx = Math.max(0, Math.min(input.width - 1, ((x + 0.5) * input.width) / w - 0.5));
+                            const x0 = Math.floor(sx), x1 = Math.min(input.width - 1, x0 + 1), fx = sx - x0;
+                            for (let c = 0; c < 4; c++) {
+                                const a = input.data[(y0 * input.width + x0) * 4 + c], b = input.data[(y0 * input.width + x1) * 4 + c];
+                                const d = input.data[(y1 * input.width + x0) * 4 + c], e = input.data[(y1 * input.width + x1) * 4 + c];
+                                data[(y * w + x) * 4 + c] = Math.round((a * (1 - fx) + b * fx) * (1 - fy) + (d * (1 - fx) + e * fx) * fy);
+                            }
+                        }
+                    }
+                    pixels = { data, width: w, height: h };
+                },
+            };
+        },
+    };
+    return canvas;
+}

package/dist/detail.d.ts

@@ -0,0 +1,19 @@
+import { type DetailResult } from "./detail-20260914/scanner.mjs";
+import { IndependentScanner, type Image, type ScanFrame } from "./host.js";
+import type { Mode } from "./index.js";
+export declare const fitLimits: {
+    readonly low: 0;
+    readonly medium: 1;
+    readonly high: 4;
+    readonly "very-high": 1;
+};
+/** Flatten decoded outputs only; retain crop-local evidence in recovery.attempts. */
+export declare class ReleaseDetailScanner {
+    private readonly scanner;
+    private disposed;
+    private constructor();
+    static create(primary: ArrayBuffer, low: ArrayBuffer, mode: Exclude<Mode, "low">): Promise<ReleaseDetailScanner>;
+    scanLocalized(image: Image, policy: Parameters<IndependentScanner["scanLocalized"]>[1], fit: number, full: boolean): DetailResult;
+    best(frame: ScanFrame): import("./host.js").Barcode | undefined;
+    dispose(): void;
+}

package/dist/detail.js

@@ -0,0 +1,87 @@
+import { DetailScanner } from "./detail-20260914/scanner.mjs";
+export const fitLimits = { low: 0, medium: 1, high: 4, "very-high": 1 };
+/** Preserve the public gray/RGB/RGBA and padded-stride image contract. */
+function packed(image) {
+    if (
+    // Runtime callers can bypass the TypeScript image contract.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    !image ||
+        !Number.isSafeInteger(image.width) ||
+        !Number.isSafeInteger(image.height) ||
+        image.width < 3 ||
+        image.height < 3 ||
+        image.width * image.height > 32 * 1024 * 1024 ||
+        ![1, 3, 4].includes(image.channels) ||
+        !Number.isSafeInteger(image.stride) ||
+        image.stride < image.width * image.channels ||
+        !(image.data instanceof Uint8Array) ||
+        image.data.length < (image.height - 1) * image.stride + image.width * image.channels)
+        throw Error("Invalid image dimensions or buffer");
+    if (image.channels === 4 && image.stride === image.width * 4) {
+        let opaque = true;
+        for (let i = 3; i < image.width * image.height * 4; i += 4) {
+            if (image.data[i] !== 255) {
+                opaque = false;
+                break;
+            }
+        }
+        if (opaque)
+            return image;
+    }
+    const data = new Uint8Array(image.width * image.height * 4);
+    for (let y = 0; y < image.height; y++)
+        for (let x = 0; x < image.width; x++) {
+            const src = y * image.stride + x * image.channels, dst = (y * image.width + x) * 4;
+            data[dst] = image.data[src];
+            data[dst + 1] = image.data[src + (image.channels === 1 ? 0 : 1)];
+            data[dst + 2] = image.data[src + (image.channels === 1 ? 0 : 2)];
+            data[dst + 3] = 255;
+        }
+    return { data, width: image.width, height: image.height, channels: 4, stride: image.width * 4 };
+}
+/** Flatten decoded outputs only; retain crop-local evidence in recovery.attempts. */
+export class ReleaseDetailScanner {
+    scanner;
+    disposed = false;
+    constructor(scanner) {
+        this.scanner = scanner;
+    }
+    static async create(primary, low, mode) {
+        return new ReleaseDetailScanner(await DetailScanner.create(primary, low, mode === "medium" ? 1 : 2));
+    }
+    scanLocalized(image, policy, fit, full) {
+        if (this.disposed)
+            throw Error("Scanner is disposed");
+        const result = this.scanner.scanLocalized(packed(image), policy ?? {}, fit, full);
+        const primaryCount = result.scan.barcodes.length;
+        const barcodes = result.recovery.barcodes.map((b, i) => i < primaryCount ? b : { ...b, candidate_indices: [] });
+        const localization = result.localization;
+        return {
+            ...result,
+            localization: {
+                ...localization,
+                proposals: localization.proposals.map((p) => ({
+                    polygon: p.polygon,
+                    score: p.score,
+                    text: p.text,
+                })),
+            },
+            scan: {
+                ...result.scan,
+                barcodes,
+                unfinished: result.scan.unfinished ||
+                    result.recovery.searchLimited ||
+                    result.recovery.attempts.some((a) => a.unfinished),
+            },
+        };
+    }
+    best(frame) {
+        return frame.barcodes.reduce((best, b) => (!best || b.support > best.support ? b : best), undefined);
+    }
+    dispose() {
+        if (!this.disposed) {
+            this.scanner.dispose();
+            this.disposed = true;
+        }
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,112 @@
+/** Independent EAN-13 supplied-region scanner. Experimental; no localizer or
+ * reference decoder is imported. All result confidence remains uncalibrated. */
+export type Point = readonly [number, number];
+export type Quad = readonly [Point, Point, Point, Point];
+export interface Image {
+    data: Uint8Array;
+    width: number;
+    height: number;
+    channels: 1 | 3 | 4;
+    stride: number;
+}
+export interface Policy {
+    transitionCleanup?: boolean;
+    sourceIdentity?: boolean;
+    interiorNormalization?: boolean;
+    guardBias?: boolean;
+    /** Experimental: accept one full-quiet scanline; increases false-read risk. Default false. */
+    allowSingleRow?: boolean;
+    maxRetryPathsPerCandidate?: number;
+    maxRetryPathsPerFrame?: number;
+    maxAssociationChecks?: number;
+    maxAssociationPixels?: number;
+    maxResults?: number;
+}
+export interface Detection {
+    text: string;
+    polygon: Quad;
+    support: number;
+    axis: number;
+}
+export interface Barcode extends Detection {
+    candidate_indices: number[];
+}
+export interface Observation {
+    text: string;
+    axis: number;
+    fraction: number;
+    left: number;
+    right: number;
+    cost: number;
+    gap: number;
+}
+export interface Candidate {
+    candidate_index: number;
+    coverage: readonly (readonly [number | null, number | null])[];
+    error: boolean;
+    error_detail: 'invalid_geometry' | 'sampling_error' | null;
+    unfinished: boolean;
+    ms: number;
+    work: Record<string, number>;
+    detections: Detection[];
+    observations: Observation[];
+}
+export interface ScanFrame {
+    unfinished: boolean;
+    candidates: Candidate[];
+    barcodes: Barcode[];
+    reconciliation: {
+        comparisons: number;
+        merged: number;
+        ambiguous: number;
+        conflicting: number;
+        pending_observations: number;
+        truncated: boolean;
+        source_pairs: number;
+        source_matches: number;
+        source_pixels: number;
+        source_capped: number;
+        pending_coverage_checks: number;
+        pending_quarantined: number;
+    };
+}
+export interface ScanResult extends ScanFrame {
+    /** This WASM build has no internal clock. Candidate ms values are unavailable zeros. */
+    candidateTimingsAvailable: false;
+    /** Actual host wall time, including validation, preparation/copies, decode and JSON parsing. */
+    elapsedMs: number;
+}
+/** Explicit indices reject sparse arrays; nonfinite numeric geometry reaches Rust. */
+export declare function isQuadShape(value: unknown): value is Quad;
+export declare class ScannerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Validate before asynchronous work; returned bytes are owned by the caller. */
+export declare function snapshotImage(image: Image): Image;
+export declare function snapshotPolicy(policy: Policy): Policy;
+/** Uncalibrated support ordering; ties preserve spatial output order. */
+export declare function rankBarcodes(barcodes: readonly Barcode[]): Barcode[];
+export declare class IndependentScanner {
+    #private;
+    private constructor();
+    static create(bytes: BufferSource): Promise<IndependentScanner>;
+    /** All supplied regions receive the cheap pass; successful reads do not end scanning. */
+    scan(image: Image, quads: readonly Quad[], policy?: Policy): ScanResult;
+    /** Synchronous transaction: upload once, localize, decode the same owned pixels. */
+    scanLocalized(image: Image, policy?: Policy, fitLimit?: number, fullFrame?: boolean): {
+        localization: any;
+        searchWindows: {
+            kind: string;
+            polygon: number[][];
+            candidateIndex: any;
+        }[];
+        scan: ScanResult;
+        localizationMs: number;
+        decodingMs: number;
+        scanMs: number;
+    };
+    /** Separate convenience; it never changes find-all work or suppresses frame evidence. */
+    best(result: ScanFrame): Barcode | undefined;
+    dispose(): void;
+}