PassportEye Documentation

Install the package via pip. Note that PassportEye depends on numpy, scipy, matplotlib, and scikit-image. If installation fails due to missing system libraries, consider using a Python distribution like Anaconda or installing dependencies via OS-specific binary packages.

Prerequisites:

• Python 3.6 or higher.
• Tesseract OCR must be installed and available in your system PATH (the tesseract command must work in your terminal).
• Legacy Tesseract Models: For better MRZ detection, it is recommended to use Tesseract's "legacy" models. If your installation doesn't include them, download the eng.traineddata file from the official Tesseract repository and replace your existing one.

$ pip install PassportEye

To use PassportEye within a Python script, use the read_mrz function. It accepts either a file path or a byte stream containing image data.

Return Value:

• Returns an MRZ object containing extracted fields and metadata.
• Returns None if no Region of Interest (ROI) was detected.
• Use the .to_dict() method on the returned object to convert it to a dictionary.

Accessing the ROI: If you pass save_roi=True, the ROI (a grayscale numpy ndarray) is stored in the aux dictionary under the key 'roi'.

from passporteye import read_mrz

# Basic extraction
mrz = read_mrz(image_file)
if mrz:
    data = mrz.to_dict()

# Extraction with ROI access
mrz = read_mrz(image_file, save_roi=True)
if mrz:
    roi_image = mrz.aux['roi']  # This is a numpy ndarray

To achieve the same performance boost as the --legacy CLI flag within your Python code, pass the --oem 0 argument to Tesseract via the extra_cmdline_params parameter in read_mrz.

from passporteye import read_mrz

# Use legacy Tesseract engine (OEM 0)
mrz = read_mrz(image_file, extra_cmdline_params='--oem 0')

For advanced usage or debugging, use the MRZPipeline class. This provides access to the intermediate steps of the recognition process via a data dictionary.

from passporteye.mrz.image import MRZPipeline

# Initialize pipeline
p = MRZPipeline(file, extra_cmdline_params='--oem 0')

# Access the result
mrz = p.result

# Access intermediate data (e.g., binarized image and detected boxes)
# p['img_binary'] contains the binarized image
# p['boxes'] contains the detected ROI boxes

The mrz command-line tool allows you to process images or PDFs and extract MRZ information directly from the terminal.

Available Flags:

• --json: Outputs the extracted information in JSON format.
• --save-roi <roi.png>: Extracts the detected Machine Readable Zone (Region of Interest) and saves it as a PNG file.
• --legacy: Enables the legacy Tesseract recognizer (requires legacy *.traineddata models to be installed in your Tesseract tessdata directory).

Note on PDFs: The tool attempts to extract the first DCT-encoded image from a PDF and applies recognition to it. This works for most scanner-produced one-page PDFs.

# Basic usage (tabular output)
$ mrz <filename>

# JSON output
$ mrz --json <filename>

# Save the detected MRZ region to a file
$ mrz --save-roi <roi.png> <filename>

# Use legacy Tesseract models
$ mrz --legacy <filename>