kraken OCR/HTR Engine

kraken is an open-source, turn-key automatic text recognition (ATR) system optimized for historical and non-Latin script writing. It is designed for the humanities to handle low-resource languages and diverse, non-conventional scripts.

Key capabilities include:

• Fully trainable layout analysis, reading order, and character recognition.
• Support for Right-to-Left, BiDi (bi-directional), and Top-to-Bottom scripts.
• Output formats: ALTO, PageXML, abbyyXML, and hOCR.
• Generation of word bounding boxes and character cuts.
• Configurable recognition via a network specification language and a plugin system.

For most programmatic use cases, you should use the High-Level API modules. These provide the primary entry points for interacting with Kraken's core functionality without needing to manage low-level components manually.

The main high-level modules are:

• kraken.containers: For managing data containers.
• kraken.lib.xml: For XML-related utilities.
• kraken.tasks: For defining and executing specific tasks.
• kraken.train: For managing training workflows.

Kraken includes several legacy modules that are retained only for backward compatibility or highly specialized use cases. Their use is not recommended for new projects or standard workflows.

Legacy modules include:

• kraken.binarization
• kraken.pageseg
• kraken.rpred
• kraken.lib.models

The Low-Level API provides direct access to Kraken's core components. While powerful, it is generally recommended to use the High-Level API instead unless you are building custom extensions or require fine-grained control over specific internal mechanisms.

Key low-level modules include:

• kraken.ketos.pretrain and kraken.ketos.train: For specialized training control.
• kraken.lib.dataset: For dataset manipulation.
• kraken.lib.bidi: For bidirectional processing.
• kraken.lib.codec: For codec operations.
• kraken.lib.segmentation: For segmentation tasks.
• kraken.lib.ctc_decoder: For CTC decoding.
• kraken.lib.vgsl: For VGSL-related operations.

kraken uses machine learning models to perform specific tasks. A model acts as a specialized "skill" or "lens" that must be loaded based on your document type:

• Segmentation Model: Used for layout analysis, such as distinguishing between a paragraph and an illustration.
• Recognition Model: Used for reading specific scripts or typefaces (e.g., 17th-century French cursive).

Note: You must use a model trained on the specific script or style of your documents. Using a model trained on modern English to read medieval Latin will result in failure.

When running segtest, you can control how the test-set class mapping is resolved using the --test-class-mapping-mode option. Choosing the right mode is critical for accurate evaluation metrics.

• full: Use this when your training setup merged aliases/classes and your test set uses the same class taxonomy as the training set source files.
• canonical: Use this when your test set uses the same class taxonomy as the output classes of the model (one-to-one mapping).
• custom: Use this when you need explicit remapping or filtering at test time using line_class_mapping or region_class_mapping from your config. This is necessary if the test set has a completely different class taxonomy than the original training dataset.

A hybrid reading order model provides a hierarchical order (regions first, then lines within each region). This is achieved by attaching both a region-ordering model and a baseline-ordering model to the same segmentation model.

To combine these models, use the ketos convert command. Note that the older ketos roadd command is deprecated.

$ ketos convert -i seg.safetensors \
                --add-ro line_ro.safetensors \
                --add-ro region_ro.safetensors \
                -o seg_with_line_and_region_ro.safetensors

Kraken uses Python entry points to allow developers to add new commands, model architectures, and tasks. To create a plugin:

1. Create a new Python package depending on kraken.
2. Implement the required interface (e.g., inheriting from SegmentationBaseModel or RecognitionBaseModel in kraken.models.base).
3. Register the class as an entry point in pyproject.toml or setup.cfg.

Available Entry Point Groups

• kraken.cli: New subcommands for the kraken CLI.
• ketos.cli: New subcommands for the ketos CLI.
• kraken.models: New model architectures.
• kraken.lightning_modules: New PyTorch Lightning modules for training/conversion.
• kraken.loaders: New model loaders.
• kraken.writers: New model writers.
• kraken.tasks: New high-level tasks.

kraken provides two primary interfaces depending on your use case:

1. Command-Line Interface (CLI): A flexible and customizable interface intended for most users. It enables chainable workflows to implement the full recognition pipeline.
2. Python API: A comprehensive API designed for developers who need to build custom workflows, integrate kraken into other projects, or require fine-grained control over the ATR process.