@zimecode/scanner

@zimecode/scanner provides browser utilities to detect and decode Zimecode markers from a live camera stream.

Installation

npm install @zimecode/scanner

What this package exports

import { startCameraAndDetect, decode } from "@zimecode/scanner";

• startCameraAndDetect(...) starts camera capture, scans frames with OpenCV.js, and returns detection candidates.
• decode(...) converts a candidate matrix into a Zime ID string.

Requirements

This package is designed for browsers and needs:

• A camera-capable browser (navigator.mediaDevices.getUserMedia)
• OpenCV.js loaded globally as window.cv
• DOM elements for video and canvases

Example OpenCV.js include:

<script async src="https://docs.opencv.org/4.x/opencv.js"></script>

Quick start

<video id="video" playsinline muted></video>
<canvas id="srcCanvas"></canvas>
<canvas id="dbgCanvas"></canvas>

import { startCameraAndDetect, decode } from "@zimecode/scanner";

const settings = {
  video: document.getElementById("video"),
  srcCanvas: document.getElementById("srcCanvas"),
  dbgCanvas: document.getElementById("dbgCanvas"),
  scanWindow: {
    enabled: true,
    sizeRatio: 0.5,
  },
  invertBeforeScan: false,
  scanBothPolarities: false,
};

startCameraAndDetect({
  settings,
  callback: (candidates) => {
    for (const candidate of candidates) {
      const zimeId = decode({ matrix: candidate.matrix });

      if (zimeId) {
        console.log("Decoded Zime ID:", zimeId, "dimension:", candidate.dimension);
      }
    }
  },
}).catch(console.error);

API

startCameraAndDetect({ settings, callback })

Starts a continuous detection loop.

• settings.video: <video> element
• settings.srcCanvas: hidden/processing canvas
• settings.dbgCanvas: visible canvas for rendered camera output and overlays
• settings.scanWindow (optional): visual square guide overlay
  • enabled (boolean): show/hide guide overlay
  • sizeRatio (number, default 0.5): square side relative to viewport short edge
  • shadeColor (string, default rgba(0, 0, 0, 0.5)): color for darkened outside area
  • borderColor (string, default rgba(255, 255, 255, 0.9)): guide border color
  • borderWidth (number, default 2): guide border width in CSS pixels
• settings.invertBeforeScan (optional, default false): inverts camera frame colors before detection and matrix sampling (useful for testing color-inverted Zimecodes)
• settings.scanBothPolarities (optional, default false): scans each frame sequentially in normal colors and then inverted colors; when enabled, this takes precedence over invertBeforeScan
• callback(candidates): called per frame with detected candidates

Each candidate includes (among others):

• quad: detected marker corner points in video coordinates
• quadCanvas: mapped corner points in debug-canvas coordinates
• dimension: estimated Zimecode dimension
• score: detection quality score
• matrix: sampled 2S x 2S bit matrix for decoding
• scanInverted: true if the candidate came from the inverted scan pass, otherwise false

decode({ matrix })

Decodes a sampled matrix and returns a decimal Zime ID (string) when redundancy checks pass. If decoding fails, it returns undefined.

Notes

• The package is browser-focused (not intended for plain Node.js runtime).
• Camera permission is required.
• Detection quality depends on focus, lighting, and marker size.