@gueshbzh-perso/scanner 0.6.0 → 0.7.0

package/src/reader.ts

@@ -0,0 +1,474 @@
+// BarcodeReader: camera preview + frame pipeline + engine, wired together.
+import { capabilities, listCameras, openCamera, rememberCamera, setTorch, setZoom } from './camera.js';
+import { pickEngineOptions } from './core.js';
+import { createEngine, type Engine } from './engine.js';
+import { Feedback } from './feedback.js';
+import {
+  clampRegion,
+  coverLayout,
+  decoderToVideo,
+  outputSize,
+  regionToVideoRect,
+  videoToElement,
+} from './geometry.js';
+import { CanvasGrabber, createGrabber, type FrameGrabber } from './grabber.js';
+import { Preview } from './overlay.js';
+import type { Detection, EngineOptions, ReaderEvents, ReaderOptions, ReaderStats, Region } from './types.js';
+
+const DEFAULT_REGION: Region = { x: 0.1, y: 0.2, width: 0.8, height: 0.6 };
+
+/** A frame read from the video, waiting for (or being decoded by) the engine. */
+interface GrabbedFrame {
+  buffer: ArrayBuffer;
+  width: number;
+  height: number;
+  /** Region of the video the frame was cropped from (to map points back). */
+  rect: ReturnType<typeof regionToVideoRect>;
+  grabMs: number;
+  /** Grab order: decodes finish out of order when several workers run. */
+  seq: number;
+}
+
+type Listener<T> = (payload: T) => void;
+
+/**
+ * Real-time barcode reader bound to a host element.
+ *
+ * ```ts
+ * const reader = await BarcodeReader.create({ host: '#scanner', formats: ['qr_code', 'ean_13'] });
+ * reader.on('detected', (codes) => console.log(codes[0].text));
+ * await reader.start();
+ * ```
+ */
+export class BarcodeReader {
+  private preview: Preview;
+  private grabber: FrameGrabber;
+  private feedback: Feedback;
+  private stream: MediaStream | null = null;
+  private listeners: { [K in keyof ReaderEvents]: Set<Listener<ReaderEvents[K]>> } = {
+    detected: new Set(),
+    error: new Set(),
+    started: new Set(),
+    stopped: new Set(),
+  };
+  private region: Region;
+  private engineOptions: EngineOptions;
+  private running = false;
+  private paused = false;
+  /** A grab (GPU readback) is in progress. */
+  private grabbing = false;
+  /** Frames being decoded (at most `engine.concurrency`). */
+  private decoding = 0;
+  /** Sequence number of the last grabbed frame, and of the last one drawn. */
+  private grabbed = 0;
+  private drawn = 0;
+  /** Grabbed frame waiting for the engine (at most one). */
+  private pending: GrabbedFrame | null = null;
+  private destroyed = false;
+  /** Start in progress, shared by concurrent `start()` calls. */
+  private starting: Promise<void> | null = null;
+  /** Bumped by `stop()`: a start that sees another value was cancelled. */
+  private lifecycle = 0;
+  /** Consecutive failed frames: only the first error of a streak is reported. */
+  private failures = 0;
+  private torchOn = false;
+  private buffers: ArrayBuffer[] = [];
+  private frameHandle = 0;
+  private perf = { frames: 0, since: 0, fps: 0, decodeMs: 0, grabMs: 0, w: 0, h: 0 };
+
+  private constructor(
+    private engine: Engine,
+    private options: ReaderOptions,
+    host: HTMLElement,
+  ) {
+    this.region = clampRegion(options.regionOfInterest ?? DEFAULT_REGION);
+    this.engineOptions = pickEngineOptions(options);
+    this.preview = new Preview(host, options.overlay);
+    this.preview.setRegion(this.region);
+    this.grabber = createGrabber(options.processing?.backend);
+    this.feedback = new Feedback(options.feedback ?? {});
+  }
+
+  /** Load the engine (WebAssembly, in a Web Worker) and build the preview inside `options.host`. */
+  static async create(options: ReaderOptions): Promise<BarcodeReader> {
+    const host =
+      typeof options.host === 'string' ? document.querySelector<HTMLElement>(options.host) : options.host;
+    if (!host) throw new Error(`BarcodeReader: host element not found (${String(options.host)})`);
+    const engine = await createEngine(options);
+    await engine.configure(pickEngineOptions(options));
+    return new BarcodeReader(engine, options, host);
+  }
+
+  /** Video input devices (labels are empty until permission is granted). */
+  static listCameras(): Promise<MediaDeviceInfo[]> {
+    return listCameras();
+  }
+
+  on<K extends keyof ReaderEvents>(event: K, listener: Listener<ReaderEvents[K]>): () => void {
+    this.listeners[event].add(listener);
+    return () => this.listeners[event].delete(listener);
+  }
+
+  /** The `<video>` element showing the camera feed. */
+  get video(): HTMLVideoElement {
+    return this.preview.video;
+  }
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  get stats(): ReaderStats {
+    return {
+      fps: this.perf.fps,
+      decodeMs: this.perf.decodeMs,
+      grabMs: this.perf.grabMs,
+      frameWidth: this.perf.w,
+      frameHeight: this.perf.h,
+      backend: this.grabber.kind,
+      worker: this.engine.inWorker,
+      workers: this.engine.concurrency,
+    };
+  }
+
+  get engineVersion(): string {
+    return this.engine.version;
+  }
+
+  /** Open the camera and start scanning. Call it from a user gesture to allow the beep on iOS. */
+  start(): Promise<void> {
+    this.assertAlive();
+    if (this.running) return Promise.resolve();
+    // Concurrent calls (double tap, React strict mode…) share one start: a
+    // second getUserMedia would open a second stream that is never released.
+    this.starting ??= this.open().finally(() => (this.starting = null));
+    return this.starting;
+  }
+
+  private async open(): Promise<void> {
+    const lifecycle = this.lifecycle;
+    const cancelled = () => lifecycle !== this.lifecycle || this.destroyed;
+    // Synchronous, before the first await: must run inside the user gesture.
+    this.feedback.unlock();
+    const stream = await openCamera(this.options.camera);
+    if (cancelled()) {
+      // stop() or destroy() was called while the camera was opening.
+      stream.getTracks().forEach((t) => t.stop());
+      return;
+    }
+    this.stream = stream;
+    const video = this.preview.video;
+    video.srcObject = stream;
+    await video.play().catch(() => undefined);
+    await waitForVideo(video);
+    if (cancelled()) return; // stop() already released `this.stream`.
+
+    const track = this.track();
+    if (this.options.camera?.rememberDevice !== false) rememberCamera(track?.getSettings().deviceId);
+    this.torchOn = false;
+    await this.refreshButtons();
+    if (cancelled()) return;
+
+    this.running = true;
+    this.paused = false;
+    this.failures = 0;
+    this.perf.since = performance.now();
+    this.perf.frames = 0;
+    this.emit('started', undefined);
+    this.schedule();
+  }
+
+  /** Stop scanning and release the camera. Also cancels a `start()` in progress. */
+  async stop(): Promise<void> {
+    this.lifecycle++;
+    if (!this.running && !this.stream) return;
+    const wasRunning = this.running;
+    this.running = false;
+    this.cancelSchedule();
+    this.stream?.getTracks().forEach((t) => t.stop());
+    this.stream = null;
+    this.preview.video.srcObject = null;
+    this.preview.setDetections([]);
+    if (wasRunning) this.emit('stopped', undefined);
+  }
+
+  /** Keep the camera running but stop decoding. */
+  pause(): void {
+    this.paused = true;
+  }
+
+  resume(): void {
+    this.paused = false;
+  }
+
+  /** Stop everything and remove the preview from the page. The reader cannot be reused. */
+  async destroy(): Promise<void> {
+    if (this.destroyed) return;
+    await this.stop();
+    this.destroyed = true;
+    this.grabber.destroy();
+    this.preview.destroy();
+    this.feedback.destroy();
+    this.engine.destroy();
+    for (const set of Object.values(this.listeners)) set.clear();
+  }
+
+  setRegionOfInterest(region: Region): void {
+    this.region = clampRegion(region);
+    this.preview.setRegion(this.region);
+  }
+
+  /** Change decoding options (formats, duplicate interval…) on the fly. Resets de-duplication. */
+  async configure(options: EngineOptions): Promise<void> {
+    this.assertAlive();
+    this.engineOptions = { ...this.engineOptions, ...options };
+    await this.engine.configure(this.engineOptions);
+  }
+
+  /** Allow `text` to be reported again right away. */
+  clearCooldown(text: string): Promise<void> {
+    return this.engine.clearCooldown(text);
+  }
+
+  get torchAvailable(): boolean {
+    return !!capabilities(this.track()).torch;
+  }
+
+  async setTorch(on: boolean): Promise<void> {
+    const track = this.track();
+    if (!track) throw new Error('Camera is not started');
+    await setTorch(track, on);
+    this.torchOn = on;
+    await this.refreshButtons();
+  }
+
+  async setZoom(zoom: number): Promise<void> {
+    const track = this.track();
+    if (!track) throw new Error('Camera is not started');
+    await setZoom(track, zoom);
+  }
+
+  /** Switch to another camera (next one in the list when `deviceId` is omitted). */
+  async switchCamera(deviceId?: string): Promise<void> {
+    this.assertAlive();
+    if (!deviceId) {
+      const cams = await listCameras();
+      const current = this.track()?.getSettings().deviceId;
+      const idx = cams.findIndex((c) => c.deviceId === current);
+      deviceId = cams[(idx + 1) % cams.length]?.deviceId;
+    }
+    const wasRunning = this.running;
+    await this.stop();
+    this.options = { ...this.options, camera: { ...this.options.camera, deviceId } };
+    if (wasRunning) await this.start();
+  }
+
+  // ── Frame loop ───────────────────────────────────────────────────────────
+
+  private schedule(): void {
+    if (!this.running) return;
+    const video = this.preview.video;
+    if ('requestVideoFrameCallback' in video) {
+      this.frameHandle = video.requestVideoFrameCallback(() => this.tick());
+    } else {
+      this.frameHandle = requestAnimationFrame(() => this.tick());
+    }
+  }
+
+  private cancelSchedule(): void {
+    const video = this.preview.video;
+    if ('cancelVideoFrameCallback' in video) video.cancelVideoFrameCallback(this.frameHandle);
+    cancelAnimationFrame(this.frameHandle);
+  }
+
+  /**
+   * Frame pipeline, two stages that run **concurrently**: the grab (GPU crop +
+   * readback, main thread) of the next frame overlaps the decoding of the
+   * previous ones, which itself runs on `engine.concurrency` workers in
+   * parallel. Running grab and decode one after the other made the frame
+   * time `grab + decode`; overlapped it is `max(grab, decode / workers)`
+   * (Galaxy A14: grab ~55 ms, decode ~125 ms → ~180 ms per frame before).
+   *
+   * Back-pressure: at most one grab in flight and one frame waiting for a
+   * free worker. While a frame waits, no new grab starts, so frames are
+   * skipped, never queued, and the waiting frame is at most one decode old.
+   */
+  private tick(): void {
+    if (!this.running) return;
+    if (!this.grabbing && !this.pending && !this.paused && this.preview.video.videoWidth > 0) {
+      this.grabbing = true;
+      this.grabFrame()
+        .then((frame) => this.enqueue(frame))
+        .catch((err) => this.handleFrameError(err))
+        .finally(() => (this.grabbing = false));
+    }
+    this.preview.render();
+    this.schedule();
+  }
+
+  private async grabFrame(): Promise<GrabbedFrame> {
+    const video = this.preview.video;
+    const ew = this.preview.width || video.videoWidth;
+    const eh = this.preview.height || video.videoHeight;
+    const rect = regionToVideoRect(this.region, video.videoWidth, video.videoHeight, ew, eh);
+    const { width, height } = outputSize(rect, this.options.processing?.maxDimension ?? 1024);
+
+    const t0 = performance.now();
+    const buffer = this.takeBuffer(width * height);
+    try {
+      await this.grabber.grab(video, rect, width, height, new Uint8Array(buffer));
+    } catch (err) {
+      this.buffers.push(buffer);
+      throw new GrabError(err);
+    }
+    return { buffer, width, height, rect, grabMs: performance.now() - t0, seq: ++this.grabbed };
+  }
+
+  private enqueue(frame: GrabbedFrame): void {
+    if (!this.running || this.paused) {
+      this.buffers.push(frame.buffer);
+    } else if (this.decoding >= this.engine.concurrency) {
+      this.pending = frame;
+    } else {
+      this.decode(frame);
+    }
+  }
+
+  private decode(frame: GrabbedFrame): void {
+    this.decoding++;
+    this.decodeFrame(frame)
+      .catch((err) => this.handleFrameError(err))
+      .finally(() => {
+        this.decoding--;
+        const next = this.pending;
+        this.pending = null;
+        if (next) this.enqueue(next);
+      });
+  }
+
+  private async decodeFrame(frame: GrabbedFrame): Promise<void> {
+    const { width, height, rect } = frame;
+    const reply = await this.engine.processFrame(frame.buffer, width, height, 'luma');
+    this.buffers.push(reply.buffer);
+    if (!this.running) return;
+    this.failures = 0;
+
+    this.updatePerf(frame.grabMs, reply.decodeMs, width, height);
+
+    const video = this.preview.video;
+    const vw = video.videoWidth;
+    const vh = video.videoHeight;
+    const toVideo = (d: Detection): Detection => ({
+      ...d,
+      points: decoderToVideo(d.points, rect, width, height),
+    });
+    // An older frame finishing after a newer one must not move the highlights back.
+    if (frame.seq > this.drawn) {
+      this.drawn = frame.seq;
+      const live = reply.live.map(toVideo);
+      const layout = coverLayout(vw, vh, this.preview.width || vw, this.preview.height || vh);
+      this.preview.setDetections(live.map((d) => d.points.map((p) => videoToElement(p, layout))));
+    }
+
+    if (reply.results && reply.results.length > 0) {
+      this.feedback.play();
+      this.emit('detected', reply.results.map(toVideo));
+    }
+  }
+
+  private handleFrameError(err: unknown): void {
+    // Frames still in flight when the reader was stopped or destroyed.
+    if (!this.running || this.destroyed) return;
+    if (err instanceof GrabError && this.grabber.kind === 'webgl') {
+      // GPU pipeline failed (context lost, driver issue…): continue on Canvas 2D.
+      console.warn('[scanner] WebGL pipeline failed, falling back to Canvas 2D:', err.cause);
+      this.grabber.destroy();
+      this.grabber = new CanvasGrabber();
+      return;
+    }
+    // A persistent failure (engine unavailable…) would otherwise emit one error
+    // per frame, ~30 per second: report the first one of each streak.
+    if (this.failures++ > 0) return;
+    const error = err instanceof GrabError ? err.cause : err;
+    this.emit('error', error instanceof Error ? error : new Error(String(error)));
+  }
+
+  private takeBuffer(size: number): ArrayBuffer {
+    // Buffers of another size (ROI or resolution changed) are dropped.
+    for (let b = this.buffers.pop(); b; b = this.buffers.pop()) {
+      if (b.byteLength === size) return b;
+    }
+    return new ArrayBuffer(size);
+  }
+
+  private updatePerf(grabMs: number, decodeMs: number, w: number, h: number): void {
+    const p = this.perf;
+    p.frames++;
+    p.grabMs = p.grabMs ? p.grabMs * 0.9 + grabMs * 0.1 : grabMs;
+    p.decodeMs = p.decodeMs ? p.decodeMs * 0.9 + decodeMs * 0.1 : decodeMs;
+    p.w = w;
+    p.h = h;
+    const now = performance.now();
+    if (now - p.since >= 1000) {
+      p.fps = (p.frames * 1000) / (now - p.since);
+      p.frames = 0;
+      p.since = now;
+    }
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────────────────
+
+  private track(): MediaStreamTrack | undefined {
+    return this.stream?.getVideoTracks()[0];
+  }
+
+  private async refreshButtons(): Promise<void> {
+    this.preview.setTorchButton(this.torchAvailable, this.torchOn, () => {
+      this.setTorch(!this.torchOn).catch((e) => this.emit('error', e));
+    });
+    const cams = await listCameras().catch(() => []);
+    this.preview.setSwitchButton(cams.length > 1, () => {
+      this.switchCamera().catch((e) => this.emit('error', e));
+    });
+  }
+
+  private emit<K extends keyof ReaderEvents>(event: K, payload: ReaderEvents[K]): void {
+    for (const l of this.listeners[event]) {
+      try {
+        l(payload);
+      } catch (err) {
+        console.error('[scanner] listener error:', err);
+      }
+    }
+  }
+
+  private assertAlive(): void {
+    if (this.destroyed) throw new Error('BarcodeReader has been destroyed');
+  }
+}
+
+/**
+ * Failure of the frame pipeline (GPU / canvas), as opposed to the engine.
+ * Only these trigger the WebGL → Canvas 2D fallback: an engine error must not
+ * be mistaken for a WebGL problem.
+ */
+class GrabError extends Error {
+  constructor(override readonly cause: unknown) {
+    super(cause instanceof Error ? cause.message : String(cause));
+  }
+}
+
+function waitForVideo(video: HTMLVideoElement): Promise<void> {
+  if (video.readyState >= 2 && video.videoWidth > 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('Camera did not deliver any frame')), 10_000);
+    video.addEventListener(
+      'loadeddata',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}

package/src/scan-image.ts

@@ -0,0 +1,88 @@
+// One-shot scanning of still images (file uploads, photos, canvases…).
+import { pickEngineOptions } from './core.js';
+import { sharedEngine } from './engine.js';
+import type { AssetOptions, Detection, EngineOptions } from './types.js';
+
+export type ImageInput =
+  Blob | ImageData | ImageBitmap | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | OffscreenCanvas;
+
+export interface ScanImageOptions extends EngineOptions, AssetOptions {
+  /** Images larger than this (longest side, px) are downscaled first. Default: `2048`. */
+  maxDimension?: number;
+}
+
+/**
+ * Scan a still image. Runs every decoding strategy (rotations, inversion,
+ * contrast enhancement…) and returns all codes found, with points in the
+ * pixel coordinates of the source image.
+ *
+ * ```ts
+ * const [code] = await scanImage(fileInput.files[0], { formats: ['qr_code'] });
+ * ```
+ */
+export async function scanImage(input: ImageInput, options: ScanImageOptions = {}): Promise<Detection[]> {
+  const engine = await sharedEngine(options);
+  const { data, width, height, scale } = await rasterize(input, options.maxDimension ?? 2048);
+  const engineOptions: EngineOptions = { ...pickEngineOptions(options), maxResults: options.maxResults ?? 8 };
+  const results = await engine.scanImage(data.buffer as ArrayBuffer, width, height, 'rgba', engineOptions);
+  return scale === 1
+    ? results
+    : results.map((r) => ({ ...r, points: r.points.map((p) => ({ x: p.x / scale, y: p.y / scale })) }));
+}
+
+async function rasterize(input: ImageInput, maxDim: number) {
+  if (
+    typeof ImageData !== 'undefined' &&
+    input instanceof ImageData &&
+    Math.max(input.width, input.height) <= maxDim
+  ) {
+    return {
+      data: new Uint8Array(input.data.slice().buffer),
+      width: input.width,
+      height: input.height,
+      scale: 1,
+    };
+  }
+
+  let source: CanvasImageSource | ImageBitmap;
+  let owned: ImageBitmap | null = null;
+  if (input instanceof Blob) {
+    owned = await createImageBitmap(input);
+    source = owned;
+  } else if (typeof ImageData !== 'undefined' && input instanceof ImageData) {
+    owned = await createImageBitmap(input);
+    source = owned;
+  } else {
+    if (typeof HTMLImageElement !== 'undefined' && input instanceof HTMLImageElement && !input.complete) {
+      await input.decode();
+    }
+    source = input as CanvasImageSource;
+  }
+
+  const [sw, sh] = size(source);
+  if (!sw || !sh) throw new Error('scanImage: image has no pixels');
+  const scale = Math.min(1, maxDim / Math.max(sw, sh));
+  const width = Math.max(1, Math.round(sw * scale));
+  const height = Math.max(1, Math.round(sh * scale));
+
+  const canvas =
+    typeof OffscreenCanvas !== 'undefined'
+      ? new OffscreenCanvas(width, height)
+      : Object.assign(document.createElement('canvas'), { width, height });
+  const ctx = canvas.getContext('2d', { willReadFrequently: true }) as
+    CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null;
+  if (!ctx) throw new Error('scanImage: 2D canvas is not available');
+  ctx.drawImage(source, 0, 0, width, height);
+  owned?.close();
+  const pixels = ctx.getImageData(0, 0, width, height).data;
+  return { data: new Uint8Array(pixels.buffer), width, height, scale };
+}
+
+function size(s: CanvasImageSource | ImageBitmap): [number, number] {
+  if (typeof HTMLImageElement !== 'undefined' && s instanceof HTMLImageElement)
+    return [s.naturalWidth, s.naturalHeight];
+  if (typeof HTMLVideoElement !== 'undefined' && s instanceof HTMLVideoElement)
+    return [s.videoWidth, s.videoHeight];
+  const o = s as { width: number; height: number };
+  return [o.width, o.height];
+}