omnimrz 0.1.1

Fast and robust MRZ extraction, parsing, and validation using PaddleOCR

OmniMRZ

OmniMRZ is a production-grade MRZ extraction and validation engine designed for KYC, identity verification, and document intelligence pipelines.

Unlike simple MRZ readers, OmniMRZ evaluates whether an MRZ is structurally correct, cryptographically valid, and logically plausible.

⭐ Show Your Support If OmniMRZ helped you or saved development time: 👉 Please consider starring the repository It helps visibility and motivates continued development

Features

Installation

Contributing

Features

At a glance

• MRZ detection and extraction from images
• Supports TD3 (passport) format
• Checksum validation (ICAO 9303)
• Logical and structural validation
• Clean Python API

Detailed features

🔍 MRZ Extraction

• PaddleOCR-based MRZ text extraction (robust on mobile & noisy images)
• Intelligent MRZ line clustering & reconstruction
• Automatic MRZ type detection (TD1 / TD2 / TD3)
• OCR noise filtering & MRZ-safe character normalization
• Works even with partially corrupted or misaligned MRZs

🧱 Structural Validation (ICAO 9303)

• Exact line-length enforcement
• Strict MRZ format verification
• Field-level structural checks
• Early-exit gating for invalid layouts

🔢 Checksum Validation

• Fully ICAO-9303 compliant checksum algorithm
• Field-level validation:
• Document number
• Date of birth
• Expiry date
• Composite checksum
• OCR-error tolerant digit correction (O→0, S→5, B→8, etc.)
• Detailed checksum failure diagnostics

🧠 Logical & Semantic Validation

• Expired document detection
• Future date-of-birth detection
• Implausible age detection
• DOB ≥ expiry detection
• Gender value validation (M, F, X, <)
• Cross-field consistency signals (issuer vs nationality)

📤 Output

• Clean MRZ text
• Structured JSON
• Deterministic pass / fail / warning signals
• Human-readable error messages

Installation

pip install omnimrz

Note: PaddleOCR requires additional system dependencies. Please ensure PaddlePaddle installs correctly on your platform.

pip install paddleocr
pip install paddle paddle

or if that fails then run

python -m pip install paddlepaddle==3.0.0 -i https://www.paddlepaddle.org.cn/packages/stable/cpu/

Quick Usage

from omnimrz import OmniMRZ

omni = OmniMRZ()
result = omni.process("ukpassport.jpg")

print(result)

Output Example

{
  "extraction": {
    "status": "SUCCESS(extraction of mrz)",
    "line1": "P<GBRPUDARSAN<<HENERT<<<<<<<<<<<<<<<<<<<<<<<",
    "line2": "7077979792GBR9505209M1704224<<<<<<<<<<<<<<00"
  },
  "structural_validation": {
    "status": "PASS",
    "mrz_type": "TD3",
    "errors": []
  },
  "checksum_validation": {
    "status": "PASS",
    "errors": []
  },
  "parsed_data": {
    "status": "PARSED",
    "data": {
      "document_type": "P",
      "issuing_country": "GBR",
      "surname": "PUDARSAN",
      "given_names": "HENERT",
      "document_number": "707797979",
      "nationality": "GBR",
      "date_of_birth": "1995-05-20",
      "gender": "M",
      "expiry_date": "2017-04-22",
      "personal_number": ""
    }
  },
  "logical_validation": {
    "status": "FAIL",
    "errors": [
      "DOCUMENT_EXPIRED"
    ]
  }
}

Contributing

Contributions are welcome!🤝

1. Fork the repository
2. Create your feature branch

git checkout -b feature/amazing-feature

3. Commit your changes
4. Push to your branch
5. Open a Pull Request

misc