eynollah/README.md

167 lines
8.8 KiB
Markdown
Raw Normal View History

# Eynollah
2024-04-03 19:58:24 +02:00
> Document Layout Analysis with Deep Learning and Heuristics
2023-04-05 10:40:18 +02:00
2023-03-31 03:18:18 +02:00
[![PyPI Version](https://img.shields.io/pypi/v/eynollah)](https://pypi.org/project/eynollah/)
2023-04-14 02:11:51 +02:00
[![GH Actions Test](https://github.com/qurator-spk/eynollah/actions/workflows/test-eynollah.yml/badge.svg)](https://github.com/qurator-spk/eynollah/actions/workflows/test-eynollah.yml)
[![GH Actions Deploy](https://github.com/qurator-spk/eynollah/actions/workflows/build-docker.yml/badge.svg)](https://github.com/qurator-spk/eynollah/actions/workflows/build-docker.yml)
2023-03-31 03:19:44 +02:00
[![License: ASL](https://img.shields.io/github/license/qurator-spk/eynollah)](https://opensource.org/license/apache-2-0/)
2024-04-03 19:58:24 +02:00
[![DOI](https://img.shields.io/badge/DOI-10.1145%2F3604951.3605513-red)](https://doi.org/10.1145/3604951.3605513)
2020-11-20 12:49:27 +01:00
![](https://user-images.githubusercontent.com/952378/102350683-8a74db80-3fa5-11eb-8c7e-f743f7d6eae2.jpg)
2023-04-14 02:48:42 +02:00
## Features
* Support for up to 10 segmentation classes:
2023-05-13 15:36:24 +02:00
* background, [page border](https://ocr-d.de/en/gt-guidelines/trans/lyRand.html), [text region](https://ocr-d.de/en/gt-guidelines/trans/lytextregion.html#textregionen__textregion_), [text line](https://ocr-d.de/en/gt-guidelines/pagexml/pagecontent_xsd_Complex_Type_pc_TextLineType.html), [header](https://ocr-d.de/en/gt-guidelines/trans/lyUeberschrift.html), [image](https://ocr-d.de/en/gt-guidelines/trans/lyBildbereiche.html), [separator](https://ocr-d.de/en/gt-guidelines/trans/lySeparatoren.html), [marginalia](https://ocr-d.de/en/gt-guidelines/trans/lyMarginalie.html), [initial](https://ocr-d.de/en/gt-guidelines/trans/lyInitiale.html), [table](https://ocr-d.de/en/gt-guidelines/trans/lyTabellen.html)
2023-04-14 02:48:42 +02:00
* Support for various image optimization operations:
* cropping (border detection), binarization, deskewing, dewarping, scaling, enhancing, resizing
2023-04-14 03:13:07 +02:00
* Text line segmentation to bounding boxes or polygons (contours) including for curved lines and vertical text
2024-04-03 19:58:24 +02:00
* Detection of reading order (left-to-right or right-to-left)
2023-04-14 03:13:07 +02:00
* Output in [PAGE-XML](https://github.com/PRImA-Research-Lab/PAGE-XML)
2023-04-14 03:25:01 +02:00
* [OCR-D](https://github.com/qurator-spk/eynollah#use-as-ocr-d-processor) interface
2023-04-14 02:48:42 +02:00
2025-05-14 21:56:03 +02:00
: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.
2024-04-03 19:58:24 +02:00
2022-04-04 21:13:21 -04:00
## Installation
2024-10-16 14:21:48 +02:00
Python `3.8-3.11` with Tensorflow `<2.13` on Linux are currently supported.
2022-04-04 21:13:21 -04:00
2023-09-26 18:54:14 +02:00
For (limited) GPU support the CUDA toolkit needs to be installed.
2022-04-04 21:13:21 -04:00
2024-04-03 19:58:24 +02:00
You can either install from PyPI
2022-04-04 21:13:21 -04:00
2023-04-14 02:48:42 +02:00
```
pip install eynollah
```
2022-04-04 21:13:21 -04:00
2023-04-14 02:48:42 +02:00
or clone the repository, enter it and install (editable) with
2022-04-04 21:13:21 -04:00
2023-04-14 02:48:42 +02:00
```
git clone git@github.com:qurator-spk/eynollah.git
cd eynollah; pip install -e .
```
2022-09-13 16:40:44 +02:00
2023-04-14 02:48:42 +02:00
Alternatively, you can run `make install` or `make install-dev` for editable installation.
2022-09-13 16:40:44 +02:00
2023-05-13 12:47:06 +02:00
## Models
2025-05-14 21:56:03 +02:00
Pretrained models can be downloaded from [qurator-data.de](https://qurator-data.de/eynollah/) or [huggingface](https://huggingface.co/SBB?search_models=eynollah).
2023-05-13 12:47:06 +02:00
2025-03-27 22:41:10 +01:00
For documentation on methods and models, have a look at [`models.md`](https://github.com/qurator-spk/eynollah/tree/main/docs/models.md).
2024-04-03 19:58:24 +02:00
## Train
2025-03-27 22:41:10 +01:00
In case you want to train your own model with Eynollah, have a look at [`train.md`](https://github.com/qurator-spk/eynollah/tree/main/docs/train.md).
2023-05-13 12:47:06 +02:00
2022-04-04 21:13:21 -04:00
## Usage
2025-05-14 21:56:03 +02:00
Eynollah supports four use cases: layout analysis (segmentation), binarization, text recognition (OCR),
and (trainable) reading order detection.
2025-05-14 21:56:03 +02:00
### Layout Analysis
The layout analysis module is responsible for detecting layouts, identifying text lines, and determining reading order
using both heuristic methods or a machine-based reading order detection model.
2025-05-14 21:56:03 +02:00
Note that there are currently two supported ways for reading order detection: either as part of layout analysis based
on image input, or, currently under development, for given layout analysis results based on PAGE-XML data as input.
2025-05-14 21:56:03 +02:00
The command-line interface for layout analysis can be called like this:
2022-04-04 21:13:21 -04:00
```sh
eynollah layout \
2024-04-03 19:58:24 +02:00
-i <single image file> | -di <directory containing image files> \
2023-04-14 02:48:42 +02:00
-o <output directory> \
2024-04-03 19:58:24 +02:00
-m <directory containing model files> \
2023-04-14 02:48:42 +02:00
[OPTIONS]
2022-09-13 17:19:19 +02:00
```
2022-09-13 21:48:21 +02:00
The following options can be used to further configure the processing:
2022-04-04 21:13:21 -04:00
2024-07-31 22:53:36 +02:00
| option | description |
|-------------------|:-------------------------------------------------------------------------------|
| `-fl` | full layout analysis including all steps and segmentation classes |
| `-light` | lighter and faster but simpler method for main region detection and deskewing |
| `-tll` | this indicates the light textline and should be passed with light version |
2024-07-31 22:53:36 +02:00
| `-tab` | apply table detection |
| `-ae` | apply enhancement (the resulting image is saved to the output directory) |
| `-as` | apply scaling |
| `-cl` | apply contour detection for curved text lines instead of bounding boxes |
| `-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`) |
2024-09-19 14:41:17 +02:00
| `-eoi` | extract only images to output directory (other processing will not be done) |
2024-07-31 22:53:36 +02:00
| `-ho` | ignore headers for reading order dectection |
| `-si <directory>` | save image regions detected 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 |
2022-04-04 21:13:21 -04:00
2025-05-14 21:56:03 +02:00
If no option is set, the tool performs layout detection of main regions (background, text, images, separators
and marginals).
2024-08-01 00:30:25 +02:00
The best output quality is produced when RGB images are used as input rather than greyscale or binarized images.
2023-05-13 02:39:18 +02:00
### Binarization
2025-05-14 21:56:03 +02:00
The binarization module performs document image binarization using pretrained pixelwise segmentation models.
The command-line interface for binarization of single image can be called like this:
```sh
eynollah binarization \
2025-05-14 21:56:03 +02:00
-m <directory containing model files> \
<single image file> \
<output image>
```
and for flowing from a directory like this:
```sh
eynollah binarization \
-m <path to directory containing model files> \
-di <directory containing image files> \
-do <output directory>
```
### OCR
Under development
### Machine-based-reading-order
Under development
2022-04-04 21:13:21 -04:00
#### Use as OCR-D processor
Eynollah ships with a CLI interface to be used as [OCR-D](https://ocr-d.de) [processor](https://ocr-d.de/en/spec/cli),
formally described in [`ocrd-tool.json`](https://github.com/qurator-spk/eynollah/tree/main/src/eynollah/ocrd-tool.json).
2020-11-20 12:49:27 +01:00
2023-04-14 13:24:13 +02:00
In this case, the source image file group with (preferably) RGB images should be used as input like this:
2020-11-20 12:49:27 +01:00
2025-04-01 23:26:38 +02:00
ocrd-eynollah-segment -I OCR-D-IMG -O OCR-D-SEG -P models 2022-04-05
2020-11-20 12:49:27 +01:00
2025-04-01 23:26:38 +02:00
If the input file group is PAGE-XML (from a previous OCR-D workflow step), Eynollah behaves as follows:
- existing regions are kept and ignored (i.e. in effect they might overlap segments from Eynollah results)
- existing annotation (and respective `AlternativeImage`s) are partially _ignored_:
- previous page frame detection (`cropped` images)
- previous derotation (`deskewed` images)
- previous thresholding (`binarized` images)
- if the page-level image nevertheless deviates from the original (`@imageFilename`)
(because some other preprocessing step was in effect like `denoised`), then
the output PAGE-XML will be based on that as new top-level (`@imageFilename`)
ocrd-eynollah-segment -I OCR-D-XYZ -O OCR-D-SEG -P models 2022-04-05
Still, in general, it makes more sense to add other workflow steps **after** Eynollah.
2023-06-23 13:54:04 +02:00
2024-04-03 19:58:24 +02:00
#### Additional documentation
Please check the [wiki](https://github.com/qurator-spk/eynollah/wiki).
2023-06-23 13:54:04 +02:00
## How to cite
If you find this tool useful in your work, please consider citing our paper:
2023-06-23 14:04:24 +02:00
```bibtex
2024-04-03 19:58:24 +02:00
@inproceedings{hip23rezanezhad,
2023-06-23 14:04:24 +02:00
title = {Document Layout Analysis with Deep Learning and Heuristics},
author = {Rezanezhad, Vahid and Baierer, Konstantin and Gerber, Mike and Labusch, Kai and Neudecker, Clemens},
2023-06-23 13:54:04 +02:00
booktitle = {Proceedings of the 7th International Workshop on Historical Document Imaging and Processing {HIP} 2023,
2023-08-09 18:39:49 +02:00
San José, CA, USA, August 25-26, 2023},
publisher = {Association for Computing Machinery},
address = {New York, NY, USA},
2023-06-23 14:04:24 +02:00
year = {2023},
2023-08-09 18:39:49 +02:00
pages = {73--78},
2023-06-23 14:04:24 +02:00
url = {https://doi.org/10.1145/3604951.3605513}
2023-06-23 13:54:04 +02:00
}
```