@gueshbzh-perso/scanner 0.6.0 → 0.7.0

package/src/feedback.ts

@@ -0,0 +1,50 @@
+// Audio / haptic feedback on detection.
+import type { FeedbackOptions } from './types.js';
+
+export class Feedback {
+  private audio: AudioContext | null = null;
+
+  constructor(private options: FeedbackOptions | false) {}
+
+  /** Must be called from a user gesture on iOS for audio to be allowed. */
+  unlock(): void {
+    if (!this.options || this.options.beep === false || this.audio) return;
+    const Ctx =
+      window.AudioContext ??
+      (window as unknown as { webkitAudioContext?: typeof AudioContext }).webkitAudioContext;
+    if (!Ctx) return;
+    try {
+      this.audio = new Ctx();
+      void this.audio.resume();
+    } catch {
+      this.audio = null;
+    }
+  }
+
+  play(): void {
+    if (!this.options) return;
+    if (this.options.vibrate !== false) navigator.vibrate?.(60);
+    if (this.options.beep !== false) this.beep();
+  }
+
+  private beep(): void {
+    const ctx = this.audio;
+    if (!ctx || ctx.state !== 'running') return;
+    const t = ctx.currentTime;
+    const osc = ctx.createOscillator();
+    const gain = ctx.createGain();
+    osc.type = 'sine';
+    osc.frequency.value = 2400;
+    gain.gain.setValueAtTime(0.0001, t);
+    gain.gain.exponentialRampToValueAtTime(0.25, t + 0.005);
+    gain.gain.exponentialRampToValueAtTime(0.0001, t + 0.09);
+    osc.connect(gain).connect(ctx.destination);
+    osc.start(t);
+    osc.stop(t + 0.1);
+  }
+
+  destroy(): void {
+    void this.audio?.close();
+    this.audio = null;
+  }
+}

package/src/geometry.ts

@@ -0,0 +1,55 @@
+// Coordinate mapping between the host element (what the user sees), the video
+// frame, and the downscaled image handed to the decoder.
+import type { Rect } from './grabber.js';
+import type { Point, Region } from './types.js';
+
+/** How a video of `vw×vh` is laid out in an element of `ew×eh` with `object-fit: cover`. */
+export interface CoverLayout {
+  scale: number;
+  offsetX: number;
+  offsetY: number;
+}
+
+export function coverLayout(vw: number, vh: number, ew: number, eh: number): CoverLayout {
+  const scale = Math.max(ew / vw, eh / vh);
+  return { scale, offsetX: (ew - vw * scale) / 2, offsetY: (eh - vh * scale) / 2 };
+}
+
+export function videoToElement(p: Point, l: CoverLayout): Point {
+  return { x: p.x * l.scale + l.offsetX, y: p.y * l.scale + l.offsetY };
+}
+
+/** Region of interest (fractions of the element) → rectangle in video pixels, clamped to the frame. */
+export function regionToVideoRect(r: Region, vw: number, vh: number, ew: number, eh: number): Rect {
+  const l = coverLayout(vw, vh, ew, eh);
+  const x0 = clamp((r.x * ew - l.offsetX) / l.scale, 0, vw);
+  const y0 = clamp((r.y * eh - l.offsetY) / l.scale, 0, vh);
+  const x1 = clamp(((r.x + r.width) * ew - l.offsetX) / l.scale, 0, vw);
+  const y1 = clamp(((r.y + r.height) * eh - l.offsetY) / l.scale, 0, vh);
+  return { x: x0, y: y0, width: Math.max(1, x1 - x0), height: Math.max(1, y1 - y0) };
+}
+
+/** Size of the decoder image for a crop: downscaled to `maxDim`, width rounded to a multiple of 4. */
+export function outputSize(rect: Rect, maxDim: number): { width: number; height: number } {
+  const scale = Math.min(1, maxDim / Math.max(rect.width, rect.height));
+  const width = Math.max(4, Math.floor((rect.width * scale) / 4) * 4);
+  const height = Math.max(1, Math.round(rect.height * scale));
+  return { width, height };
+}
+
+/** Map points from decoder-image space back to video pixels. */
+export function decoderToVideo(points: Point[], rect: Rect, width: number, height: number): Point[] {
+  const sx = rect.width / width;
+  const sy = rect.height / height;
+  return points.map((p) => ({ x: rect.x + (p.x + 0.5) * sx, y: rect.y + (p.y + 0.5) * sy }));
+}
+
+export function clampRegion(r: Region): Region {
+  const x = clamp(r.x, 0, 1);
+  const y = clamp(r.y, 0, 1);
+  return { x, y, width: clamp(r.width, 0.01, 1 - x), height: clamp(r.height, 0.01, 1 - y) };
+}
+
+function clamp(v: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, v));
+}

