@mrbilit/mrz-ocr 2.0.0

package/README.md

@@ -0,0 +1,145 @@
+# @mrbilit/mrz-ocr
+
+MRZ character recognition using a small ONNX CNN. Replaces the HOG+SVM
+pipeline in the original mrz-detection project. Runs on `onnxruntime-web`
+(WASM) in the browser and can use `onnxruntime-node` in Node.js.
+
+This package is part of [mrbilit/mrz-scanner](https://github.com/mrbilit/mrz-scanner),
+a fork of [alsenet-labs/mrz-scanner](https://github.com/alsenet-labs/mrz-scanner).
+
+## Install
+
+For browser applications:
+
+```bash
+npm install @mrbilit/mrz-ocr
+```
+
+For Node.js applications, also install the native ONNX Runtime:
+
+```bash
+npm install @mrbilit/mrz-ocr onnxruntime-node
+```
+
+## Usage (Browser)
+
+```ts
+import { decode } from 'image-js';
+import { MrzOcr } from '@mrbilit/mrz-ocr';
+
+const ocr = new MrzOcr({
+  modelPath: '/mrz-cnn.onnx', // served as a static asset
+});
+
+await ocr.init();
+
+const image = decode(bytes);
+const { lines, confidence } = await ocr.recognize(image);
+```
+
+## Usage (Node.js)
+
+```ts
+import { MrzOcr } from '@mrbilit/mrz-ocr';
+import * as ort from 'onnxruntime-node';
+
+const ocr = new MrzOcr({
+  modelPath: './models/mrz-cnn.onnx',
+  ort, // required in Node.js; browser builds default to onnxruntime-web
+});
+
+await ocr.init();
+```
+
+## Recognition pipeline
+
+`recognize(image)` assumes the input is a tight crop of the MRZ band (what
+`@mrbilit/mrz-detection` produces):
+
+1. Greyscale + Otsu threshold on the crop.
+2. Connected-component ROIs; try black-pixel ROIs first, fall back to white.
+3. Filter by aspect ratio (0.3–3.0), cluster into lines by center-Y
+   (line height ≈ `image.height / 6`).
+4. Drop short lines (`minCharsPerLine`, default 5) and keep the last
+   `maxLines` (default 3) — covers TD1 (3 lines) and TD2/TD3 (2 lines).
+5. Sort each line left-to-right, resize each character to 20×20, normalize
+   to `[0, 1]`, and batch into a single `(N, 1, 20, 20)` tensor.
+6. Run the ONNX session; apply softmax over the 37 output logits; emit the
+   argmax character and its probability as confidence.
+
+## Model
+
+- Architecture: `Conv(1→32, 3×3)→ReLU→MaxPool→Conv(32→64, 3×3)→ReLU→MaxPool→
+  Flatten→Dense(128)→ReLU→Dropout(0.3)→Dense(37)`.
+- ≈75 K parameters, ≈917 KB ONNX (opset 17).
+- 37 classes: `0-9`, `A-Z`, `<`.
+- Shipped at `models/mrz-cnn.onnx` with a `models/mrz-cnn.json` sidecar
+  recording the symbol table and last test accuracy.
+
+## Retraining
+
+From `packages/mrz-ocr/training`:
+
+```bash
+cd packages/mrz-ocr/training
+pip install -r requirements.txt
+
+python extract_ocrb.py
+python train_cnn.py --data-dir ./ocrb_chars --output ../models/mrz-cnn.onnx
+
+# Or synthetic data only:
+python train_cnn.py --generate --output ../models/mrz-cnn.onnx
+```
+
+After retraining, rebuild any consumer that bundles the model asset.
+
+## Exports
+
+```ts
+interface MrzOcrOptions {
+  modelPath?: string;          // default 'mrz-cnn.onnx'
+  minCharsPerLine?: number;    // default 5
+  maxLines?: number;           // default 3
+  ort?: OrtModule;             // pass onnxruntime-node in Node.js
+}
+
+interface MrzOcrResult {
+  lines: string[];
+  confidence: number[][];      // per-character softmax probabilities
+}
+
+class MrzOcr {
+  constructor(options?: MrzOcrOptions);
+  init(): Promise<void>;
+  recognize(image: Image): Promise<MrzOcrResult>;
+}
+
+const MRZ_SYMBOLS: readonly string[];
+```
+
+## Security
+
+Constructor inputs are validated:
+
+- `modelPath` must end in `.onnx`; `..` is rejected; only `http(s)://` URLs
+  and local paths are allowed (no `file://`, `data:`, `ftp://`).
+- `recognize()` refuses images above 20 megapixels to bound memory.
+
+## Development
+
+From the monorepo root:
+
+```bash
+yarn install
+yarn workspace @mrbilit/mrz-ocr build
+yarn workspace @mrbilit/mrz-ocr typecheck
+```
+
+## License
+
+This project is distributed under the GNU Affero General Public License,
+version 3 or later (AGPL-3.0-or-later).
+
+The original project and source code are Copyright © 2018-2025 ALSENET SA.
+
+See [LICENSE](../../LICENSE) for the full license text.

package/dist/index.d.ts

@@ -0,0 +1,78 @@
+import { Image as Image_2 } from 'image-js';
+
+export declare const MRZ_SYMBOLS: readonly string[];
+
+/**
+ * ONNX-based MRZ OCR engine.
+ *
+ * Usage:
+ *   const ocr = new MrzOcr({ modelPath: './mrz-cnn.onnx' });
+ *   await ocr.init();
+ *   const result = await ocr.recognize(croppedMrzImage);
+ */
+export declare class MrzOcr {
+    private session;
+    private ort;
+    private options;
+    private ortOverride;
+    constructor(options?: MrzOcrOptions);
+    /**
+     * Initialize the ONNX inference session.
+     * Must be called before recognize().
+     *
+     * In the browser, onnxruntime-web is imported automatically.
+     * In Node.js, pass the ort module via the constructor:
+     *   new MrzOcr({ ort: await import('onnxruntime-node') })
+     */
+    init(): Promise<void>;
+    /**
+     * Recognize MRZ text from a cropped MRZ image.
+     * The image should contain just the MRZ region (output of detection stage).
+     */
+    recognize(image: Image_2): Promise<MrzOcrResult>;
+    /**
+     * Segment the MRZ image into individual character images.
+     * Uses Otsu thresholding and connected component analysis.
+     */
+    private segmentCharacters;
+    /**
+     * Run batch inference on character images.
+     * Preprocesses all characters into a single tensor for efficient inference.
+     */
+    private predictBatch;
+}
+
+export declare interface MrzOcrOptions {
+    /** URL or file path to the ONNX model */
+    modelPath?: string;
+    /** Minimum characters per line to be considered valid */
+    minCharsPerLine?: number;
+    /** Maximum number of MRZ lines to keep */
+    maxLines?: number;
+    /** Provide the ONNX Runtime module directly (for Node.js, pass `import('onnxruntime-node')`) */
+    ort?: OrtModule;
+}
+
+export declare interface MrzOcrResult {
+    lines: string[];
+    confidence: number[][];
+}
+
+declare interface OrtModule {
+    InferenceSession: {
+        create(path: string, options?: {
+            executionProviders?: string[];
+        }): Promise<OrtSession>;
+    };
+    Tensor: new (type: string, data: Float32Array, dims: number[]) => OrtTensor;
+}
+
+declare interface OrtSession {
+    run(feeds: Record<string, OrtTensor>): Promise<Record<string, OrtTensor>>;
+}
+
+declare interface OrtTensor {
+    data: Float32Array;
+}
+
+export { }

package/dist/index.js

@@ -0,0 +1,130 @@
+import { crop as e, fromMask as t, getRois as n, grey as r, resize as i, threshold as a } from "image-js";
+//#region src/symbols.ts
+var o = [..."0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ<"], s = 2e7;
+function c(e) {
+	if (e.includes("..")) throw Error("Invalid model path: path traversal (..) not allowed");
+	if (e.startsWith("http://") || e.startsWith("https://")) {
+		if (!e.endsWith(".onnx")) throw Error("Invalid model URL: must end with .onnx");
+		return;
+	}
+	if (/^[a-z]+:\/\//i.test(e)) throw Error("Invalid model path: only http(s) URLs or local paths allowed");
+	if (!e.endsWith(".onnx")) throw Error("Invalid model path: must end with .onnx");
+}
+var l = {
+	positive: !0,
+	negative: !1,
+	minSurface: 5,
+	minRatio: .3,
+	maxRatio: 3,
+	algorithm: "otsu"
+}, u = class {
+	session = null;
+	ort = null;
+	options;
+	ortOverride;
+	constructor(e = {}) {
+		let t = e.modelPath ?? "mrz-cnn.onnx";
+		c(t), this.options = {
+			modelPath: t,
+			minCharsPerLine: e.minCharsPerLine ?? 5,
+			maxLines: e.maxLines ?? 3
+		}, this.ortOverride = e.ort;
+	}
+	async init() {
+		this.ort = this.ortOverride ? this.ortOverride : await import("onnxruntime-web"), this.session = await this.ort.InferenceSession.create(this.options.modelPath, { executionProviders: ["wasm"] });
+	}
+	async recognize(e) {
+		if (e.width * e.height > s) throw Error(`Image too large (${e.width}x${e.height}). Max ${s} pixels.`);
+		let { charImages: t, lineBreaks: n } = this.segmentCharacters(e);
+		if (t.length === 0) return {
+			lines: [],
+			confidence: []
+		};
+		let r = await this.predictBatch(t), i = [], a = [], o = "", c = [], l = 0;
+		for (let e = 0; e < r.length; e++) n.includes(e) && o.length > 0 && (i.push(o), a.push(c), o = "", c = []), o += r[l].char, c.push(r[l].confidence), l++;
+		return o.length > 0 && (i.push(o), a.push(c)), {
+			lines: i,
+			confidence: a
+		};
+	}
+	segmentCharacters(i) {
+		let o = i.colorModel === "GREY" ? i : r(i), s = a(o, { algorithm: l.algorithm }), c = t(s), u = n(c, {
+			minSurface: l.minSurface,
+			kind: "black"
+		});
+		if (u.length === 0 && (u = n(c, {
+			minSurface: l.minSurface,
+			kind: "white"
+		})), u.length === 0) return {
+			charImages: [],
+			lineBreaks: []
+		};
+		let d = u.map((e) => ({
+			roi: e,
+			minX: e.origin.column,
+			minY: e.origin.row,
+			maxX: e.origin.column + e.width,
+			maxY: e.origin.row + e.height,
+			width: e.width,
+			height: e.height,
+			centerY: e.origin.row + e.height / 2
+		})).filter((e) => {
+			let t = e.width / e.height;
+			return t >= l.minRatio && t <= l.maxRatio;
+		}), f = i.height / 6, p = [], m = [], h = [...d].sort((e, t) => e.centerY - t.centerY);
+		for (let e of h) m.length === 0 || Math.abs(e.centerY - m[0].centerY) < f ? m.push(e) : (p.push(m), m = [e]);
+		m.length > 0 && p.push(m);
+		let g = p.filter((e) => e.length >= this.options.minCharsPerLine).slice(-this.options.maxLines), _ = [], v = [];
+		for (let t of g) {
+			v.push(_.length);
+			let n = t.sort((e, t) => e.minX - t.minX);
+			for (let t of n) {
+				let n = e(o, {
+					origin: {
+						column: t.minX,
+						row: t.minY
+					},
+					width: t.width,
+					height: t.height
+				});
+				_.push(n);
+			}
+		}
+		return {
+			charImages: _,
+			lineBreaks: v
+		};
+	}
+	async predictBatch(e) {
+		if (!this.session || !this.ort) throw Error("MrzOcr not initialized. Call init() first.");
+		let t = this.ort, n = e.length, a = new Float32Array(n * 1 * 20 * 20);
+		for (let t = 0; t < e.length; t++) {
+			let n = i(e[t], {
+				width: 20,
+				height: 20
+			}), o = n.colorModel === "GREY" ? n : r(n), s = t * 20 * 20;
+			for (let e = 0; e < 20; e++) for (let t = 0; t < 20; t++) a[s + e * 20 + t] = o.getValue(t, e, 0) / 255;
+		}
+		let s = new t.Tensor("float32", a, [
+			n,
+			1,
+			20,
+			20
+		]), c = await this.session.run({ input: s }), l = c[Object.keys(c)[0]].data, u = o.length, d = [];
+		for (let e = 0; e < n; e++) {
+			let t = e * u, n = 0, r = -Infinity, i = 0, a = new Float32Array(u);
+			for (let e = 0; e < u; e++) a[e] = Math.exp(l[t + e]), i += a[e];
+			for (let e = 0; e < u; e++) {
+				let t = a[e] / i;
+				t > r && (r = t, n = e);
+			}
+			d.push({
+				char: o[n],
+				confidence: r
+			});
+		}
+		return d;
+	}
+};
+//#endregion
+export { o as MRZ_SYMBOLS, u as MrzOcr };

package/models/mrz-cnn.json

@@ -0,0 +1,44 @@
+{
+  "symbols": [
+    "0",
+    "1",
+    "2",
+    "3",
+    "4",
+    "5",
+    "6",
+    "7",
+    "8",
+    "9",
+    "A",
+    "B",
+    "C",
+    "D",
+    "E",
+    "F",
+    "G",
+    "H",
+    "I",
+    "J",
+    "K",
+    "L",
+    "M",
+    "N",
+    "O",
+    "P",
+    "Q",
+    "R",
+    "S",
+    "T",
+    "U",
+    "V",
+    "W",
+    "X",
+    "Y",
+    "Z",
+    "<"
+  ],
+  "input_size": 20,
+  "num_classes": 37,
+  "accuracy": 1.0
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@mrbilit/mrz-ocr",
+  "version": "2.0.0",
+  "description": "MRZ character recognition using ONNX CNN model",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "models"],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "image-js": "^1.5.0",
+    "onnxruntime-web": "^1.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.5.0"
+  },
+  "license": "AGPL-3.0-or-later"
+}