Skip to main content

Toolkit for advanced OCR of poor quality documents

Project description


The package provides a full OCR pipeline including text paragraph detection, text line detection, text transcription, and text refinement using a language model. The package can be used as a command line application or as a python package which provides a document processing class and a class which represents document page content.

Please cite

If you use pero-ocr, please cite:

  • O Kodym, M Hradiš: Page Layout Analysis System for Unconstrained Historic Documents. ICDAR, 2021.
  • M Kišš, K Beneš, M Hradiš: AT-ST: Self-Training Adaptation Strategy for OCR in Domains with Limited Transcriptions. ICDAR, 2021.
  • J Kohút, M Hradiš: TS-Net: OCR Trained to Switch Between Text Transcription Styles. ICDAR, 2021.

Running stuff

Scripts (as well as tests) assume that it is possible to import pero_ocr and its components.

For the current shell session, this can be achieved by setting PYTHONPATH up:

export PYTHONPATH=/path/to/the/repo:$PYTHONPATH

As a more permanent solution, a very simplistic is prepared:

python develop

Beware that the does not promise to bring all the required stuff, e.g. setting CUDA up is up to you.

Pero can be later removed from your Python distribution by running:

python develop --uninstall

Available models

General layout analysis (printed and handwritten) with european printed OCR specialized to czech newspapers can be downloaded here. The OCR engine is suitable for most european printed documents. It is specialized for low-quality czech newspapers digitized from microfilms, but it provides very good results for almast all types of printed documents in most languages. If you are interested in processing printed fraktur fonts, handwritten documents or medieval manuscripts, feel free to contact the authors. The newest OCR engines are available at OCR engines are available also through API runing at, github repository.

Command line application

A command line application is ./user_scripts/ It is able to process images in a directory using an OCR engine. It can render detected lines in an image and provide document content in Page XML and ALTO XML formats. Additionally, it is able to crop all text lines as rectangular regions of normalized size and save them into separate image files.

Integration of the pero-ocr python module

This example shows how to directly use the OCR pipeline provided by pero-ocr package. This shows how to integrate pero-ocr into other applications. Class PageLayout represents content of a single document page and can be loaded from Page XMl and exported to Page XML and ALTO XML formats. The OCR pipeline is represented by the PageParser class.

import os
import configparser
import cv2
from pero_ocr.document_ocr.layout import PageLayout
from pero_ocr.document_ocr.page_parser import PageParser

# Read config file.
config_path = "./config_file.ini"
config = configparser.ConfigParser()

# Init the OCR pipeline. 
# You have to specify config_path to be able to use relative paths
# inside the config file.
Page_parser = PageParser(config, 

# Read the document page image.
input_image_path = "page_image.jpg"
image = cv2.imread(input_image_path, 1)

# Init empty page content. 
# This object will be updated by the ocr pipeline. id can be any string and it is used to identify the page.
page_layout = PageLayout(id=input_image_path,
     page_size=(image.shape[0], image.shape[1]))

# Process the image by the OCR pipeline
page_layout = page_parser.process_page(input_image_path, page_layout)

page_layout.to_pagexml('output_page.xml') # Save results as Page XML.
page_layout.to_altoxml('output_ALTO.xml') # Save results as ALTO XML.

# Render detected text regions and text lines into the image and
# save it into a file.

# Save each cropped text line in a separate .jpg file.
for region in page_layout.regions:
  for line in region.lines:
     cv2.imwrite(f'file_id-{}.jpg', line.crop.astype(np.uint8))


Working changes are expected to happen on develop branch, so if you plan to contribute, you better check it out right during cloning:

git clone -b develop pero-ocr


Currently, only unittests are provided with the code. Some of the code. So simply run your preferred test runner, e.g.:

~/pero-ocr $ green

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pero-ocr-0.6.1.tar.gz (83.8 kB view hashes)

Uploaded source

Built Distribution

pero_ocr-0.6.1-py3-none-any.whl (85.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page