tapirscan 1.0.0

package/dist/index.js

@@ -0,0 +1,199 @@
+import { ReleaseDetailScanner, fitLimits } from "./detail.js";
+import { policy } from "./policy.js";
+import { MediumMultiformatScanner } from "./multiformat/scanner.js";
+import { resolveFormats } from "./multiformat/formats.js";
+export { formatBits, linearFormats, matrixFormats, retailFormats } from "./multiformat/formats.js";
+import { IndependentScanner } from "./host.js";
+export { ScannerError } from "./host.js";
+function pixels(image) {
+    if ("channels" in image)
+        return image;
+    if (!(image.data instanceof Uint8ClampedArray))
+        throw new TypeError("Use ImageData or an explicit buffer with channels and stride");
+    return {
+        data: new Uint8Array(image.data.buffer, image.data.byteOffset, image.data.byteLength),
+        width: image.width,
+        height: image.height,
+        channels: 4,
+        stride: image.width * 4,
+    };
+}
+async function loadDefault(url) {
+    if (url.protocol === "file:") {
+        const nodeFs = "node:fs/promises";
+        const fs = (await import(/* @vite-ignore */ nodeFs));
+        return new Uint8Array(await fs.readFile(url)).buffer;
+    }
+    const response = await fetch(url);
+    if (!response.ok)
+        throw new Error(`WASM load failed: ${String(response.status)}`);
+    return response.arrayBuffer();
+}
+function publicResult(raw, image, debug) {
+    const barcodes = raw.scan.barcodes.map(({ text, format, polygon }) => {
+        const left = Math.floor(Math.min(...polygon.map((p) => p[0])));
+        const top = Math.floor(Math.min(...polygon.map((p) => p[1])));
+        return {
+            text,
+            format,
+            polygon,
+            rect: {
+                left,
+                top,
+                width: Math.ceil(Math.max(...polygon.map((p) => p[0]))) - left,
+                height: Math.ceil(Math.max(...polygon.map((p) => p[1]))) - top,
+            },
+        };
+    });
+    let bestIndex = -1;
+    for (let i = 0; i < barcodes.length; i++)
+        if (bestIndex < 0 || raw.scan.barcodes[i].support > raw.scan.barcodes[bestIndex].support)
+            bestIndex = i;
+    return {
+        barcodes,
+        values: barcodes.map((b) => b.text),
+        best: barcodes[bestIndex],
+        image: { width: image.width, height: image.height },
+        mode: raw.mode,
+        elapsedMs: raw.elapsedMs,
+        unfinished: raw.scan.unfinished,
+        ...(debug ? { debug: raw } : {}),
+    };
+}
+const modes = {
+    low: "low-release-20260915.wasm",
+    medium: "medium-release-20260915.wasm",
+    high: "high-release-20260915.wasm",
+    "very-high": "very-high-release-20260915.wasm",
+};
+/** Mode selects a compiled implementation. Create another instance to switch. */
+export class Scanner {
+    host;
+    mode;
+    additional;
+    formats;
+    constructor(host, mode, additional, formats = ["EAN13"]) {
+        this.host = host;
+        this.mode = mode;
+        this.additional = additional;
+        this.formats = formats;
+    }
+    static async create(options = {}) {
+        const input = options;
+        if (input === null || typeof input !== "object" || Array.isArray(input))
+            throw new TypeError("Invalid scanner options");
+        for (const key of Object.keys(options))
+            if (!["mode", "formats", "loadWasm"].includes(key))
+                throw new TypeError(`Unknown scanner option: ${key}`);
+        const mode = options.mode ?? "medium";
+        if (!Object.hasOwn(modes, mode))
+            throw new TypeError("Unknown scanner mode");
+        const extraAsset = "../wasm/multiformat.wasm";
+        const formats = resolveFormats(options.formats);
+        const url = new URL("../wasm/" + modes[mode], import.meta.url);
+        const load = options.loadWasm ?? loadDefault;
+        const bytes = await load(url);
+        const recovery = mode === "low" ? undefined : await load(new URL("../wasm/" + modes.low, import.meta.url));
+        const host = recovery
+            ? await ReleaseDetailScanner.create(bytes, recovery, mode)
+            : await IndependentScanner.create(bytes);
+        try {
+            const extra = formats.some((f) => f !== "EAN13" && f !== "UPCA")
+                ? await load(new URL(extraAsset, import.meta.url))
+                : undefined;
+            const additional = formats.length !== 1 || formats[0] !== "EAN13"
+                ? await MediumMultiformatScanner.create(bytes, extra, mode, recovery)
+                : undefined;
+            return new Scanner(host, mode, additional, formats);
+        }
+        catch (error) {
+            host.dispose();
+            throw error;
+        }
+    }
+    scan(inputImage, options = {}) {
+        const image = pixels(inputImage);
+        const input = options;
+        if (input === null || typeof input !== "object" || Array.isArray(input))
+            throw new TypeError("Invalid scan options");
+        for (const key of Object.keys(options)) {
+            if (key !== "multiple" && key !== "includeRegions" && key !== "debug")
+                throw new TypeError(`Unknown scan option: ${key}`);
+        }
+        for (const key of ["multiple", "includeRegions", "debug"]) {
+            if (options[key] !== undefined && typeof options[key] !== "boolean")
+                throw new TypeError(`Invalid ${key}`);
+        }
+        const multiple = options.multiple ?? true;
+        if (options.debug !== undefined &&
+            options.includeRegions !== undefined &&
+            options.debug !== options.includeRegions)
+            throw new TypeError("debug and includeRegions disagree");
+        const includeRegions = options.debug ?? options.includeRegions ?? false;
+        if (this.additional) {
+            const frame = this.additional.scan(image, this.formats);
+            const barcodes = multiple ? frame.barcodes : frame.barcodes.slice(0, 1);
+            return publicResult({
+                schemaVersion: 2,
+                mode: this.mode,
+                multiple,
+                elapsedMs: frame.scanMs,
+                localizationLimited: frame.unfinished,
+                scan: {
+                    barcodes,
+                    unfinished: frame.unfinished,
+                    ...(includeRegions ? { regions: frame.regions } : {}),
+                },
+            }, image, includeRegions);
+        }
+        const full = this.host.scanLocalized(image, policy, fitLimits[this.mode], true);
+        // Isolate the imported host's JSON result at the public ABI type boundary.
+        const localization = full.localization;
+        const best = multiple ? undefined : this.host.best(full.scan);
+        const barcodes = (multiple ? full.scan.barcodes : best ? [best] : []).map((b) => ({
+            ...b,
+            format: "EAN13",
+        }));
+        return publicResult({
+            schemaVersion: 2,
+            mode: this.mode,
+            multiple,
+            elapsedMs: full.scanMs,
+            localizationLimited: localization.workLimited,
+            scan: includeRegions
+                ? { ...full.scan, barcodes }
+                : { barcodes, unfinished: full.scan.unfinished },
+            ...(includeRegions
+                ? {
+                    localization,
+                    searchWindows: full.searchWindows,
+                    ...("recovery" in full && "detailRegions" in full
+                        ? {
+                            recovery: full.recovery,
+                            detailRegions: full.detailRegions,
+                        }
+                        : {}),
+                }
+                : {}),
+        }, image, includeRegions);
+    }
+    /** Convenience alias for result.best. */
+    best(result) {
+        return result.best;
+    }
+    dispose() {
+        this.additional?.dispose();
+        this.host.dispose();
+    }
+}
+/** Scan one image with automatic cleanup. Reuse Scanner for a stream of images. */
+export async function scan(image, options = {}) {
+    const { multiple, debug, includeRegions, ...creation } = options;
+    const scanner = await Scanner.create(creation);
+    try {
+        return scanner.scan(image, { multiple, debug, includeRegions });
+    }
+    finally {
+        scanner.dispose();
+    }
+}

