mrz-genius 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihradj KYC Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# mrz-genius
+
+[![npm version](https://img.shields.io/npm/v/mrz-genius.svg?style=flat-square)](https://www.npmjs.com/package/mrz-genius)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-blue.svg?style=flat-square)](https://nodejs.org)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg?style=flat-square)](#)
+
+Bibliothèque Node.js complète pour la **détection**, l' **OCR** et le **parsing** des zones MRZ (Machine Readable Zone) sur les documents d'identité.
+
+### 📍 Workflow d'extraction
+
+```mermaid
+graph LR
+    A[Image Brute] --> B[Détection Zone MRZ]
+    B --> C[Optimisation Image]
+    C --> D[OCR Tesseract/LLM]
+    D --> E[Parsing & Correction]
+    E --> F[Données ID Validées]
+    style F fill:#10b981,stroke:#059669,color:#fff
+```
+
+Inspirée du module Swift [MRZParser](https://github.com/romanmazeev/MRZParser).
+
+## 📋 Formats supportés
+
+| Format | Type de document | Lignes | Caractères/ligne |
+|--------|-----------------|--------|------------------|
+| **TD1** | Cartes d'identité (CNI) | 3 | 30 |
+| **TD2** | Documents de voyage (format moyen) | 2 | 36 |
+| **TD3** | Passeports | 2 | 44 |
+| **MRVA** | Visas type A | 2 | 44 |
+| **MRVB** | Visas type B | 2 | 36 |
+
+## 🚀 Installation
+
+```bash
+npm install mrz-genius
+```
+
+Ou depuis les sources :
+
+```bash
+cd mrz-genius
+npm install
+```
+
+## 📖 Utilisation
+
+### 1. Pipeline complet : Image → MRZ parsé
+
+```javascript
+const { processImage } = require('mrz-genius');
+
+// Depuis un fichier image
+const result = await processImage('./passport.jpg');
+
+if (result.success) {
+  console.log('Nom:', result.parsed.surname);
+  console.log('Prénoms:', result.parsed.givenNames);
+  console.log('N° Document:', result.parsed.documentNumber);
+  console.log('Nationalité:', result.parsed.nationality);
+  console.log('Date naissance:', result.parsed.birthDateFormatted);
+  console.log('Date expiration:', result.parsed.expiryDateFormatted);
+  console.log('Sexe:', result.parsed.sex);
+}
+```
+
+### 2. Parser direct (texte MRZ)
+
+```javascript
+const { parseMRZ } = require('mrz-genius');
+
+// TD3 - Passeport
+const result = parseMRZ([
+  'P<UTOERIKSSON<<ANNA<MARIA<<<<<<<<<<<<<<<<<<<',
+  'L898902C36UTO7408122F1204159ZE184226B<<<<<10'
+]);
+
+console.log(result);
+// {
+//   success: true,
+//   ocr: { confidence: 98, method: 'full_image_threshold_140_3x' },
+//   parsed: {
+...
+//     surname: 'TOURE',
+//     documentNumber: 'CI0086201',
+//     ...
+//   }
+// }
+
+### 2. Option avec LLM (ChatGPT, Claude, Gemini)
+
+Pour remplacer l'OCR classique par les capacités de vision surpuissantes d'un modèle d'IA :
+
+```javascript
+const result = await processImage('./document.jpg', {
+  llm: {
+    provider: 'chatgpt', // ou 'anthropic', 'gemini', 'litellm'
+    apiKey: process.env.API_KEY,
+    model: 'gpt-4o' // (Optionnel) modèle spécifique
+  }
+});
+```
+
+### 3. Parser direct (texte MRZ)
+//   issuingCountry: 'UTO',
+//   surname: 'ERIKSSON',
+//   givenNames: 'ANNA MARIA',
+//   documentNumber: 'L898902C3',
+//   nationality: 'UTO',
+//   birthDate: Date,
+//   birthDateFormatted: '1974-08-12',
+//   sex: 'FEMALE',
+//   expiryDate: Date,
+//   expiryDateFormatted: '2012-04-15',
+//   optionalData1: 'ZE184226B',
+//   ...
+// }
+```
+
+### 3. Parsing avec texte multi-ligne
+
+```javascript
+const { parseMRZ } = require('mrz-genius');
+
+// TD1 - Carte d'identité
+const mrz = `I<UTOD231458907<<<<<<<<<<<<<<<
+7408122F1204159UTO<<<<<<<<<<<6
+ERIKSSON<<ANNA<MARIA<<<<<<<<<<`;
+
+const result = parseMRZ(mrz);
+```
+
+### 4. Détection de la zone MRZ sur image
+
+```javascript
+const { detectMRZRegion } = require('mrz-genius');
+
+const region = await detectMRZRegion('./document.jpg');
+console.log('Région MRZ:', region.x, region.y, region.width, region.height);
+console.log('Confiance:', region.confidence);
+// region.imageBuffer contient l'image croppée de la zone MRZ
+```
+
+### 5. OCR seul
+
+```javascript
+const { performOCR } = require('mrz-genius');
+
+const ocrResult = await performOCR('./passport.jpg');
+console.log('Lignes MRZ:', ocrResult.lines);
+console.log('Confiance OCR:', ocrResult.confidence);
+```
+
+### 6. Correction OCR
+
+```javascript
+const { parseMRZ } = require('mrz-genius');
+
+// Avec correction des erreurs OCR courantes (O→0, I→1, etc.)
+const result = parseMRZ(mrzText, { ocrCorrection: true });
+```
+
+### 7. Vérification de présence MRZ
+
+```javascript
+const { hasMRZ } = require('mrz-genius');
+
+const containsMRZ = await hasMRZ('./document.jpg');
+console.log('Document contient un MRZ:', containsMRZ);
+```
+
+## 🔧 API Complète
+
+### Haut niveau
+
+| Fonction | Description |
+|----------|-------------|
+| `processImage(image, options?)` | Pipeline complet : détection + OCR + parsing |
+| `parseMRZ(text, options?)` | Parse un texte MRZ directement |
+
+### Détection
+
+| Fonction | Description |
+|----------|-------------|
+| `detectMRZRegion(input, options?)` | Détecte la zone MRZ dans une image |
+| `optimizeForOCR(buffer, options?)` | Optimise une image pour l'OCR |
+| `preprocessForOCR(input, options?)` | Détection + optimisation combinées |
+
+### OCR
+
+| Fonction | Description |
+|----------|-------------|
+| `performOCR(input, options?)` | OCR Tesseract optimisé pour MRZ |
+| `hasMRZ(input)` | Vérifie si une image contient un MRZ |
+
+### Validation
+
+| Fonction | Description |
+|----------|-------------|
+| `calculateCheckDigit(value)` | Calcule le chiffre de contrôle ICAO |
+| `isCheckDigitValid(value, digit)` | Valide un chiffre de contrôle |
+| `isCompositeValid(fields, digit)` | Valide le chiffre de contrôle composite |
+
+### Correction OCR
+
+| Fonction | Description |
+|----------|-------------|
+### Correction OCR (Heuristiques d'auto-réparation)
+
+| Fonction | Description |
+|----------|-------------|
+| `correctOCR(str, contentType)` | Corrige les erreurs OCR courantes simples |
+| `repairFieldWithCheckDigit(val, cd)`| Répare par brute-force les confusions en vérifiant le Check Digit |
+| `repairIvorianDocumentNumber(doc)` | Corrige de force un numéro CNI pour correspondre aux normes Ivoiriennes |
+
+## 📦 Structure du résultat
+
+```typescript
+interface MRZResult {
+  valid: boolean;             // Tous les chiffres de contrôle sont valides
+  format: string;             // TD1, TD2, TD3, MRVA, MRVB
+  documentType: string;       // PASSPORT, VISA, ID_CARD
+  issuingCountry: string;     // Code pays ISO 3166-1 (3 lettres)
+  surname: string;            // Nom de famille
+  givenNames: string | null;  // Prénoms
+  documentNumber: string;     // Numéro du document
+  nationality: string;        // Code nationalité
+  birthDate: Date;            // Date de naissance
+  birthDateFormatted: string; // Format YYYY-MM-DD
+  sex: string;                // MALE, FEMALE, UNSPECIFIED
+  expiryDate: Date | null;    // Date d'expiration
+  expiryDateFormatted: string;
+  optionalData1: string | null;
+  optionalData2: string | null;  // TD1 uniquement
+  mrzKey: string;             // Clé BAC pour e-Passeports
+  rawMRZ: string;             // MRZ brut
+  details: {                  // Détails de validation
+    fields: { ... },
+    finalCheckDigitValid: boolean
+  };
+}
+```
+
+## 🧪 Tests
+
+```bash
+npm test
+```
+
+## 📐 Distribution des champs
+
+```
+TD1 (Carte d'identité) — 3 lignes × 30 caractères
+┌─────────────────────────────────────┐
+│ Ligne 1: Type|Pays|N°Document|Opt1  │
+│ Ligne 2: DDN|S|Exp|Nat|Opt2|Check   │
+│ Ligne 3: NOM<<PRÉNOMS               │
+└─────────────────────────────────────┘
+
+TD3 (Passeport) — 2 lignes × 44 caractères
+┌────────────────────────────────────────────────┐
+│ Ligne 1: Type|Pays|NOM<<PRÉNOMS                │
+│ Ligne 2: N°Doc|Nat|DDN|S|Exp|Opt1|Check        │
+└────────────────────────────────────────────────┘
+```
+
+## 📄 Licence
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "mrz-genius",
+  "version": "2.0.0",
+  "description": "Node.js library for MRZ detection, OCR, and parsing from identity documents (TD1, TD2, TD3, MRVA, MRVB)",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "scripts": {
+    "test": "node test/test.js",
+    "demo": "node ../example/index.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toure5013/mrz-genius.git"
+  },
+  "bugs": {
+    "url": "https://github.com/toure5013/mrz-genius/issues"
+  },
+  "homepage": "https://github.com/toure5013/mrz-genius#readme",
+  "keywords": [
+    "mrz",
+    "passport",
+    "id-card",
+    "ocr",
+    "identity",
+    "travel-document",
+    "machine-readable-zone",
+    "kyc",
+    "td1",
+    "td2",
+    "td3",
+    "visa"
+  ],
+  "author": "toure5013",
+  "license": "MIT",
+  "dependencies": {
+    "sharp": "^0.33.2",
+    "tesseract.js": "^5.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/detector/mrzDetector.js

@@ -0,0 +1,214 @@
+/**
+ * MRZ Detector
+ * Detects and extracts the MRZ zone from an identity document image
+ * Uses image processing techniques (sharp) to locate and crop the MRZ region
+ */
+
+'use strict';
+
+const sharp = require('sharp');
+
+/**
+ * Preprocess image for better MRZ detection
+ * @param {Buffer|string} input - Image buffer or file path
+ * @returns {Promise<{metadata: Object, buffer: Buffer}>}
+ */
+async function preprocessImage(input) {
+  const image = sharp(input);
+  const metadata = await image.metadata();
+
+  const processed = sharp(input)
+    .grayscale()
+    .normalize()
+    .sharpen({ sigma: 1.5 })
+    .modulate({ brightness: 1.1 });
+
+  const buffer = await processed.toBuffer();
+  return { metadata, buffer };
+}
+
+/**
+ * Detect MRZ region in an image.
+ * Strategy: crop the bottom portion of the document where MRZ always resides.
+ * For ID cards (TD1), MRZ is ~25-35% from bottom.
+ * For passports (TD3), MRZ is ~15-25% from bottom.
+ * 
+ * @param {Buffer|string} input - Image buffer or file path
+ * @param {Object} [options] - Detection options
+ * @param {number} [options.bottomPercent=45] - Bottom percentage of image to scan
+ * @param {number} [options.padding=5] - Padding around detected MRZ in pixels
+ * @returns {Promise<Object|null>} Detected MRZ region
+ */
+async function detectMRZRegion(input, options = {}) {
+  const { bottomPercent = 45, padding = 5 } = options;
+
+  try {
+    const { metadata } = await preprocessImage(input);
+    const { width, height } = metadata;
+
+    if (!width || !height) {
+      throw new Error('Unable to read image dimensions');
+    }
+
+    // MRZ is at the bottom of the document
+    const mrzTopStart = Math.floor(height * (1 - bottomPercent / 100));
+    const mrzHeight = height - mrzTopStart;
+
+    // Crop bottom region
+    const extractTop = Math.max(0, mrzTopStart - padding);
+    const extractHeight = Math.min(mrzHeight + padding * 2, height - extractTop);
+
+    const croppedBuffer = await sharp(input)
+      .extract({
+        left: 0,
+        top: extractTop,
+        width: width,
+        height: extractHeight,
+      })
+      .grayscale()
+      .normalize()
+      .sharpen({ sigma: 2 })
+      .toBuffer();
+
+    // Analyze rows to find the MRZ text band
+    const analyzed = sharp(croppedBuffer);
+    const analyzedMeta = await analyzed.metadata();
+    const rawBuffer = await analyzed.raw().toBuffer();
+
+    const cropHeight = analyzedMeta.height;
+    const cropWidth = analyzedMeta.width;
+    const channels = analyzedMeta.channels || 1;
+
+    // Calculate horizontal text density per row
+    const rowDensities = [];
+    for (let y = 0; y < cropHeight; y++) {
+      let darkPixelCount = 0;
+      for (let x = 0; x < cropWidth; x++) {
+        const pixel = rawBuffer[y * cropWidth * channels + x * channels];
+        if (pixel < 120) darkPixelCount++;
+      }
+      rowDensities.push(darkPixelCount / cropWidth);
+    }
+
+    // Find continuous bands of high text density (MRZ lines)
+    const threshold = 0.12;
+    let bestStart = -1;
+    let bestEnd = -1;
+    let bestLength = 0;
+    let currentStart = -1;
+    let consecutiveRows = 0;
+
+    for (let y = 0; y < cropHeight; y++) {
+      if (rowDensities[y] > threshold) {
+        if (currentStart === -1) currentStart = y;
+        consecutiveRows++;
+      } else {
+        if (consecutiveRows > bestLength && consecutiveRows > 3) {
+          bestStart = currentStart;
+          bestEnd = y - 1;
+          bestLength = consecutiveRows;
+        }
+        currentStart = -1;
+        consecutiveRows = 0;
+      }
+    }
+
+    // Check last segment
+    if (consecutiveRows > bestLength && consecutiveRows > 3) {
+      bestStart = currentStart;
+      bestEnd = cropHeight - 1;
+      bestLength = consecutiveRows;
+    }
+
+    // Extract the MRZ band or fall back to full bottom crop
+    let mrzBuffer;
+    let confidence = 'low';
+
+    if (bestStart !== -1 && bestLength > 5) {
+      const absoluteTop = Math.max(0, extractTop + bestStart - padding * 2);
+      const bandHeight = Math.min(bestLength + padding * 4, height - absoluteTop);
+
+      mrzBuffer = await sharp(input)
+        .extract({
+          left: 0,
+          top: absoluteTop,
+          width: width,
+          height: bandHeight,
+        })
+        .grayscale()
+        .normalize()
+        .sharpen({ sigma: 2 })
+        .toBuffer();
+
+      confidence = 'high';
+    } else {
+      // Fallback: the whole bottom region
+      mrzBuffer = croppedBuffer;
+    }
+
+    return {
+      x: 0,
+      y: extractTop,
+      width: width,
+      height: extractHeight,
+      imageBuffer: mrzBuffer,
+      confidence,
+    };
+  } catch (error) {
+    throw new Error(`MRZ detection failed: ${error.message}`);
+  }
+}
+
+/**
+ * Create an OCR-optimized image from the detected MRZ region
+ * @param {Buffer} mrzImageBuffer - MRZ region image buffer
+ * @param {Object} [options] - Options
+ * @param {number} [options.scaleFactor=3] - Upscale factor for better OCR
+ * @param {number} [options.threshold=140] - Binarization threshold
+ * @returns {Promise<Buffer>} OCR-optimized image buffer
+ */
+async function optimizeForOCR(mrzImageBuffer, options = {}) {
+  const { scaleFactor = 3, threshold = 140 } = options;
+
+  const meta = await sharp(mrzImageBuffer).metadata();
+  const targetWidth = meta.width * scaleFactor;
+  const targetHeight = meta.height * scaleFactor;
+
+  return sharp(mrzImageBuffer)
+    .resize(targetWidth, targetHeight, {
+      kernel: sharp.kernel.lanczos3,
+      fit: 'fill',
+    })
+    .grayscale()
+    .normalize()
+    .sharpen({ sigma: 2, m1: 2, m2: 3 })
+    .threshold(threshold)
+    .toBuffer();
+}
+
+/**
+ * Full preprocessing pipeline: detect MRZ region + optimize for OCR
+ * @param {Buffer|string} input - Image path or buffer
+ * @param {Object} [options] - Options
+ * @returns {Promise<{region: Object, ocrReadyBuffer: Buffer}>}
+ */
+async function preprocessForOCR(input, options = {}) {
+  const region = await detectMRZRegion(input, options);
+  if (!region) {
+    throw new Error('Could not detect MRZ region in image');
+  }
+
+  const ocrReadyBuffer = await optimizeForOCR(region.imageBuffer, options);
+
+  return {
+    region,
+    ocrReadyBuffer,
+  };
+}
+
+module.exports = {
+  preprocessImage,
+  detectMRZRegion,
+  optimizeForOCR,
+  preprocessForOCR,
+};

package/src/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Type definitions for mrz-genius
+ */
+
+export interface MRZFieldDetail {
+  raw: string;
+  checkDigit: number | null;
+  valid: boolean;
+}
+
+export interface MRZDetails {
+  fields: {
+    documentNumber: MRZFieldDetail;
+    birthDate: MRZFieldDetail;
+    expiryDate: MRZFieldDetail;
+    optionalData1: MRZFieldDetail;
+  };
+  finalCheckDigitValid: boolean;
+}
+
+export interface MRZResult {
+  valid: boolean;
+  format: 'TD1' | 'TD2' | 'TD3' | 'MRVA' | 'MRVB';
+  documentType: 'PASSPORT' | 'VISA' | 'ID_CARD' | string;
+  issuingCountry: string | null;
+  surname: string | null;
+  givenNames: string | null;
+  documentNumber: string | null;
+  nationality: string | null;
+  birthDate: Date | null;
+  birthDateFormatted: string | null;
+  sex: 'MALE' | 'FEMALE' | 'NON_BINARY' | 'UNSPECIFIED';
+  expiryDate: Date | null;
+  expiryDateFormatted: string | null;
+  optionalData1: string | null;
+  optionalData2: string | null;
+  mrzKey: string;
+  rawMRZ: string;
+  details: MRZDetails;
+}
+
+export interface OCRResult {
+  lines: string[];
+  rawText: string;
+  confidence: number;
+  method: string;
+}
+
+export interface ProcessImageResult {
+  success: boolean;
+  ocr: OCRResult;
+  parsed: MRZResult | null;
+}
+
+export interface MRZRegion {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  imageBuffer: Buffer;
+  confidence: 'high' | 'low';
+}
+
+export interface FieldPosition {
+  line: number;
+  start: number;
+  end: number;
+  hasCheckDigit: boolean;
+  contentType: 'digits' | 'letters' | 'mixed' | 'sex';
+}
+
+export interface MRZFormatSpec {
+  lineLength: number;
+  linesCount: number;
+}
+
+export interface LLMConfig {
+  provider: 'chatgpt' | 'openai' | 'anthropic' | 'gemini' | 'litellm';
+  apiKey: string;
+  model?: string;
+  baseUrl?: string;
+}
+
+export interface ProcessImageOptions {
+  ocrCorrection?: boolean;
+  detectRegion?: boolean;
+  lang?: string;
+  llm?: LLMConfig;
+}
+
+export interface ParseOptions {
+  ocrCorrection?: boolean;
+}
+
+export interface DetectOptions {
+  bottomPercent?: number;
+  padding?: number;
+}
+
+export interface OCROptions {
+  lang?: string;
+  detectRegion?: boolean;
+  tessdataPath?: string;
+}
+
+// High-level API
+export function processImage(image: Buffer | string, options?: ProcessImageOptions): Promise<ProcessImageResult>;
+export function parseMRZ(mrzText: string | string[], options?: ParseOptions): MRZResult | null;
+
+// Detection
+export function detectMRZRegion(input: Buffer | string, options?: DetectOptions): Promise<MRZRegion | null>;
+export function optimizeForOCR(mrzImageBuffer: Buffer, options?: { scaleFactor?: number; threshold?: number }): Promise<Buffer>;
+export function preprocessForOCR(input: Buffer | string, options?: DetectOptions): Promise<{ region: MRZRegion; ocrReadyBuffer: Buffer }>;
+
+// OCR
+export function performOCR(input: Buffer | string, options?: OCROptions): Promise<OCRResult>;
+export function hasMRZ(input: Buffer | string): Promise<boolean>;
+export function postProcessOCR(text: string): string[];
+export function extractMRZFromFullText(fullText: string): string[] | null;
+
+// Parser
+export function parse(input: string | string[], options?: ParseOptions): MRZResult | null;
+export function detectFormat(lines: string[]): string | null;
+export function parseName(rawName: string): { surname: string | null; givenNames: string | null };
+export function parseDate(raw: string, type: 'birth' | 'expiry'): Date | null;
+export function formatDate(date: Date): string;
+export function parseSex(rawSex: string): string;
+export function parseDocumentType(rawType: string): string;
+
+// Validation
+export function calculateCheckDigit(value: string): number | null;
+export function isCheckDigitValid(rawValue: string, checkDigit: number): boolean;
+export function isCompositeValid(fields: Array<{ rawValue: string; checkDigit: number | null }>, finalCheckDigit: number): boolean;
+
+// OCR Correction
+export function correctOCR(str: string, contentType: 'digits' | 'letters' | 'sex' | 'mixed'): string;
+export function findMatchingStrings(strings: string[], isCorrectCombination: (combo: string[]) => boolean): string[] | null;
+
+// Constants
+export const MRZ_FORMATS: Record<string, MRZFormatSpec>;
+export function getFieldPositions(format: string): Record<string, FieldPosition> | null;