Skip to main content

Eynollah

Document Layout Analysis, Binarization and OCR with Deep Learning Models and Heuristics

Python Versions PyPI Version GH Actions Test GH Actions Deploy License: ASL DOI

Features

⚠️ Development is focused on achieving the optimal quality for a wide variety of historical documents using a combination of multiple deep learning models and heuristics; therefore processing can be slow.

Installation

Python 3.9-3.11 with ONNX Runtime on Linux are currently supported.

For GPU support, Nvidia drivers supporting CUDA 12 must be installed. The runtime dependencies will pull in ONNX, TensorRT and CUDA runtime libraries (including cuDNN) from PyPI.

You can either install from PyPI

pip install eynollah

or clone the repository, enter it and install (editable) with

git clone git@github.com:qurator-spk/eynollah.git
cd eynollah; pip install -e .

To also install the dependencies for the OCR engines:

pip install "eynollah[OCR]"

⚠️ Requirements for OCR are more involved, as they need Tensorflow (with tf-keras) and/or Torch (with transformers), which may also have conflicting CUDA dependencies. An ONNX conversion for these models may be achieved soon.

Models

Pretrained models can be downloaded from Zenodo. For model documentation and model cards, see models.md.

Two model variants are provided:

  • For faster runtime inference, download the ONNX model variants distributed as models_inference_...zip
  • For finetuning and training, download the original (Tensorflow / Torch) models distributed as models_training...zip

To train your own model with Eynollah, see train.md.

Usage

Eynollah supports five use cases:

  1. layout analysis (segmentation),
  2. binarization,
  3. image enhancement,
  4. text recognition (OCR), and
  5. reading order detection.

The generic options shared by all subcommands are:

  -m <directory containing model files>
  -mv <model category> <model variant> <model path>
  -D <device specifier>
  -l <log level>

Layout Analysis

Detect layout elements and their reading order.

The command-line interface for layout analysis can be called like this:

eynollah [GENERIC_OPTIONS] layout \
  -i <single image file> | -di <directory containing image files> \
  -o <output directory> \
     [OPTIONS]

The following options can be used to further configure the processing:

option description
-fl apply full layout analysis including all steps and classes (recommended)
-tab apply table detection
-ae apply image enhancement (the resulting image is saved to the output directory)
-as apply automatic scaling
-cl apply contour detection for curved text lines, deskewing all regions independently
-ib apply binarization (the resulting bitonal image is saved to the output directory)
-ep enable plotting (MUST always be used with -sl, -sd, -sa, -si or -ae)
-ho ignore headers for reading order detection
-si <directory> save detected image regions to this directory
-sd <directory> save deskewed image to this directory
-sl <directory> save layout prediction as plot to this directory
-sp <directory> save cropped page image to this directory
-sa <directory> save all (plot, enhanced/binary image, layout) to this directory
-thart confidence threshold of artificial boundary class during textline detection
-tharl confidence threshold of artificial boundary class during region detection
-ncu set upper limit of columns in document image
-ncl set lower limit of columns in document image
-slro skip layout detection and reading order
-romb apply machine learning based reading order detection
-ipe ignore page extraction
-j number of CPU jobs to run parallel (useful with -di)
-H when to halt when some jobs fail

Binarization

Perform document image binarization.

The command-line interface for binarization can be called like this:

eynollah [GENERIC_OPTIONS] binarization \
  -i <single image file> | -di <directory containing image files> \
  -o <output directory> \
  [OPTIONS]

Image Enhancement

Enlarge and enhance images. Useful when the scan quality is low.

The command-line interface for image enhancement can be called like this:

eynollah [GENERIC_OPTIONS] enhancement \
  -i <single image file> | -di <directory containing image files> \
  -o <output directory> \
  [OPTIONS]

The following options can be used to further configure the processing:

option description
-sos save the enhanced image in original image size
-ncu upper limit of columns in document image
-ncl lower limit of columns in document image

OCR

Perform text recognition using either a CNN-RNN model (default) or a TrOCR model. Needs a PAGE-XML input file containing textline segmentation information.

The command-line interface for OCR can be called like this:

eynollah [GENERIC_OPTIONS] ocr \
  -i <single image file> | -di <directory containing image files> \
  -xml <page-xml input file> | -dx <directory containing page-xml files> \
  -o <output directory> \

The following options can be used to further configure the processing:

option description
-trocr use TrOCR model instead of CNN-RNN model
-dib directory of binarized images (file type must be '.png'), prediction with both RGB and bin
-doit directory for output images rendered with the predicted text
-nmtc cropped textline images will not be masked with textline contour
-bs OCR inference batch size. Default batch size is 2 for TrOCR and 8 for CNN-RNN models
-min_conf minimum OCR confidence value. OCR with textline confidence lower than this will be ignored

Reading Order Detection

Detect reading order using a machine learning based model. Needs a PAGE-XML input file containing textline segmentation information.

The command-line interface for machine learning based reading order detection can be called like this:

eynollah [GENERIC_OPTIONS] machine-based-reading-order \
  -i <single image file> | -di <directory containing image files> \
  -xml <xml file name> | -dx <directory containing xml files> \
  -o <output directory> 

Documentation

Additional documentation:

  • For using Eynollah with Docker, see docker.md.
  • For using Eynollah with OCR-D, see ocrd.md.
  • For advanced use, see use.md.
  • For model documentation and model cards, see models.md.
  • For model training or fine-tuning, see train.md.
  • For a runnable example to use with e.g. Google Colab, see eynollah_layout.ipynb.

How to cite

@inproceedings{hip23rezanezhad,
  title     = {Document Layout Analysis with Deep Learning and Heuristics},
  author    = {Rezanezhad, Vahid and Baierer, Konstantin and Gerber, Mike and Labusch, Kai and Neudecker, Clemens},
  booktitle = {Proceedings of the 7th International Workshop on Historical Document Imaging and Processing {HIP} 2023,
               San José, CA, USA, August 25-26, 2023},
  publisher = {Association for Computing Machinery},
  address   = {New York, NY, USA},
  year      = {2023},
  pages     = {73--78},
  url       = {https://doi.org/10.1145/3604951.3605513}
}

Metadata

Release files for eynollah 0.10.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for eynollah 0.10.1
File Size Uploaded Provenance Actions
eynollah-0.10.1.tar.gz 388.1 kB With provenance Details for eynollah-0.10.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for eynollah 0.10.1
File Interpreter ABI Platform Actions
eynollah-0.10.1-py3-none-any.whl Python 3 none any Details for eynollah-0.10.1-py3-none-any.whl

Total release size: 788.9 kB

Release files / eynollah-0.10.1.tar.gz

Download URL eynollah-0.10.1.tar.gz
Size 388.1 kB
Tags Source
SHA-256 checksum
How to use checksums
e463db3ebbe1148e62cc3a524bbfc0f250092ab6462dcfee1d483e0b2488372e
BLAKE2b-256 checksum
How to use checksums
06ca7549c81819e9a5ed12588e6d6bbb78b78ec5ddde7c1ee3327d6e48217aa1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / eynollah-0.10.1-py3-none-any.whl

Download URL eynollah-0.10.1-py3-none-any.whl
Size 400.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a947c892ebcaef1c2df0baa9045a991c2c09cc2ed14c0482819d9149d8fda573
BLAKE2b-256 checksum
How to use checksums
3cf488199f8c9325774661ff8685f2ac624540903c31571c2b2828b73b081278
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for eynollah 0.10.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for eynollah-0.10.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page