package/dist/multiformat/formats.d.ts

@@ -0,0 +1,26 @@
+/** Explicit opt-in formats for the independent Medium extension. */
+export declare const formatBits: {
+    readonly EAN13: 1;
+    readonly UPCA: 2;
+    readonly EAN8: 4;
+    readonly UPCE: 8;
+    readonly Code128: 16;
+    readonly Code39: 32;
+    readonly ITF: 64;
+    readonly Codabar: 128;
+    readonly Code93: 256;
+    readonly QRCode: 512;
+    readonly DataMatrix: 1024;
+    readonly PDF417: 2048;
+    readonly Aztec: 4096;
+    readonly DataBar: 8192;
+    readonly DataBarExpanded: 16384;
+    readonly MaxiCode: 131072;
+};
+export type Format = keyof typeof formatBits;
+export declare const retailFormats: readonly Format[];
+export declare const linearFormats: readonly Format[];
+export declare const matrixFormats: readonly Format[];
+export type FormatSelection = readonly Format[] | "1D" | "2D" | "all";
+export declare function resolveFormats(input?: readonly string[] | "1D" | "2D" | "all"): Format[];
+export declare function maskFor(formats: readonly Format[]): number;

package/dist/multiformat/formats.js

@@ -0,0 +1,59 @@
+/** Explicit opt-in formats for the independent Medium extension. */
+export const formatBits = {
+    EAN13: 1,
+    UPCA: 2,
+    EAN8: 4,
+    UPCE: 8,
+    Code128: 16,
+    Code39: 32,
+    ITF: 64,
+    Codabar: 128,
+    Code93: 256,
+    QRCode: 512,
+    DataMatrix: 1024,
+    PDF417: 2048,
+    Aztec: 4096,
+    DataBar: 8192,
+    DataBarExpanded: 16384,
+    MaxiCode: 131072,
+};
+export const retailFormats = ["EAN13", "UPCA", "EAN8", "UPCE"];
+export const linearFormats = [
+    ...retailFormats,
+    "Code128",
+    "Code39",
+    "ITF",
+    "Codabar",
+    "Code93",
+    "DataBar",
+    "DataBarExpanded",
+];
+export const matrixFormats = [
+    "QRCode",
+    "DataMatrix",
+    "PDF417",
+    "Aztec",
+    "MaxiCode",
+];
+export function resolveFormats(input) {
+    if (input === "1D")
+        return [...linearFormats];
+    if (input === "2D")
+        return [...matrixFormats];
+    if (input === "all")
+        return [...linearFormats, ...matrixFormats];
+    if (input === undefined)
+        return ["EAN13"];
+    if (!Array.isArray(input) || input.length === 0)
+        throw Error("Choose at least one barcode format.");
+    for (const value of input) {
+        if (typeof value !== "string")
+            throw Error("Barcode format must be a string.");
+        if (!Object.hasOwn(formatBits, value))
+            throw Error(`Unsupported barcode format: ${value}`);
+    }
+    return [...new Set(input)];
+}
+export function maskFor(formats) {
+    return formats.reduce((mask, f) => mask | formatBits[f], 0);
+}

