@mrbilit/mrz-scanner

Top-level orchestrator. Combines @mrbilit/mrz-detection, @mrbilit/mrz-ocr, and @mrbilit/mrz-core into a single scanMrz(image) entry point.

This package is part of the mrbilit/mrz-scanner fork of the original alsenet-labs/mrz-scanner project.

Install

npm install @mrbilit/mrz-scanner image-js onnxruntime-web

Usage

import { decode } from 'image-js';
import { scanMrz } from '@mrbilit/mrz-scanner';

const image = decode(bytes);

const result = await scanMrz(image, {
  modelPath: '/mrz-cnn.onnx',
  onProgress: (stage) => console.log(stage),   // 'detecting' | 'ocr' | 'parsing'
});

if (result.parsed?.valid) {
  console.log(result.parsed.fields);
} else {
  console.log('OCR lines:', result.ocrLines);
  console.log('Error:', result.error);
}

Pipeline

1. Lazy-initialize a shared MrzOcr instance on first call (cached between calls — model is only loaded once).
2. getMrz(image, { debug }) localizes and crops the MRZ region.
3. ocr.recognize(crop) produces lines + per-character confidence.
4. parse(lines) validates and, if necessary, applies OCR-confusion corrections from @mrbilit/mrz-core.

Fallback

If detection throws (e.g. the image is already a tight MRZ crop, or the morphology pipeline rejects the region), scanMrz runs OCR directly on the full input image and returns whatever it finds. Only if that also fails is the detection error propagated back in result.error.

Exports

interface ScanMrzOptions {
  modelPath?: string;
  onProgress?: ScanProgress;
  debug?: boolean;             // include detection debug images in the result
}

interface ScanMrzResult {
  parsed?: ParseResult;        // from @mrbilit/mrz-core (extends mrz v5 result)
  ocrLines?: string[];
  confidence?: number[][];
  error?: Error;
  debugImages?: Record<string, unknown>;
}

function scanMrz(image: Image, options?: ScanMrzOptions): Promise<ScanMrzResult>

Also re-exports parse, ScanProgress, OcrResult, ParseResult from @mrbilit/mrz-core, and MrzDetectionResult / MrzOcrResult from the other packages.

Node.js

In Node.js the OCR sub-package needs the native runtime explicitly. Build your own pipeline from the lower-level packages — see the top-level README section "Node.js Usage" for an example — or reuse the CLI (@mrbilit/mrz-cli) which wires it up for you.

License

AGPL-3.0-or-later.