@mrbilit/mrz-scanner 2.0.0

package/README.md

@@ -0,0 +1,87 @@
+# @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](https://github.com/mrbilit/mrz-scanner)
+fork of the original [alsenet-labs/mrz-scanner](https://github.com/alsenet-labs/mrz-scanner)
+project.
+
+## Install
+
+```bash
+npm install @mrbilit/mrz-scanner image-js onnxruntime-web
+```
+
+## Usage
+
+```ts
+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
+
+```ts
+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.

package/dist/index.d.ts

@@ -0,0 +1,64 @@
+import { Image as Image_2 } from 'image-js';
+import { MrzDetectionResult } from '@mrbilit/mrz-detection';
+import { MrzOcrResult } from '@mrbilit/mrz-ocr';
+import { OcrResult } from '@mrbilit/mrz-core';
+import { parse } from '@mrbilit/mrz-core';
+import { ParseResult } from '@mrbilit/mrz-core';
+import { ScanProgress } from '@mrbilit/mrz-core';
+
+export { MrzDetectionResult }
+
+export { MrzOcrResult }
+
+export { OcrResult }
+
+export { parse }
+
+export { ParseResult }
+
+/**
+ * Scan a document image for MRZ data.
+ *
+ * @param image - An image-js Image of the document
+ * @param options - Configuration options
+ * @returns Parsed MRZ result with fields, or error details
+ *
+ * @example
+ * ```ts
+ * import { Image } from 'image-js';
+ * import { scanMrz } from '@mrbilit/mrz-scanner';
+ *
+ * const image = await Image.load('passport.jpg');
+ * const result = await scanMrz(image);
+ * if (result.parsed?.valid) {
+ *   console.log(result.parsed.fields);
+ * }
+ * ```
+ */
+export declare function scanMrz(image: Image_2, options?: ScanMrzOptions): Promise<ScanMrzResult>;
+
+export declare interface ScanMrzOptions {
+    /** URL or file path to the ONNX model */
+    modelPath?: string;
+    /** Progress callback for UI feedback */
+    onProgress?: ScanProgress;
+    /** Enable debug mode (returns intermediate images) */
+    debug?: boolean;
+}
+
+export declare interface ScanMrzResult {
+    /** Parsed and validated MRZ fields */
+    parsed?: ParseResult;
+    /** Raw OCR text lines */
+    ocrLines?: string[];
+    /** Per-character confidence scores */
+    confidence?: number[][];
+    /** Error if any stage failed */
+    error?: Error;
+    /** Debug images from the detection stage */
+    debugImages?: Record<string, unknown>;
+}
+
+export { ScanProgress }
+
+export { }

package/dist/index.js

@@ -0,0 +1,26 @@
+import { getMrz as e } from "@mrbilit/mrz-detection";
+import { MrzOcr as t } from "@mrbilit/mrz-ocr";
+import { parse as n, parse as r } from "@mrbilit/mrz-core";
+//#region src/scan-mrz.ts
+var i = null;
+async function a(n, a = {}) {
+	let { onProgress: o, debug: s = !1 } = a, c = {};
+	o?.("detecting"), i || (i = new t({ modelPath: a.modelPath }), await i.init());
+	try {
+		let t = e(n, { debug: s });
+		s && (c.debugImages = t.debugImages), o?.("ocr");
+		let a = await i.recognize(t.crop);
+		c.ocrLines = a.lines, c.confidence = a.confidence, o?.("parsing"), c.parsed = r(a.lines);
+	} catch (e) {
+		try {
+			o?.("ocr");
+			let t = await i.recognize(n);
+			t.lines.length > 0 ? (c.ocrLines = t.lines, c.confidence = t.confidence, o?.("parsing"), c.parsed = r(t.lines)) : c.error = e instanceof Error ? e : Error(String(e));
+		} catch {
+			c.error = e instanceof Error ? e : Error(String(e));
+		}
+	}
+	return c;
+}
+//#endregion
+export { n as parse, a as scanMrz };

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@mrbilit/mrz-scanner",
+  "version": "2.0.0",
+  "description": "Full MRZ scanning pipeline: detect, OCR, and parse",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite build --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@mrbilit/mrz-core": "2.0.0",
+    "@mrbilit/mrz-detection": "2.0.0",
+    "@mrbilit/mrz-ocr": "2.0.0",
+    "image-js": "^1.5.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vite": "^8.0.0",
+    "vite-plugin-dts": "^4.5.0"
+  },
+  "license": "AGPL-3.0-or-later"
+}