# konstantinkozhin/manuscript-ocr architecture

> Architecture diagram of the GitHub repository konstantinkozhin/manuscript-ocr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/konstantinkozhin/manuscript-ocr
- Repository: https://github.com/konstantinkozhin/manuscript-ocr

## Overview

Manuscript OCR is a Python framework for OCR/HTR on manuscript and modern document images. Its primary workflow accepts an image, detects text regions, orders them, recognizes text, and can optionally correct the result, represented as structured page data. The repository also contains model-training components for recognition, detection, and text correction. The pipeline excerpt establishes image loading and default detector/layout choices, but omits most stage execution; those stage links are therefore shown as unverified rather than asserted. README capability statements support the broader OCR workflow.

Main entry points: [`src/manuscript/_pipeline.py`](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/_pipeline.py) (OCR pipeline), [`src/manuscript/data/structures.py`](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/data/structures.py) (Page results), [`src/manuscript/recognizers/_trba/__init__.py`](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/__init__.py) (Text recognition), [`src/manuscript/api/base.py`](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/api/base.py) (Model artifacts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["OCR workflow"]
  node_pipeline["OCR pipeline<br/>[_pipeline.py]"]
  node_detection["Text detection<br/>[__init__.py]"]
  node_layout["Reading order<br/>[__init__.py]"]
  node_regions["Region preparation"]
  node_recognition["Text recognition<br/>[__init__.py]"]
  node_correction["Text correction<br/>[__init__.py]"]
end

subgraph group_shared["Shared runtime"]
  node_page["Page results<br/>[structures.py]"]
  node_imageio["Image I/O<br/>[io.py]"]
  node_geometry["Image geometry<br/>[geometry.py]"]
  node_artifact["Model artifacts<br/>[base.py]"]
end

subgraph group_models["Inference models"]
  node_yolo["YOLO detector<br/>[__init__.py]"]
  node_east["EAST detector<br/>[__init__.py]"]
  node_trba_model["TRBA network<br/>[model.py]"]
  node_charlm_model["Correction model<br/>[model.py]"]
end

subgraph group_training["Model training"]
  node_trba_data["Recognition data<br/>[dataset.py]"]
  node_trba_augment["Recognition transforms<br/>[transforms.py]"]
  node_trba_train["Recognition trainer<br/>[train.py]"]
  node_east_data["Detection data<br/>[dataset.py]"]
  node_east_train["Detection training<br/>[train_utils.py]"]
  node_charlm_train["Correction trainer<br/>[train.py]"]
end

node_user(("Image user"))

node_user -->|"submits image"| node_pipeline
node_pipeline -.->|"loads image"| node_imageio
node_pipeline -.->|"runs detection"| node_detection
node_pipeline -.->|"orders regions"| node_layout
node_pipeline -.->|"runs recognition"| node_recognition
node_pipeline -.->|"may correct"| node_correction
node_detection -.->|"produces regions"| node_page
node_layout -.->|"orders page data"| node_page
node_recognition -->|"prepares crops"| node_regions
node_regions -->|"crops regions"| node_geometry
node_recognition -.->|"updates text"| node_page
node_correction -->|"corrects text"| node_page
node_pipeline -.->|"returns result"| node_page
node_pipeline -->|"defaults to"| node_yolo
node_detection -->|"loads weights"| node_artifact
node_recognition -->|"loads weights"| node_artifact
node_correction -->|"loads weights"| node_artifact
node_east_train -.->|"uses dataset"| node_east_data
node_trba_train -->|"uses dataset"| node_trba_data
node_trba_train -->|"uses transforms"| node_trba_augment
node_trba_train -->|"trains model"| node_trba_model
node_charlm_train -->|"trains model"| node_charlm_model
node_east -->|"loads weights"| node_artifact

click node_pipeline "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/_pipeline.py"
click node_detection "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/__init__.py"
click node_layout "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/layouts/_simplesorting/__init__.py"
click node_regions "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_common/region_preparers.py"
click node_recognition "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/__init__.py"
click node_correction "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/__init__.py"
click node_page "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/data/structures.py"
click node_imageio "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/utils/io.py"
click node_geometry "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/utils/geometry.py"
click node_artifact "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/api/base.py"
click node_yolo "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_yolo/__init__.py"
click node_east "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/__init__.py"
click node_trba_model "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/model/model.py"
click node_trba_data "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/data/dataset.py"
click node_trba_augment "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/data/transforms.py"
click node_trba_train "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/training/train.py"
click node_east_data "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/dataset.py"
click node_east_train "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/train_utils.py"
click node_charlm_model "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/model.py"
click node_charlm_train "https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/train.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_pipeline,node_detection,node_layout,node_regions,node_recognition,node_correction,node_user toneBlue
class node_page,node_imageio,node_geometry,node_artifact toneAmber
class node_yolo,node_east,node_trba_model,node_charlm_model toneMint
class node_trba_data,node_trba_augment,node_trba_train,node_east_data,node_east_train,node_charlm_train toneRose
```

## Components

### OCR workflow

- [OCR pipeline](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/_pipeline.py): `src/manuscript/_pipeline.py`
- [Text detection](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/__init__.py): `src/manuscript/detectors/_east/__init__.py`
- [Reading order](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/layouts/_simplesorting/__init__.py): `src/manuscript/layouts/_simplesorting/__init__.py`
- [Region preparation](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_common/region_preparers.py): `src/manuscript/recognizers/_common/region_preparers.py`
- [Text recognition](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/__init__.py): `src/manuscript/recognizers/_trba/__init__.py`
- [Text correction](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/__init__.py): `src/manuscript/correctors/_charlm/__init__.py`

### Shared runtime

- [Page results](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/data/structures.py): `src/manuscript/data/structures.py`
- [Image I/O](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/utils/io.py): `src/manuscript/utils/io.py`
- [Image geometry](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/utils/geometry.py): `src/manuscript/utils/geometry.py`
- [Model artifacts](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/api/base.py): `src/manuscript/api/base.py`

### Inference models

- [YOLO detector](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_yolo/__init__.py): `src/manuscript/detectors/_yolo/__init__.py`
- [EAST detector](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/__init__.py): `src/manuscript/detectors/_east/__init__.py`
- [TRBA network](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/model/model.py): `src/manuscript/recognizers/_trba/model/model.py`
- [Correction model](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/model.py): `src/manuscript/correctors/_charlm/model.py`

### Model training

- [Recognition data](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/data/dataset.py): `src/manuscript/recognizers/_trba/data/dataset.py`
- [Recognition transforms](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/data/transforms.py): `src/manuscript/recognizers/_trba/data/transforms.py`
- [Recognition trainer](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/recognizers/_trba/training/train.py): `src/manuscript/recognizers/_trba/training/train.py`
- [Detection data](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/dataset.py): `src/manuscript/detectors/_east/dataset.py`
- [Detection training](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/detectors/_east/train_utils.py): `src/manuscript/detectors/_east/train_utils.py`
- [Correction trainer](https://github.com/konstantinkozhin/manuscript-ocr/blob/main/src/manuscript/correctors/_charlm/train.py): `src/manuscript/correctors/_charlm/train.py`

### Other components

- **Image user**

## Connections

- Image user → OCR pipeline: submits image
- OCR pipeline → Image I/O: loads image
- OCR pipeline → Text detection: runs detection
- OCR pipeline → Reading order: orders regions
- OCR pipeline → Text recognition: runs recognition
- OCR pipeline → Text correction: may correct
- Text detection → Page results: produces regions
- Reading order → Page results: orders page data
- Text recognition → Region preparation: prepares crops (evidence: `src/manuscript/recognizers/_trba/__init__.py`)
- Region preparation → Image geometry: crops regions (evidence: `src/manuscript/recognizers/_common/region_preparers.py`)
- Text recognition → Page results: updates text
- Text correction → Page results: corrects text (evidence: `src/manuscript/correctors/_charlm/__init__.py`)
- OCR pipeline → Page results: returns result
- OCR pipeline → YOLO detector: defaults to (evidence: `src/manuscript/_pipeline.py`)
- Text detection → Model artifacts: loads weights (evidence: `src/manuscript/detectors/_east/__init__.py`)
- Text recognition → Model artifacts: loads weights (evidence: `src/manuscript/recognizers/_trba/__init__.py`)
- Text correction → Model artifacts: loads weights (evidence: `src/manuscript/correctors/_charlm/__init__.py`)
- Detection training → Detection data: uses dataset
- Recognition trainer → Recognition data: uses dataset (evidence: `src/manuscript/recognizers/_trba/training/train.py`)
- Recognition trainer → Recognition transforms: uses transforms (evidence: `src/manuscript/recognizers/_trba/training/train.py`)
- Recognition trainer → TRBA network: trains model (evidence: `src/manuscript/recognizers/_trba/training/train.py`)
- Correction trainer → Correction model: trains model (evidence: `src/manuscript/correctors/_charlm/train.py`)
- EAST detector → Model artifacts: loads weights (evidence: `src/manuscript/detectors/_east/__init__.py`)
