qurator-spk/eynollah

Eynollah – Deep‑learning based document layout analysis, binarization & OCR

What it is

• A Python library (and CLI tool) that combines deep‑learning models and heuristics to process scanned documents. It can segment page layouts, binarize images, enhance low‑quality scans, run OCR, and determine reading order, outputting results in the standard PAGE‑XML format.

Why it matters

• Handles historic and heterogeneous documents where classic OCR pipelines struggle. By offering both pixel‑wise segmentation models (10 layout classes) and modern OCR models (CNN‑RNN or TrOCR), it aims for high‑quality transcription without requiring users to stitch together many separate tools.

Key capabilities

Capability	Details
Layout analysis	Pixel‑wise segmentation for background, page border, text region, text line, header, image, separator, marginalia, initial, table. Returns region polygons or bounding boxes and can infer reading order (heuristic or trainable).
Binarization	Deep‑learning (CNN or hybrid CNN‑Transformer) models produce clean binary images, useful for downstream OCR.
Image enhancement	Upscaling and quality‑boosting of low‑resolution scans.
OCR	Text recognition via a CNN‑RNN model or the Transformer‑based TrOCR model; works on PAGE‑XML inputs and can output rendered images with overlaid text.
Reading order detection	Separate module or integrated step; supports left‑to‑right and right‑to‑left scripts.
Integration	Provides an OCR‑D processor interface, allowing it to be dropped into OCR‑D workflows.

How to get it

• Install from PyPI: pip install eynollah (Python 3.8‑3.11, Linux, ONNX Runtime).
• For full OCR support (TensorFlow + PyTorch) use the extra: pip install "eynollah[OCR]".
• Docker image available: ghcr.io/qurator-spk/eynollah:latest.
• GPU acceleration requires CUDA 12 drivers; the package pulls ONNX, TensorRT and cuDNN from PyPI.

Running the tool (CLI examples)

# Layout analysis
eynollah layout -i page.tif -o out_dir -fl -ae -ep

# Binarization
eynollah binarization -i page.tif -o out_dir

# Image enhancement
eynollah enhancement -i page.tif -o out_dir -sos

# OCR (needs PAGE‑XML)
eynollah ocr -i page.tif -dx xml_dir -o out_dir -trocr

# Machine‑based reading order
eynollah machine-based-reading-order -i page.tif -xml page.xml -o out_dir

Common generic options (-m, -mv, -D, -l) let you point to model files, choose device (CPU/GPU), and set logging.

Models

• Pre‑trained weights are hosted on Zenodo and Hugging Face.
• Inference‑optimized ONNX models (models_inference_…zip) for fast CPU/GPU use.
• Full TensorFlow/PyTorch checkpoints (models_training…zip) for fine‑tuning (install the [training] extra).

Training your own models

• Documentation in docs/train.md and scripts under the train/ folder guide you through data preparation, training, and evaluation.

License & citation

• Apache‑2.0 license.
• If you use the software in research, cite the HIP 2023 paper (DOI 10.1145/3604951.3605513).

Who might use it

• Digital humanities scholars digitizing historical books, newspapers, or manuscripts.
• Libraries and archives needing a turnkey pipeline for layout‑aware OCR.
• Developers building OCR‑D workflows who want a drop‑in processor for complex page structures.