ocrd-tesserocr 0.11.0

wrap Tesseract preprocessing, segmentation and recognition

ocrd_tesserocr

Crop, deskew, segment into regions / tables / lines / words, or recognize with tesserocr

Introduction

This package offers OCR-D compliant workspace processors for (much of) the functionality of Tesseract via its Python API wrapper tesserocr. (Each processor is a parameterizable step in a configurable workflow of the OCR-D functional model. There are usually various alternative processor implementations for each step. Data is represented with METS and PAGE.)

It includes image preprocessing (cropping, binarization, deskewing), layout analysis (region, table, line, word segmentation), script identification, font style recognition and text recognition.

Most processors can operate on different levels of the PAGE hierarchy, depending on the workflow configuration. In PAGE, image results are referenced (read and written) via AlternativeImage, text results via TextEquiv, font attributes via TextStyle, script via @primaryScript, deskewing via @orientation, cropping via Border and segmentation via Region / TextLine / Word elements with Coords/@points.

Installation

Required ubuntu packages:

• Tesseract headers (libtesseract-dev)
• Some Tesseract language models (tesseract-ocr-{eng,deu,frk,...} or script models (tesseract-ocr-script-{latn,frak,...}); or better yet custom trained models
• Leptonica headers (libleptonica-dev)

From PyPI

This is the best option if you want to use the stable, released version.

---

NOTE

ocrd_tesserocr requires Tesseract >= 4.1.0. The Tesseract packages bundled with Ubuntu < 19.10 are too old. If you are on Ubuntu 18.04 LTS, please use Alexander Pozdnyakov's PPA repository, which has up-to-date builds of Tesseract and its dependencies:

sudo add-apt-repository ppa:alex-p/tesseract-ocr
sudo apt-get update

---

sudo apt-get install git python3 python3-pip libtesseract-dev libleptonica-dev tesseract-ocr-eng tesseract-ocr wget
pip install ocrd_tesserocr

With docker

This is the best option if you want to run the software in a container.

You need to have Docker

docker pull ocrd/tesserocr

To run with docker:

docker run -v path/to/workspaces:/data ocrd/tesserocr ocrd-tesserocrd-crop ...

From git

This is the best option if you want to change the source code or install the latest, unpublished changes.

We strongly recommend to use venv.

git clone https://github.com/OCR-D/ocrd_tesserocr
cd ocrd_tesserocr
sudo make deps-ubuntu # or manually with apt-get
make deps        # or pip install -r requirements
make install     # or pip install .

Usage

For details, see docstrings in the individual processors and ocrd-tool.json descriptions, or simply --help.

Available OCR-D processors are:

• ocrd-tesserocr-crop (simplistic)
  • sets Border of pages and adds AlternativeImage files to the output fileGrp
• ocrd-tesserocr-deskew (for skew and orientation; mind operation_level)
  • sets @orientation of regions or pages and adds AlternativeImage files to the output fileGrp
• ocrd-tesserocr-binarize (Otsu – not recommended)
  • adds AlternativeImage files to the output fileGrp
• ocrd-tesserocr-recognize (optionally including segmentation; mind segmentation_level and textequiv_level)
  • adds TextRegions, TableRegions, ImageRegions, MathsRegions, SeparatorRegions, NoiseRegions and ReadingOrder to Page and sets their @orientation (optionally)
  • adds TextRegions to TableRegions and sets their @orientation (optionally)
  • adds TextLines to TextRegions (optionally)
  • adds Words to TextLines (optionally)
  • adds Glyphs to Words (optionally)
  • adds TextEquiv
• ocrd-tesserocr-segment (all-in-one segmentation – recommended; delegates to recognize)
  • adds TextRegions, TableRegions, ImageRegions, MathsRegions, SeparatorRegions, NoiseRegions and ReadingOrder to Page and sets their @orientation
  • adds TextRegions to TableRegions and sets their @orientation
  • adds TextLines to TextRegions
  • adds Words to TextLines
  • adds Glyphs to Words
• ocrd-tesserocr-segment-region (only regions – with overlapping bboxes; delegates to recognize)
  • adds TextRegions, TableRegions, ImageRegions, MathsRegions, SeparatorRegions, NoiseRegions and ReadingOrder to Page and sets their @orientation
• ocrd-tesserocr-segment-table (only table cells; delegates to recognize)
  • adds TextRegions to TableRegions
• ocrd-tesserocr-segment-line (only lines – from overlapping regions; delegates to recognize)
  • adds TextLines to TextRegions
• ocrd-tesserocr-segment-word (only words; delegates to recognize)
  • adds Words to TextLines
• ocrd-tesserocr-fontshape (only text style – via Tesseract 3 models)
  • adds TextStyle to Words

The text region @types detected are (from Tesseract's PolyBlockType):

• paragraph: normal block (aligned with others in the column)
• floating: unaligned block (is in a cross-column pull-out region)
• heading: block that spans more than one column
• caption: block for text that belongs to an image

If you are unhappy with these choices, consider post-processing with a dedicated custom processor in Python, or by modifying the PAGE files directly (e.g. xmlstarlet ed --inplace -u '//pc:TextRegion/@type[.="floating"]' -v paragraph filegrp/*.xml).

All segmentation is currently done as bounding boxes only by default, i.e. without precise polygonal outlines. For dense page layouts this means that neighbouring regions and neighbouring text lines may overlap a lot. If this is a problem for your workflow, try post-processing like so:

• after line segmentation: use ocrd-cis-ocropy-resegment for polygonalization, or ocrd-cis-ocropy-clip on the line level
• after region segmentation: use ocrd-segment-repair with plausibilize (and sanitize after line segmentation)

It also means that Tesseract should be allowed to segment across multiple hierarchy levels at once, to avoid introducing inconsistent/duplicate text line assignments in text regions, or word assignments in text lines. Hence,

• prefer ocrd-tesserocr-recognize with segmentation_level=region over ocrd-tesserocr-segment followed by ocrd-tesserocr-recognize, if you want to do all in one with Tesseract,
• prefer ocrd-tesserocr-recognize with segmentation_level=line over ocrd-tesserocr-segment-line followed by ocrd-tesserocr-recognize, if you want to do everything but region segmentation with Tesseract,
• prefer ocrd-tesserocr-segment over ocrd-tesserocr-segment-region followed by (ocrd-tesserocr-segment-table and) ocrd-tesserocr-segment-line, if you want to do everything but recognition with Tesseract.

However, you can also run ocrd-tesserocr-segment* and ocrd-tesserocr-recognize with shrink_polygons=True to get polygons by post-processing each segment, shrinking to the convex hull of all its symbol outlines.

Testing

make test

This downloads some test data from https://github.com/OCR-D/assets under repo/assets, and runs some basic test of the Python API as well as the CLIs.

Set PYTEST_ARGS="-s --verbose" to see log output (-s) and individual test results (--verbose).