package/dist/multiformat/geometry.d.ts

@@ -0,0 +1,32 @@
+import type { Quad } from "../host.js";
+export type Transform = readonly number[];
+export declare function project(t: Transform, x: number, y: number): [number, number];
+export declare function transformFor(quad: Quad, width: number, height: number): Transform;
+export declare function rectify(gray: Uint8Array, width: number, height: number, quad: Quad): {
+    data: Uint8Array<ArrayBuffer>;
+    width: number;
+    height: number;
+    transform: number[];
+};
+/** Convex intersection, including opposite winding and projective quadrilaterals. */
+export declare function polygonOverlap(a: Quad, b: Quad): {
+    iou: number;
+    smaller: number;
+    a: number;
+    b: number;
+};
+/** Suppress overlapping reads of the same physical symbol, never by text alone. */
+export declare function distinctReads<T extends {
+    text: string;
+    format: string;
+    polygon: Quad;
+    support: number;
+    eanAddOn?: string;
+    readerInitialization?: boolean;
+    structuredAppend?: {
+        index: number;
+        count: number;
+        id?: string;
+        parity?: number;
+    };
+}>(reads: readonly T[]): T[];

package/dist/multiformat/geometry.js

@@ -0,0 +1,122 @@
+export function project(t, x, y) {
+    const z = t[6] * x + t[7] * y + 1;
+    return [(t[0] * x + t[1] * y + t[2]) / z, (t[3] * x + t[4] * y + t[5]) / z];
+}
+export function transformFor(quad, width, height) {
+    const source = [
+        [0, 0],
+        [width, 0],
+        [width, height],
+        [0, height],
+    ];
+    const a = [];
+    for (let i = 0; i < 4; i++) {
+        const [x, y] = source[i], [u, v] = quad[i];
+        a.push([x, y, 1, 0, 0, 0, -u * x, -u * y, u], [0, 0, 0, x, y, 1, -v * x, -v * y, v]);
+    }
+    for (let col = 0; col < 8; col++) {
+        let pivot = col;
+        for (let i = col + 1; i < 8; i++)
+            if (Math.abs(a[i][col]) > Math.abs(a[pivot][col]))
+                pivot = i;
+        if (Math.abs(a[pivot][col]) < 1e-9)
+            throw Error("Degenerate barcode region.");
+        [a[col], a[pivot]] = [a[pivot], a[col]];
+        const divisor = a[col][col];
+        for (let j = col; j <= 8; j++)
+            a[col][j] /= divisor;
+        for (let i = 0; i < 8; i++) {
+            if (i === col)
+                continue;
+            const scale = a[i][col];
+            for (let j = col; j <= 8; j++)
+                a[i][j] -= scale * a[col][j];
+        }
+    }
+    return a.map((row) => row[8]);
+}
+export function rectify(gray, width, height, quad) {
+    const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1]);
+    const w = Math.max(8, Math.ceil(Math.max(distance(quad[0], quad[1]), distance(quad[3], quad[2]))));
+    const h = Math.max(8, Math.ceil(Math.max(distance(quad[0], quad[3]), distance(quad[1], quad[2]))));
+    if (w * h > 8 * 1024 * 1024)
+        throw Error("Barcode region exceeds rectification budget.");
+    const base = transformFor(quad, w, h);
+    const pad = 8, divisor = 1 - pad * (base[6] + base[7]);
+    const t = [
+        base[0] / divisor,
+        base[1] / divisor,
+        (base[2] - pad * (base[0] + base[1])) / divisor,
+        base[3] / divisor,
+        base[4] / divisor,
+        (base[5] - pad * (base[3] + base[4])) / divisor,
+        base[6] / divisor,
+        base[7] / divisor,
+    ];
+    const paddedWidth = w + 2 * pad, paddedHeight = h + 2 * pad;
+    const data = new Uint8Array(paddedWidth * paddedHeight);
+    for (let y = 0; y < paddedHeight; y++)
+        for (let x = 0; x < paddedWidth; x++) {
+            const [xx, yy] = project(t, x + 0.5, y + 0.5);
+            if (xx < 0 || yy < 0 || xx > width - 1 || yy > height - 1) {
+                data[y * paddedWidth + x] = 255;
+                continue;
+            }
+            const x0 = Math.floor(xx), y0 = Math.floor(yy), fx = xx - x0, fy = yy - y0;
+            const x1 = Math.min(width - 1, x0 + 1), y1 = Math.min(height - 1, y0 + 1);
+            data[y * paddedWidth + x] = Math.round((gray[y0 * width + x0] * (1 - fx) + gray[y0 * width + x1] * fx) * (1 - fy) +
+                (gray[y1 * width + x0] * (1 - fx) + gray[y1 * width + x1] * fx) * fy);
+        }
+    return { data, width: paddedWidth, height: paddedHeight, transform: t };
+}
+/** Convex intersection, including opposite winding and projective quadrilaterals. */
+export function polygonOverlap(a, b) {
+    const signedArea = (p) => p.reduce((sum, q, i) => {
+        const r = p[(i + 1) % p.length];
+        return sum + q[0] * r[1] - q[1] * r[0];
+    }, 0) / 2;
+    const aa = Math.abs(signedArea(a)), bb = Math.abs(signedArea(b));
+    if (Math.min(aa, bb) < 1e-6)
+        return { iou: 0, smaller: 0, a: 0, b: 0 };
+    const winding = Math.sign(signedArea(b));
+    let points = [...a];
+    for (let i = 0; i < 4 && points.length; i++) {
+        const p = b[i], q = b[(i + 1) % 4];
+        const side = (r) => winding * ((q[0] - p[0]) * (r[1] - p[1]) - (q[1] - p[1]) * (r[0] - p[0]));
+        const clipped = [];
+        for (let j = 0; j < points.length; j++) {
+            const u = points[j], v = points[(j + 1) % points.length], su = side(u), sv = side(v);
+            if (su >= 0)
+                clipped.push(u);
+            if (su >= 0 !== sv >= 0) {
+                const t = su / (su - sv);
+                clipped.push([u[0] + t * (v[0] - u[0]), u[1] + t * (v[1] - u[1])]);
+            }
+        }
+        points = clipped;
+    }
+    const intersection = Math.min(aa, bb, Math.abs(signedArea(points)));
+    return {
+        iou: intersection / (aa + bb - intersection),
+        smaller: intersection / Math.min(aa, bb),
+        a: intersection / aa,
+        b: intersection / bb,
+    };
+}
+/** Suppress overlapping reads of the same physical symbol, never by text alone. */
+export function distinctReads(reads) {
+    const result = [];
+    for (const read of [...reads].sort((a, b) => b.support - a.support)) {
+        if (!result.some((r) => r.text === read.text &&
+            r.format === read.format &&
+            r.eanAddOn === read.eanAddOn &&
+            Boolean(r.readerInitialization) === Boolean(read.readerInitialization) &&
+            r.structuredAppend?.index === read.structuredAppend?.index &&
+            r.structuredAppend?.count === read.structuredAppend?.count &&
+            r.structuredAppend?.id === read.structuredAppend?.id &&
+            r.structuredAppend?.parity === read.structuredAppend?.parity &&
+            polygonOverlap(r.polygon, read.polygon).smaller >= 0.65))
+            result.push(read);
+    }
+    return result;
+}

