@gueshbzh-perso/scanner 0.9.0 → 0.11.0

package/dist/wasm/scanner_wasm_bg.wasm.d.ts

@@ -16,10 +16,12 @@ export const wasmscanner_scanRgb: (a: number, b: number, c: number, d: number, e
 export const wasmscanner_scanRgba: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const wasmscansession_clearCooldown: (a: number, b: number, c: number) => void;
 export const wasmscansession_commit: (a: number, b: number) => number;
+export const wasmscansession_commitExternal: (a: number, b: number, c: number, d: number) => void;
 export const wasmscansession_frameBuffer: (a: number, b: number) => number;
 export const wasmscansession_lastDetections: (a: number) => number;
 export const wasmscansession_new: (a: number) => number;
 export const wasmscansession_plan: (a: number) => number;
+export const wasmscansession_planFallbackOnly: (a: number) => number;
 export const wasmscansession_processFrameBuffer: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
 export const wasmscansession_processFrameLuma: (a: number, b: number, c: number, d: number, e: number) => number;
 export const wasmscansession_processFrameRgba: (a: number, b: number, c: number, d: number, e: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gueshbzh-perso/scanner",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Fast QR code & barcode scanning for the web: camera, WebGL frame pipeline, Web Worker and Rust/WebAssembly decoder.",
   "type": "module",
   "license": "MIT",

package/src/core.ts

@@ -6,6 +6,8 @@
 // - `SessionCore`: the session. Cheap calls (`plan`, `commit`), main thread.
 // - `DecoderCore`: the expensive decoding, one per Web Worker.
 // The inline engine (no Worker support) uses both on the main thread.
+// Codes read by the browser's native `BarcodeDetector` enter the session with
+// `SessionCore.commitExternal` (see `native.ts`).
 import init, { WasmFrameDecoder, WasmScanner, WasmScanSession, version } from './wasm/scanner_wasm.js';
 import type { FramePlan, FrameReport, PixelFormat, ScanResult, WasmScanConfig } from './wasm/scanner_wasm.js';
 import type { Detection, EngineOptions } from './types.js';
@@ -72,6 +74,12 @@ export function toDetection(r: ScanResult): Detection {
   return d;
 }
 
+function toScanResult(d: Detection): ScanResult {
+  const r: ScanResult = { text: d.text, format: d.format, points: d.points, timestampMs: d.timestamp };
+  if (d.rawBytes) r.rawBytes = d.rawBytes;
+  return r;
+}
+
 export interface FrameOutcome {
   /** New codes, or `null`. */
   results: Detection[] | null;
@@ -89,9 +97,14 @@ export class SessionCore {
     this.session = new WasmScanSession(streamConfig(options));
   }
 
-  /** Strategy plan of the next frame, for a `DecoderCore` configured the same way. */
-  plan(): FramePlan {
-    return this.active().plan();
+  /**
+   * Strategy plan of the next frame, for a `DecoderCore` configured the same
+   * way. `fastPath: false` when the native `BarcodeDetector` already searched
+   * the frame: the decoder then runs the fallback strategy only.
+   */
+  plan(fastPath = true): FramePlan {
+    const session = this.active();
+    return fastPath ? session.plan() : session.planFallbackOnly();
   }
 
   /** Record a decoded frame; returns the new codes and the live ones. */
@@ -102,16 +115,16 @@ export class SessionCore {
     return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs: report.elapsedMs };
   }
 
-  /** Decode on this thread (inline engine): plan, decode and commit at once. */
-  process(pixels: Uint8Array, width: number, height: number, format: PixelFormat): FrameOutcome {
+  /**
+   * Record codes read by the native `BarcodeDetector`: same format filter,
+   * confirmation and de-duplication as decoded frames. Points are kept as
+   * given (video pixels).
+   */
+  commitExternal(codes: Detection[], elapsedMs: number): FrameOutcome {
     const session = this.active();
-    // Write straight into WASM memory: avoids one more copy of the frame.
-    session.frameBuffer(pixels.length).set(pixels);
-    const t0 = performance.now();
-    const fresh = session.processFrameBuffer(width, height, format);
-    const decodeMs = performance.now() - t0;
+    const fresh = session.commitExternal(codes.map(toScanResult), elapsedMs);
     const results = fresh ? fresh.map(toDetection) : null;
-    return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs };
+    return { results, live: results ?? session.lastDetections.map(toDetection), decodeMs: elapsedMs };
   }
 
   reset(): void {

package/src/engine.ts

@@ -9,7 +9,7 @@
 // with many slow cores (Galaxy A14: decode ~125 ms) the pool multiplies the
 // frame rate.
 import { DecoderCore, SessionCore, compileWasm, defaultWasmUrl, loadWasm } from './core.js';
-import type { FramePlan, FrameReport } from './core.js';
+import type { FrameOutcome, FramePlan, FrameReport } from './core.js';
 import type { WorkerRequest, WorkerResponse } from './protocol.js';
 import type { PixelFormat } from './wasm/scanner_wasm.js';
 import type { AssetOptions, Detection, EngineOptions } from './types.js';
@@ -28,8 +28,24 @@ export interface Engine {
   /** Frames that can be decoded at the same time (number of workers). */
   readonly concurrency: number;
   configure(options: EngineOptions): Promise<void>;
-  /** Decode a camera frame. `buffer` is transferred and returned in the reply. */
-  processFrame(buffer: ArrayBuffer, width: number, height: number, format: PixelFormat): Promise<FrameReply>;
+  /**
+   * Decode a camera frame. `buffer` is transferred and returned in the reply.
+   * `fastPath: false` runs the fallback strategy only, for a frame the
+   * native `BarcodeDetector` already searched without finding anything.
+   */
+  processFrame(
+    buffer: ArrayBuffer,
+    width: number,
+    height: number,
+    format: PixelFormat,
+    fastPath?: boolean,
+  ): Promise<FrameReply>;
+  /**
+   * Record codes read by the native `BarcodeDetector` in a frame: same
+   * format filter, multi-frame confirmation and de-duplication as decoded
+   * frames. Points are returned as given.
+   */
+  commitExternal(codes: Detection[], elapsedMs: number): Promise<FrameOutcome>;
   /** One-shot scan of a still image, running every strategy. */
   scanImage(
     buffer: ArrayBuffer,
@@ -186,10 +202,11 @@ class WorkerPoolEngine implements Engine {
     width: number,
     height: number,
     format: PixelFormat,
+    fastPath = true,
   ): Promise<FrameReply> {
     if (!this.configured) throw new Error('Engine not configured');
     const generation = this.generation;
-    const plan = this.session.plan();
+    const plan = this.session.plan(fastPath);
     let res: OkResponse;
     try {
       res = await this.idleWorker().ok({ type: 'decode', buffer, width, height, format, plan }, [buffer]);
@@ -205,6 +222,11 @@ class WorkerPoolEngine implements Engine {
     return { ...this.session.commit(res.report), buffer: returned };
   }
 
+  async commitExternal(codes: Detection[], elapsedMs: number) {
+    if (!this.configured) throw new Error('Engine not configured');
+    return this.session.commitExternal(codes, elapsedMs);
+  }
+
   async scanImage(
     buffer: ArrayBuffer,
     width: number,
@@ -265,7 +287,10 @@ class InlineEngine implements Engine {
   constructor(readonly version: string) {}
 
   async configure(options: EngineOptions) {
+    // Same configuration for both: a plan is an index in the decoder's list
+    // of fallback strategies (as with workers).
     this.session.configure(options);
+    this.decoder.configure(options);
   }
 
   async processFrame(
@@ -273,8 +298,21 @@ class InlineEngine implements Engine {
     width: number,
     height: number,
     format: PixelFormat,
+    fastPath = true,
   ): Promise<FrameReply> {
-    return { ...this.session.process(new Uint8Array(buffer), width, height, format), buffer };
+    const plan = this.session.plan(fastPath);
+    let report: FrameReport;
+    try {
+      report = this.decoder.decode(new Uint8Array(buffer), width, height, format, plan);
+    } catch (err) {
+      this.session.commit(emptyReport(plan));
+      throw err;
+    }
+    return { ...this.session.commit(report), buffer };
+  }
+
+  async commitExternal(codes: Detection[], elapsedMs: number) {
+    return this.session.commitExternal(codes, elapsedMs);
   }
 
   async scanImage(

package/src/native.ts

@@ -0,0 +1,147 @@
+// The browser's native barcode decoder (`BarcodeDetector`, Shape Detection API).
+//
+// Available in Chrome on Android (Google Play Services), macOS (Apple Vision)
+// and ChromeOS; not in Safari, Firefox, nor Chrome on Windows / Linux. Where it
+// exists it decodes outside the page's threads, so it can replace the engine's
+// **fast path**: the engine then only runs its fallback strategies (Linear,
+// CLAHE, Sauvola, inverted…) on the frames the native decoder found nothing
+// in. The native decoder has no such preprocessing, and those strategies are
+// what reads the hard codes (laser-engraved tags, labels in shadow).
+import type { Rect } from './grabber.js';
+import type { BarcodeFormat, Detection, Point } from './types.js';
+
+// The API is not in TypeScript's `lib.dom` yet: minimal local declarations.
+
+/** A code found by `BarcodeDetector.detect()`. */
+export interface NativeBarcode {
+  rawValue: string;
+  format: string;
+  /** Corners in pixels of the source (for a `<video>`: `videoWidth` space). */
+  cornerPoints: readonly Point[];
+}
+
+interface BarcodeDetectorInstance {
+  detect(source: CanvasImageSource): Promise<NativeBarcode[]>;
+}
+
+/** The `BarcodeDetector` constructor. */
+export interface BarcodeDetectorClass {
+  new (options?: { formats?: string[] }): BarcodeDetectorInstance;
+  getSupportedFormats(): Promise<string[]>;
+}
+
+/**
+ * Formats of this SDK, all spelled like the native ones (`qr_code`, `ean_13`…)
+ * except `micro_qr`, which the native API does not have. With the engine
+ * fallback it is still read by the fallback strategies (`Hard` decodes the
+ * raw frame with every format); without it, see `NativeDetector.create`.
+ */
+const NATIVE_FORMATS: readonly BarcodeFormat[] = [
+  'qr_code',
+  'data_matrix',
+  'aztec',
+  'pdf417',
+  'code_128',
+  'code_39',
+  'code_93',
+  'ean_13',
+  'ean_8',
+  'upc_a',
+  'upc_e',
+  'itf',
+  'codabar',
+];
+
+/** Native decoder serving one reader configuration. */
+export class NativeDetector {
+  private constructor(
+    private detector: BarcodeDetectorInstance,
+    /** Formats the detector looks for. */
+    readonly formats: readonly BarcodeFormat[],
+  ) {}
+
+  /**
+   * A detector for `formats` (default: all), or `undefined` when the native
+   * decoder cannot replace the engine's fast path: API absent, or one of the
+   * requested formats not supported natively (codes of that format would
+   * then be read by the slow fallbacks at best).
+   *
+   * `micro_qr`, absent from the native API: with `engineFallback` the
+   * fallbacks read it. Without, a list that names it explicitly keeps the
+   * engine (the application asked for it, it must not be lost silently),
+   * while the default list (every format) accepts not reading it.
+   */
+  static async create(
+    formats: readonly BarcodeFormat[] | undefined,
+    api: BarcodeDetectorClass | undefined = nativeApi(),
+    engineFallback = false,
+  ): Promise<NativeDetector | undefined> {
+    if (!api) return undefined;
+    if (!engineFallback && formats?.includes('micro_qr')) return undefined;
+    let supported: string[];
+    try {
+      supported = await api.getSupportedFormats();
+    } catch {
+      return undefined;
+    }
+    // On Android the list is empty until Google Play Services has downloaded
+    // its barcode module (first use on the device, in the background): the
+    // detector is unavailable *for now*, the engine does the whole job.
+    const wanted = (formats?.length ? formats : NATIVE_FORMATS).filter((f) => f !== 'micro_qr');
+    if (wanted.length === 0 || !wanted.every((f) => supported.includes(f))) return undefined;
+    try {
+      return new NativeDetector(new api({ formats: [...wanted] }), wanted);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /**
+   * Codes in `source` whose center lies in `rect` (the region of interest, in
+   * source pixels), as detections in source pixels. Throws when the native
+   * decoder fails.
+   */
+  async detect(source: CanvasImageSource, rect: Rect): Promise<Detection[]> {
+    const found = await this.detector.detect(source);
+    const timestamp = Date.now();
+    return found.flatMap((code) => {
+      const format = code.format as BarcodeFormat;
+      if (!this.formats.includes(format) || code.cornerPoints.length === 0) return [];
+      if (!contains(rect, center(code.cornerPoints))) return [];
+      const points = code.cornerPoints.map((p) => ({ x: p.x, y: p.y }));
+      return [{ text: code.rawValue, format, points, timestamp }];
+    });
+  }
+}
+
+/**
+ * The browser's own `BarcodeDetector`, if any. Feature detection only (no
+ * list of browsers or devices): any browser that ships the API is used.
+ *
+ * Polyfills are rejected: packages such as `barcode-detector` install a
+ * `BarcodeDetector` that runs ZXing in WebAssembly on the main thread,
+ * slower than this SDK's own engine in its workers. A built-in class
+ * stringifies as `function BarcodeDetector() { [native code] }`.
+ */
+function nativeApi(): BarcodeDetectorClass | undefined {
+  const api: unknown = Reflect.get(globalThis, 'BarcodeDetector');
+  if (typeof api !== 'function' || !isBuiltIn(api)) return undefined;
+  return api as BarcodeDetectorClass;
+}
+
+/** `true` for a function implemented by the browser, not in JavaScript. */
+export function isBuiltIn(fn: object): boolean {
+  return /\{\s*\[native code\]\s*\}\s*$/.test(Function.prototype.toString.call(fn));
+}
+
+function center(points: readonly Point[]): Point {
+  const n = points.length;
+  return {
+    x: points.reduce((s, p) => s + p.x, 0) / n,
+    y: points.reduce((s, p) => s + p.y, 0) / n,
+  };
+}
+
+function contains(r: Rect, p: Point): boolean {
+  return p.x >= r.x && p.x <= r.x + r.width && p.y >= r.y && p.y <= r.y + r.height;
+}