@ -1,10 +1,10 @@
# Eynollah
# Eynollah
> Document Layout Analysis (segmentation) using pre-trained models and h euristics
> Document Layout Analysis with Deep Learning and H euristics
[](https://pypi.org/project/eynollah/)
[](https://pypi.org/project/eynollah/)
[](https://circleci.com/gh/qurator-spk/eynollah)
[](https://github.com/qurator-spk/eynollah/actions/workflows/test-eynollah.yml)
[](https://github.com/qurator-spk/eynollah/actions/workflows/test-eynollah.yml)
[](https://opensource.org/license/apache-2-0/)
[](https://opensource.org/license/apache-2-0/)
[](https://doi.org/10.1145/3604951.3605513)
@ -14,17 +14,18 @@
* Support for various image optimization operations:
* Support for various image optimization operations:
* cropping (border detection), binarization, deskewing, dewarping, scaling, enhancing, resizing
* cropping (border detection), binarization, deskewing, dewarping, scaling, enhancing, resizing
* Text line segmentation to bounding boxes or polygons (contours) including for curved lines and vertical text
* Text line segmentation to bounding boxes or polygons (contours) including for curved lines and vertical text
* Detection of reading order
* Detection of reading order (left-to-right or right-to-left)
* Output in [PAGE-XML ](https://github.com/PRImA-Research-Lab/PAGE-XML )
* Output in [PAGE-XML ](https://github.com/PRImA-Research-Lab/PAGE-XML )
* [OCR-D ](https://github.com/qurator-spk/eynollah#use-as-ocr-d-processor ) interface
* [OCR-D ](https://github.com/qurator-spk/eynollah#use-as-ocr-d-processor ) interface
:warning: Development is currently focused on achieving the best possible quality of results for a wide variety of historical documents and therefore processing can be very slow. We aim to improve this, but contributions are welcome.
## Installation
## Installation
Python versions `3.8-3.11` with Tensorflow versions >=`2.12` on Linux are currently supported. Unfortunately we can not currently support Windows or MacOS.
Python `3.8-3.11` with Tensorflow `2.12-2.15` on Linux are currently supported.
Windows users may be able to successfully run the tool through [WSL ](https://learn.microsoft.com/en-us/windows/wsl/ ).
For (limited) GPU support the CUDA toolkit needs to be installed.
For (limited) GPU support the CUDA toolkit needs to be installed.
You can either install via
You can either install from PyPI
```
```
pip install eynollah
pip install eynollah
@ -40,45 +41,48 @@ cd eynollah; pip install -e .
Alternatively, you can run `make install` or `make install-dev` for editable installation.
Alternatively, you can run `make install` or `make install-dev` for editable installation.
## Models
## Models
Pre-trained models can be downloaded from [qurator-data.de ](https://qurator-data.de/eynollah/ ).
Pre-trained models can be downloaded from [qurator-data.de ](https://qurator-data.de/eynollah/ ) or [huggingface ](https://huggingface.co/SBB?search_models=eynollah ).
## Train
🚧 **Work in progress**
In case you want to train your own model to use with Eynollah, have a look at [sbb_pixelwise_segmentation ](https://github.com/qurator-spk/sbb_pixelwise_segmentation ).
In case you want to train your own model, have a look at [` sbb_pixelwise_segmentation` ](https://github.com/qurator-spk/sbb_pixelwise_segmentation ).
## Usage
## Usage
The command-line interface can be called like this:
The command-line interface can be called like this:
```sh
```sh
eynollah \
eynollah \
-i < file > \
-i < single image file > | -di < directory containing image files > \
-o < output directory > \
-o < output directory > \
-m < path to directory containing model files > \
-m < containing model files > \
[OPTIONS]
[OPTIONS]
```
```
The following options can be used to further configure the processing:
The following options can be used to further configure the processing:
| option | description |
| option | description |
|----------|:-------------|
|-------------------|:-------------------------------------------------------------------------------|
| `-fl` | full layout analysis including all steps and segmentation classes |
| `-fl` | full layout analysis including all steps and segmentation classes |
| `-light` | lighter and faster but simpler method for main region detection and deskewing |
| `-light` | lighter and faster but simpler method for main region detection and deskewing |
| `-tab` | apply table detection |
| `-tab` | apply table detection |
| `-ae` | apply enhancement (the resulting image is saved to the output directory) |
| `-ae` | apply enhancement (the resulting image is saved to the output directory) |
| `-as` | apply scaling |
| `-as` | apply scaling |
| `-cl` | apply contour detection for curved text lines instead of bounding boxes |
| `-cl` | apply contour detection for curved text lines instead of bounding boxes |
| `-ib` | apply binarization (the resulting image is saved to the output directory) |
| `-ib` | apply binarization (the resulting image is saved to the output directory) |
| `-ep` | enable plotting (MUST always be used with `-sl` , `-sd` , `-sa` , `-si` or `-ae` ) |
| `-ep` | enable plotting (MUST always be used with `-sl` , `-sd` , `-sa` , `-si` or `-ae` ) |
| `-ho` | ignore headers for reading order dectection |
| `-ho` | ignore headers for reading order dectection |
| `-di <directory>` | process all images in a directory in batch mode |
| `-si <directory>` | save image regions detected to this directory |
| `-si <directory>` | save image regions detected to this directory |
| `-sd <directory>` | save deskewed image to this directory |
| `-sd <directory>` | save deskewed image to this directory |
| `-sl <directory>` | save layout prediction as plot to this directory |
| `-sl <directory>` | save layout prediction as plot to this directory |
| `-sp <directory>` | save cropped page image to this directory |
| `-sp <directory>` | save cropped page image to this directory |
| `-sa <directory>` | save all (plot, enhanced/binary image, layout) to this directory |
| `-sa <directory>` | save all (plot, enhanced/binary image, layout) to this directory |
If no option is set, the tool performs layout detection of main regions (background, text, images, separators and marginals).
If no option is set, the tool will perform layout detection of main regions (background, text, images, separators and marginals).
The best output quality is produced when RGB images are used as input rather than greyscale or binarized images.
The tool produces better quality output when RGB images are used as input than greyscale or binarized images.
#### Use as OCR-D processor
#### Use as OCR-D processor
🚧 **Work in progress**
Eynollah ships with a CLI interface to be used as [OCR-D ](https://ocr-d.de ) processor.
Eynollah ships with a CLI interface to be used as [OCR-D ](https://ocr-d.de ) processor.
@ -96,11 +100,14 @@ ocrd-eynollah-segment -I OCR-D-IMG-BIN -O SEG-LINE -P models
uses the original (RGB) image despite any binarization that may have occured in previous OCR-D processing steps
uses the original (RGB) image despite any binarization that may have occured in previous OCR-D processing steps
#### Additional documentation
Please check the [wiki ](https://github.com/qurator-spk/eynollah/wiki ).
## How to cite
## How to cite
If you find this tool useful in your work, please consider citing our paper:
If you find this tool useful in your work, please consider citing our paper:
```bibtex
```bibtex
@inproceedings {rezanezhad2023eynollah ,@inproceedings {hip23 rezanezhad,
title = {Document Layout Analysis with Deep Learning and Heuristics},
title = {Document Layout Analysis with Deep Learning and Heuristics},
author = {Rezanezhad, Vahid and Baierer, Konstantin and Gerber, Mike and Labusch, Kai and Neudecker, Clemens},
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,
booktitle = {Proceedings of the 7th International Workshop on Historical Document Imaging and Processing {HIP} 2023,
cneud
4 months ago