package/dist/multiformat/pixels.d.ts

@@ -0,0 +1,3 @@
+import type { Image } from "../multiformat-host.js";
+/** Input dimensions are validated by the scanner. Preserve its integer luma rule. */
+export declare function toGray({ data, width, height, channels, stride }: Image): Uint8Array;

package/dist/multiformat/pixels.js

@@ -0,0 +1,36 @@
+const littleEndian = new Uint8Array(new Uint32Array([1]).buffer)[0] === 1;
+/** Input dimensions are validated by the scanner. Preserve its integer luma rule. */
+export function toGray({ data, width, height, channels, stride }) {
+    const count = width * height;
+    if (channels === 1 && stride === width)
+        return data.slice(0, count);
+    const gray = new Uint8Array(count);
+    if (channels === 4 && stride === width * 4 && littleEndian && data.byteOffset % 4 === 0) {
+        const words = new Uint32Array(data.buffer, data.byteOffset, count);
+        for (let i = 0; i < count; i++) {
+            const value = words[i];
+            gray[i] =
+                ((value & 255) * 77 + ((value >>> 8) & 255) * 150 + ((value >>> 16) & 255) * 29 + 128) >>>
+                    8;
+        }
+    }
+    else if (channels === 4 && stride === width * 4) {
+        for (let i = 0, j = 0; j < count; i += 4, j++)
+            gray[j] = (data[i] * 77 + data[i + 1] * 150 + data[i + 2] * 29 + 128) >> 8;
+    }
+    else if (channels === 3 && stride === width * 3) {
+        for (let i = 0, j = 0; j < count; i += 3, j++)
+            gray[j] = (data[i] * 77 + data[i + 1] * 150 + data[i + 2] * 29 + 128) >> 8;
+    }
+    else if (channels === 1) {
+        for (let y = 0; y < height; y++)
+            gray.set(data.subarray(y * stride, y * stride + width), y * width);
+    }
+    else {
+        for (let y = 0; y < height; y++) {
+            for (let x = 0, i = y * stride, j = y * width; x < width; x++, i += channels, j++)
+                gray[j] = (data[i] * 77 + data[i + 1] * 150 + data[i + 2] * 29 + 128) >> 8;
+        }
+    }
+    return gray;
+}

