How mittagessen/kraken works
Project Type and Purpose
• Kraken is a domain-specific, full-stack OCR system optimized for historical and non-Latin scripts.
• It provides both a CLI interface for local inference/training (kraken command) and a Python library (kraken.lib), plus an optional HTTP service layer (kraken.ketos) with static web assets for integration.
High-Level Architecture
A. CLI Application Layer
B. Core Processing Library
C. Optional HTTP/REST Service Layer (Ketos)
D. External & Deployment Components
Main Components & Relationships
A. CLI Application Layer
• Entry point: kraken/kraken.py invokes subcommands: binarize, segment, ocr, train, get, list, etc.
• Orchestrates pipelines by calling into Core Processing Library.
• Reads user inputs (image files, options), writes outputs (text, JSON, XML).
B. Core Processing Library (kraken.lib + kraken modules)
• Binarization: kraken.binarization, kraken.lib.functional_im_transforms
• Segmentation: kraken.pageseg, kraken.lib.segmentation, kraken.lib/dataset/segmentation.py
• Line & layout analysis: kraken.align, kraken.blla
• Recognition: model architectures in kraken.lib.models, kraken.lib.pretrain, kraken.lib.ro
• Inference & decoding: kraken.lib.ctc_decoder, kraken.lib.xml, kraken.rpred, kraken/transcribe.py
• Data handling: kraken.lib.dataset, kraken.lib.util, kraken.containers
• Contrib scripts for extended functionality: kraken/contrib/*.py
C. Optional HTTP/REST Service Layer (Ketos)
• Package: kraken.ketos
• Exposes endpoints for training, dataset management, segmentation, recognition, transcription.
• Serves static assets (HTML, CSS, JS) from kraken/templates for a minimal front-end.
• Interacts with the same core modules to perform tasks on server side.
D. External & Deployment Components
• Model repository: downloads from Zenodo (via CLI kraken get)
• Output formats: ALTO, PageXML, ABBYYXML, hOCR via template system (kraken/templates/*)
• Packaging: setup.py, pyproject.toml, environment.yml (CPU/GPU), singularity/kraken.def
• CI: .github/workflows/test.yml, pytest.ini, tests/
Data Flow & Interactions
• User invokes the CLI or sends HTTP request → CLI/Ketos layer
• CLI/Ketos calls Core Library functions in order:
1. Load image(s) → Binarization → Segmentation → Line estimation → Recognition
3. Serialize results in user-specified format (text, JSON, XML)
• Contrib scripts can be plugged in to augment overlays, heatmaps, forced alignment, etc.
Architectural Patterns & Design Principles
• Modular pipeline design: each OCR stage is a separate module, callable independently.
• Plugin-style I/O: format templates exist under kraken/templates; formatters are interchangeable.
• Layered separation:
• Presentation (CLI + Ketos web assets)
• Orchestration (kraken/kraken.py + ketos router)
• Processing core (kraken.lib + algorithm modules)
• Data storage (models, datasets, cache)