# urja4157/simplehtr architecture

> Architecture diagram of the GitHub repository urja4157/simplehtr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urja4157/simplehtr
- Repository: https://github.com/urja4157/simplehtr

## Overview

##### Project Type and Purpose
- This is an open-source machine-learning tool for Handwritten Text Recognition (HTR) built on TensorFlow 2.0.
- It provides three modes—train, validate, infer—via a Python CLI (`src/main.py`).
- It can ingest raw IAM dataset images (words or lines), optionally convert them to LMDB for speed, train a CNN+RNN+CTC model, and run inference with multiple decoders (best-path, beam-search, word-beam-search).

##### Top-Level Components
A. Data Storage
- `data/`: raw input images (`data/corpus.txt` holds the vocabulary).
- IAM dataset (external), organized into `img/` and `gt/`.
- Optional `lmdb/` directory (created by `create_lmdb.py`) for fast image loading.
B. Model Artifacts
- `model/`: trained checkpoints (`snapshot-*`), vocabulary lists (`wordCharList.txt`).
C. Source Code (`src/`):
1. create_lmdb.py – converts raw PNGs → LMDB
2. dataloader_iam.py – loads and batches images (LMDB or PNG)
3. preprocessor.py – resizes, normalizes, augments images
4. model.py – defines CNN layers, LSTM layers, CTC loss & decoding graph
5. main.py – CLI entry point orchestrating train/validate/infer

##### External Dependencies
- TensorFlow 2.x for CNN/RNN/CTC
- Optional CTCWordBeamSearch library for word-beam-search decoder
- Python packages in `requirements.txt`

##### Relationships & Data Flow
1. CLI (`main.py`) reads command-line args (`--mode`, `--fast`, `--decoder`, etc.).
2. If training or validation:
– DataLoader (`dataloader_iam.py`) reads raw PNGs or LMDB → Tensor batches
– Preprocessor applies transforms → feeds into Model graph (`model.py`)
– Model trains or validates, writes checkpoints into `model/`
– Vocabulary extracted → `data/corpus.txt` and `model/wordCharList.txt`
3. If inference:
– DataLoader loads a single image → Preprocessor → Model → raw CTC output
– Decoder layer applies best-path or beam-search or external word-beam-search → final text

##### Architectural Patterns and Design Principles
- Pipeline architecture: clear separation of data ingestion, preprocessing, model definition, training, and inference.
- Modular components: each script/module implements one responsibility.
- External integration point: decoder plugin (CTCWordBeamSearch) for extensibility.

##### Detail
- Every script/module as its own node.
- Optional LMDB path and external decoder integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Layer"
        rawimg["data/ (raw PNGs)"]:::storage
        vocab["data/corpus.txt"]:::storage
        lmdb["lmdb/ (optional)"]:::storage
    end

    subgraph "Processing Layer"
        lmdbconv["LMDB Converter\n(create_lmdb.py)"]:::processing
        dl["DataLoader\n(src/dataloader_iam.py)"]:::processing
        pp["Preprocessor\n(src/preprocessor.py)"]:::processing
    end

    subgraph "Model Layer"
        model["Model Graph\n(CNN+RNN+CTC)\n(src/model.py)"]:::model
    end

    subgraph "Checkpoint Storage"
        ckpts["model/"]:::storage
        vocab_list["model/wordCharList.txt"]:::storage
    end

    subgraph "Decoder Layer"
        builtin["CTC Decoders\n(best-path, beam-search)"]:::processing
        subgraph "External Decoder"
            extdec["CTCWordBeamSearch\n(external)"]:::external
        end
    end

    subgraph "Interface Layer"
        cli["CLI\n(src/main.py)"]:::interface
    end

    rawimg -->|"PNG or LMDB Batch"| dl
    vocab -->|"Vocabulary"| dl
    lmdb -->|"LMDB Batch"| dl
    dl -->|"Raw Tensor Batch"| pp
    pp -->|"Normalized Tensor"| model
    model -->|"CTC logits"| builtin
    model -->|"CTC logits"| extdec
    model -->|"Checkpoints"| ckpts
    model -->|"Vocabulary List"| vocab_list
    builtin -->|"Decoded Text"| out["Decoded Text"]
    extdec -->|"Decoded Text"| out
    cli -->|"orchestrates"| dl
    cli -->|"orchestrates"| model
    cli -->|"orchestrates"| builtin
    cli -->|"orchestrates"| extdec

    click rawimg "https://github.com/urja4157/simplehtr/tree/master/data/"
    click vocab "https://github.com/urja4157/simplehtr/blob/master/data/corpus.txt"
    click lmdb "https://github.com/urja4157/simplehtr/tree/master/lmdb/"
    click lmdbconv "https://github.com/urja4157/simplehtr/blob/master/src/create_lmdb.py"
    click dl "https://github.com/urja4157/simplehtr/blob/master/src/dataloader_iam.py"
    click pp "https://github.com/urja4157/simplehtr/blob/master/src/preprocessor.py"
    click model "https://github.com/urja4157/simplehtr/blob/master/src/model.py"
    click ckpts "https://github.com/urja4157/simplehtr/tree/master/model/"
    click vocab_list "https://github.com/urja4157/simplehtr/blob/master/model/wordCharList.txt"
    click cli "https://github.com/urja4157/simplehtr/blob/master/src/main.py"
    click requirements "https://github.com/urja4157/simplehtr/blob/master/requirements.txt"

    classDef storage fill:#add8e6,stroke:#2f4f4f,color:#000;
    classDef processing fill:#f08080,stroke:#800000,color:#000;
    classDef model fill:#90ee90,stroke:#006400,color:#000;
    classDef interface fill:#fff68f,stroke:#ffd700,color:#000;
    classDef external fill:#fff,stroke:#000,stroke-dasharray:5 5,color:#000;
```