package/dist/multiformat/scanner.d.ts

@@ -0,0 +1,51 @@
+import { type Image, type Quad } from "../multiformat-host.js";
+import type { Mode } from "../index.js";
+import { type Format } from "./formats.js";
+export interface Barcode {
+    format: Format | "Unknown";
+    text: string;
+    polygon: Quad;
+    support: number;
+    localizationScore?: number;
+    gs1?: boolean;
+    readerInitialization?: boolean;
+    structuredAppend?: {
+        index: number;
+        count: number;
+        id?: string;
+        parity?: number;
+    };
+    eanAddOn?: string;
+    error?: number;
+    rank?: number;
+}
+export type EanAddOnSymbol = "Ignore" | "Read" | "Require";
+export interface Frame {
+    eanAddOnSymbol: EanAddOnSymbol;
+    barcodes: Barcode[];
+    regions: Barcode[];
+    formats: Format[];
+    unfinished: boolean;
+    scanMs: number;
+    mediumMs: number;
+    additionalMs: number;
+    preparationMs: number;
+    localizationMs: number;
+    linearStrategy: "scanlines" | "medium-localized";
+}
+/** Frozen EAN13 Medium plus project-owned opt-in readers. No reference decoder. */
+export declare class MediumMultiformatScanner {
+    private medium?;
+    private mode;
+    private extra?;
+    private handle;
+    private disposed;
+    private constructor();
+    static create(mediumBytes: ArrayBuffer, extraBytes?: ArrayBuffer, mode?: Mode, recoveryBytes?: ArrayBuffer): Promise<MediumMultiformatScanner>;
+    scan(image: Image, inputFormats?: readonly string[], options?: {
+        linearStrategy?: "scanlines" | "medium-localized";
+        eanAddOnSymbol?: EanAddOnSymbol;
+    }): Frame;
+    private scanExtra;
+    dispose(): void;
+}