package/src/grabber.ts

@@ -0,0 +1,385 @@
+// Frame pipeline: turns a video frame into the small grayscale image the decoder needs.
+//
+// The WebGL2 path does all the per-pixel work on the GPU in a single pass:
+//   upload video texture → crop to the region of interest → RGB→luma
+//   → box-filtered downscale → pack 4 luma pixels per RGBA texel
+// so the CPU readback is exactly `width × height` bytes (4× less than
+// getImageData) and, thanks to a pixel-pack buffer + fence, it does not
+// stall the main thread waiting for the GPU.
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface FrameGrabber {
+  readonly kind: 'webgl' | 'canvas';
+  /**
+   * Render `src` (cropped to `rect`, in source pixels) into `out`, a luma
+   * buffer of `width × height` bytes. `width` must be a multiple of 4.
+   */
+  grab(source: TexImageSource, rect: Rect, width: number, height: number, out: Uint8Array): Promise<void>;
+  destroy(): void;
+}
+
+type AnyCanvas = HTMLCanvasElement | OffscreenCanvas;
+
+function makeCanvas(): AnyCanvas {
+  return typeof OffscreenCanvas !== 'undefined'
+    ? new OffscreenCanvas(4, 4)
+    : document.createElement('canvas');
+}
+
+const VERT = `#version 300 es
+in vec2 a_pos;
+void main() { gl_Position = vec4(a_pos, 0.0, 1.0); }`;
+
+const FRAG = `#version 300 es
+precision highp float;
+uniform sampler2D u_src;
+uniform vec4 u_rect;     // crop rectangle in texture coordinates (origin top-left)
+uniform vec2 u_out;      // size of the luma image
+uniform vec2 u_tap;      // sub-sample offset for the 2x2 box filter
+out vec4 o_color;
+const vec3 LUMA = vec3(0.299, 0.587, 0.114);
+
+float luma(vec2 px) {
+  vec2 uv = u_rect.xy + (px + 0.5) / u_out * u_rect.zw;
+  vec3 c = texture(u_src, uv + vec2(-u_tap.x, -u_tap.y)).rgb
+         + texture(u_src, uv + vec2( u_tap.x, -u_tap.y)).rgb
+         + texture(u_src, uv + vec2(-u_tap.x,  u_tap.y)).rgb
+         + texture(u_src, uv + vec2( u_tap.x,  u_tap.y)).rgb;
+  return dot(c * 0.25, LUMA);
+}
+
+void main() {
+  // Framebuffer row 0 is read back first, so row r samples image row r from the top.
+  float y = floor(gl_FragCoord.y);
+  float x = floor(gl_FragCoord.x) * 4.0;
+  o_color = vec4(luma(vec2(x, y)), luma(vec2(x + 1.0, y)), luma(vec2(x + 2.0, y)), luma(vec2(x + 3.0, y)));
+}`;
+
+export class WebGLGrabber implements FrameGrabber {
+  readonly kind = 'webgl';
+  private gl: WebGL2RenderingContext;
+  private program: WebGLProgram;
+  private srcTex: WebGLTexture;
+  private dstTex: WebGLTexture;
+  private fbo: WebGLFramebuffer;
+  private pbo: WebGLBuffer;
+  private uniforms: Record<'rect' | 'out' | 'tap', WebGLUniformLocation | null>;
+  private size = { w: 0, h: 0 };
+  private lost = false;
+
+  /** Returns `null` when WebGL2 is not available. */
+  static create(): WebGLGrabber | null {
+    try {
+      const canvas = makeCanvas();
+      const gl = canvas.getContext('webgl2', {
+        alpha: true,
+        antialias: false,
+        depth: false,
+        stencil: false,
+        premultipliedAlpha: false,
+        preserveDrawingBuffer: false,
+        powerPreference: 'low-power',
+      }) as WebGL2RenderingContext | null;
+      return gl ? new WebGLGrabber(canvas, gl) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private constructor(canvas: AnyCanvas, gl: WebGL2RenderingContext) {
+    this.gl = gl;
+    (canvas as HTMLCanvasElement).addEventListener?.('webglcontextlost', (e) => {
+      e.preventDefault();
+      this.lost = true;
+    });
+
+    this.program = link(gl, VERT, FRAG);
+    gl.useProgram(this.program);
+
+    // Full-screen triangle.
+    const vbo = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, vbo);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const loc = gl.getAttribLocation(this.program, 'a_pos');
+    gl.enableVertexAttribArray(loc);
+    gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
+
+    this.uniforms = {
+      rect: gl.getUniformLocation(this.program, 'u_rect'),
+      out: gl.getUniformLocation(this.program, 'u_out'),
+      tap: gl.getUniformLocation(this.program, 'u_tap'),
+    };
+    gl.uniform1i(gl.getUniformLocation(this.program, 'u_src'), 0);
+
+    this.srcTex = texture(gl);
+    this.dstTex = texture(gl);
+    this.fbo = must(gl.createFramebuffer(), 'framebuffer');
+    this.pbo = must(gl.createBuffer(), 'pixel buffer');
+    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+    gl.pixelStorei(gl.PACK_ALIGNMENT, 1);
+  }
+
+  async grab(
+    source: TexImageSource,
+    rect: Rect,
+    width: number,
+    height: number,
+    out: Uint8Array,
+  ): Promise<void> {
+    const gl = this.gl;
+    if (this.lost || gl.isContextLost()) throw new Error('WebGL context lost');
+    const [sw, sh] = sourceSize(source);
+    const texW = width / 4;
+
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.srcTex);
+    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);
+
+    if (this.size.w !== texW || this.size.h !== height) {
+      gl.bindTexture(gl.TEXTURE_2D, this.dstTex);
+      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA8, texW, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.dstTex, 0);
+      gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+      gl.bufferData(gl.PIXEL_PACK_BUFFER, width * height, gl.STREAM_READ);
+      this.size = { w: texW, h: height };
+      gl.bindTexture(gl.TEXTURE_2D, this.srcTex);
+    }
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.fbo);
+    gl.viewport(0, 0, texW, height);
+    gl.uniform4f(this.uniforms.rect, rect.x / sw, rect.y / sh, rect.width / sw, rect.height / sh);
+    gl.uniform2f(this.uniforms.out, width, height);
+    // Box filter footprint: a quarter of an output pixel, only when downscaling.
+    const fx = rect.width / width;
+    const fy = rect.height / height;
+    gl.uniform2f(this.uniforms.tap, fx > 1 ? (0.25 * fx) / sw : 0, fy > 1 ? (0.25 * fy) / sh : 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    // Asynchronous readback into the pixel-pack buffer.
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+    gl.readPixels(0, 0, texW, height, gl.RGBA, gl.UNSIGNED_BYTE, 0);
+    const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
+    gl.flush();
+    if (sync) {
+      await waitSync(gl, sync);
+      gl.deleteSync(sync);
+    }
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, this.pbo);
+    gl.getBufferSubData(gl.PIXEL_PACK_BUFFER, 0, out, 0, width * height);
+    gl.bindBuffer(gl.PIXEL_PACK_BUFFER, null);
+  }
+
+  destroy() {
+    const gl = this.gl;
+    gl.deleteTexture(this.srcTex);
+    gl.deleteTexture(this.dstTex);
+    gl.deleteFramebuffer(this.fbo);
+    gl.deleteBuffer(this.pbo);
+    gl.deleteProgram(this.program);
+    gl.getExtension('WEBGL_lose_context')?.loseContext();
+  }
+}
+
+/** Fallback pipeline using Canvas 2D (`drawImage` does the crop + scale). */
+export class CanvasGrabber implements FrameGrabber {
+  readonly kind = 'canvas';
+  private canvas = makeCanvas();
+  private ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
+
+  constructor() {
+    const ctx = this.canvas.getContext('2d', { willReadFrequently: true, alpha: false });
+    this.ctx = must(ctx as CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null, '2D context');
+  }
+
+  async grab(
+    source: TexImageSource,
+    rect: Rect,
+    width: number,
+    height: number,
+    out: Uint8Array,
+  ): Promise<void> {
+    if (this.canvas.width !== width || this.canvas.height !== height) {
+      this.canvas.width = width;
+      this.canvas.height = height;
+    }
+    const ctx = this.ctx;
+    ctx.imageSmoothingEnabled = true;
+    ctx.imageSmoothingQuality = 'medium';
+    ctx.drawImage(source as CanvasImageSource, rect.x, rect.y, rect.width, rect.height, 0, 0, width, height);
+    const rgba = ctx.getImageData(0, 0, width, height).data;
+    rgbaToLuma(rgba, out);
+  }
+
+  destroy() {
+    this.canvas.width = this.canvas.height = 0;
+  }
+}
+
+export function createGrabber(backend: 'auto' | 'webgl' | 'canvas' = 'auto'): FrameGrabber {
+  if (backend !== 'canvas') {
+    const gl = WebGLGrabber.create();
+    if (gl) return backend === 'auto' ? new AdaptiveGrabber(gl, () => new CanvasGrabber()) : gl;
+    if (backend === 'webgl') throw new Error('WebGL2 is not available');
+  }
+  return new CanvasGrabber();
+}
+
+/** Frames timed per backend before deciding. */
+const PROBE_FRAMES = 15;
+/** WebGL is kept without probing when its median grab is below this (ms). */
+const SLOW_GRAB_MS = 20;
+/** Canvas 2D must be this much faster to be kept: it blocks the main thread. */
+const CANVAS_WIN_RATIO = 0.6;
+
+/**
+ * `'auto'` backend: WebGL2, unless Canvas 2D is measured to be much faster on
+ * this device.
+ *
+ * WebGL does the crop / luma / downscale on the GPU and reads back 4× less
+ * data, asynchronously, so it is the right default. But on some GPUs the
+ * readback itself is slow (the fence takes tens of ms to signal), and then
+ * the grab limits the frame rate now that decoding runs in parallel. So when
+ * the median WebGL grab exceeds `SLOW_GRAB_MS`, Canvas 2D is timed on the
+ * next `PROBE_FRAMES` frames and kept only if clearly faster (`drawImage` +
+ * `getImageData` run on the main thread, while WebGL waits asynchronously).
+ * The decision is made once, from measurements: no device list.
+ */
+export class AdaptiveGrabber implements FrameGrabber {
+  private active: FrameGrabber;
+  private other: FrameGrabber | null = null;
+  private samples: number[] = [];
+  private webglMedian = 0;
+  private state: 'webgl' | 'probing' | 'decided' = 'webgl';
+
+  constructor(
+    private webgl: FrameGrabber,
+    private makeCanvas: () => FrameGrabber,
+    private now: () => number = () => performance.now(),
+  ) {
+    this.active = webgl;
+  }
+
+  get kind(): 'webgl' | 'canvas' {
+    return this.active.kind;
+  }
+
+  async grab(source: TexImageSource, rect: Rect, width: number, height: number, out: Uint8Array) {
+    const grabber = this.active;
+    const t0 = this.now();
+    await grabber.grab(source, rect, width, height, out);
+    if (this.state !== 'decided' && grabber === this.active) this.record(this.now() - t0);
+  }
+
+  private record(ms: number): void {
+    this.samples.push(ms);
+    if (this.samples.length < PROBE_FRAMES) return;
+    const median = medianOf(this.samples);
+    this.samples = [];
+    if (this.state === 'webgl') {
+      if (median < SLOW_GRAB_MS) {
+        this.state = 'decided';
+        return;
+      }
+      this.webglMedian = median;
+      this.other = this.webgl;
+      this.active = this.makeCanvas();
+      this.state = 'probing';
+      return;
+    }
+    // Probing Canvas 2D: keep it, or go back to WebGL.
+    this.state = 'decided';
+    if (median < this.webglMedian * CANVAS_WIN_RATIO) {
+      this.other?.destroy();
+    } else {
+      this.active.destroy();
+      this.active = this.webgl;
+    }
+    this.other = null;
+  }
+
+  destroy(): void {
+    this.active.destroy();
+    this.other?.destroy();
+  }
+}
+
+function medianOf(values: number[]): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[sorted.length >> 1] ?? 0;
+}
+
+/** BT.601 luma with integer arithmetic (same weights as the GPU path and the engine). */
+export function rgbaToLuma(rgba: Uint8ClampedArray | Uint8Array, out: Uint8Array): void {
+  const n = Math.min(out.length, rgba.length >> 2);
+  for (let i = 0, j = 0; i < n; i++, j += 4) {
+    // In bounds by construction (`n`): `?? 0` only satisfies the type checker.
+    out[i] = (19595 * (rgba[j] ?? 0) + 38470 * (rgba[j + 1] ?? 0) + 7471 * (rgba[j + 2] ?? 0)) >> 16;
+  }
+}
+
+export function sourceSize(source: TexImageSource): [number, number] {
+  if (typeof HTMLVideoElement !== 'undefined' && source instanceof HTMLVideoElement) {
+    return [source.videoWidth, source.videoHeight];
+  }
+  if (typeof HTMLImageElement !== 'undefined' && source instanceof HTMLImageElement) {
+    return [source.naturalWidth, source.naturalHeight];
+  }
+  if (typeof VideoFrame !== 'undefined' && source instanceof VideoFrame) {
+    return [source.displayWidth, source.displayHeight];
+  }
+  const s = source as { width: number; height: number };
+  return [s.width, s.height];
+}
+
+// ── WebGL helpers ──────────────────────────────────────────────────────────
+
+function must<T>(v: T | null, what: string): T {
+  if (!v) throw new Error(`WebGL: failed to create ${what}`);
+  return v;
+}
+
+function texture(gl: WebGL2RenderingContext): WebGLTexture {
+  const t = must(gl.createTexture(), 'texture');
+  gl.bindTexture(gl.TEXTURE_2D, t);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+  return t;
+}
+
+function link(gl: WebGL2RenderingContext, vs: string, fs: string): WebGLProgram {
+  const compile = (type: number, src: string) => {
+    const s = must(gl.createShader(type), 'shader');
+    gl.shaderSource(s, src);
+    gl.compileShader(s);
+    if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) throw new Error(`Shader: ${gl.getShaderInfoLog(s)}`);
+    return s;
+  };
+  const p = must(gl.createProgram(), 'program');
+  gl.attachShader(p, compile(gl.VERTEX_SHADER, vs));
+  gl.attachShader(p, compile(gl.FRAGMENT_SHADER, fs));
+  gl.linkProgram(p);
+  if (!gl.getProgramParameter(p, gl.LINK_STATUS)) throw new Error(`Program: ${gl.getProgramInfoLog(p)}`);
+  return p;
+}
+
+function waitSync(gl: WebGL2RenderingContext, sync: WebGLSync): Promise<void> {
+  return new Promise((resolve) => {
+    const started = performance.now();
+    const poll = () => {
+      const status = gl.clientWaitSync(sync, 0, 0);
+      // Give up waiting after 50 ms: getBufferSubData will then block, but never hang.
+      if (status !== gl.TIMEOUT_EXPIRED || performance.now() - started > 50) resolve();
+      else setTimeout(poll, 1);
+    };
+    poll();
+  });
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+export { BarcodeReader } from './reader.js';
+export { scanImage, type ImageInput, type ScanImageOptions } from './scan-image.js';
+export { createEngine, type Engine, type FrameReply } from './engine.js';
+export { listCameras } from './camera.js';
+export type {
+  AssetOptions,
+  BarcodeFormat,
+  CameraOptions,
+  CameraResolution,
+  Detection,
+  EngineOptions,
+  FeedbackOptions,
+  OverlayOptions,
+  Point,
+  ProcessingOptions,
+  ReaderEvents,
+  ReaderOptions,
+  ReaderStats,
+  Region,
+} from './types.js';