Skip to content

TuzkaOCR

Lightweight OCR pipeline for scanned page and document images, optimized for CPU inference. It detects page layout and text lines, runs line-level recognition, maps recognized words back to source-image coordinates, and returns ALTO XML or PAGE XML with word bounding boxes, or plain text.

Around 13 MB of model artifacts per domain, no GPU required, and it runs anywhere ONNX Runtime runs.

What it does

  • Page OCR for scanned books, archival material, and historical documents.
  • Four material domains: printed, kramarky broadsheets, Czech handwriting, and German Kurrent/Sütterlin.
  • ALTO XML output with page, block, line, and word coordinates, plus explicit model provenance.
  • PAGE XML output with line baselines and polygons, for Transkribus, eScriptorium and OCR-D.
  • A command-line tool for single pages and batch directories.
  • A FastAPI service with asynchronous job processing, and CPU and GPU container images.
  • Optional API-key authentication, single-key or per-caller.

How a page is processed

  1. Load the image with OpenCV.
  2. Detect regions, baselines, and line heights with the layout model.
  3. Extract perspective-corrected line crops.
  4. For handwritten and Kurrent pages, read all line styles first, then recognize each line with the page-level style. Other domains recognize each line directly.
  5. Assemble ALTO XML, PAGE XML or plain text.

Quickstart

git clone https://github.com/moravianlibrary/TuzkaOCR.git
cd TuzkaOCR
python3 -m venv .venv && source .venv/bin/activate
pip install .
tuzkaocr page.jpg --format txt --out page.txt

New to the command line?

Step by step, no experience needed walks through the same setup assuming no terminal experience, with the Windows and Mac differences spelled out.

Full installation instructions CLI reference

Where to go next

If you want to Read
Install and run it locally Installation then CLI
Do that without using a terminal before Step by step, no experience needed
OCR pages over HTTP HTTP API
Deploy it as a service Docker
Tune threads, memory, or limits Configuration
Pick the right model for your material Models and domains
Parse the output Output formats
Fix something that broke Troubleshooting

Licensing

The source code is licensed under the Apache License 2.0. The model artifacts in tuzkaocr/models/ are licensed separately under CC BY-NC-SA 4.0 — non-commercial use only. See LICENSE, NOTICE, and tuzkaocr/models/LICENSE in the repository.