# sanny26/indic-htr architecture

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

- Interactive diagram: https://gitdiagram.com/sanny26/indic-htr
- Repository: https://github.com/sanny26/indic-htr

## Overview

##### Main Components
a. Data Preparation & Datasets:
- The README explains that LMDB files must be created for train/validation/test splits. The datasets directory (with files such as dataset.py, ae_transforms.py, label_transform.py, etc.) shows the preprocessing pipeline, including data transformations (e.g., skew transforms, grid distortions) specific to handling handwriting images.
- The alphabet folder contains language-specific alphabet text files that supply the Unicode symbols needed for prediction.
b. Model Architectures:
c. Training and Evaluation:
- Training scripts are found as base_train.py and lang_train.py. The README describes how to run training and testing modes.
- There are also tools scripts for creating datasets (tools/create_dataset.py) and for scoring predictions (tools/score.py and tools/oov_score.py) to check error rates (WER/CER).
d. Configuration and Utilities:
- Files like config.py and utils.py handle hyperparameters and common functions.
- The pyproject.toml file and the LICENSE file give further project management and legal context.

##### Relationships and Interactions
- Input -> Data Preparation: Data flows from raw images (arranged per the dataset structure) through the dataset module, where image transforms are applied.
- The preprocessed data and the alphabet text comprise the inputs for training; your training scripts (lang_train.py) call the dataset functions.
- The model components (from the models folder) are dynamically loaded by the training scripts and layered to form the recognition pipeline.
- Once the model processes inputs, outputs are evaluated through scoring tools.
- There is a clear dependency between components—for example, the datasets provide the critical data preparing stage that feeds directly into the training routines, which in turn use the model definitions.

##### Architectural Patterns and Design Principles
- The project employs a modular design with separation of concerns: (a) data handling in the datasets directory, (b) network modeling with separated files for different model types and submodules in the models directory, and (c) explicit training control via dedicated training scripts.
- Design principles include a pipeline-based approach: Data → Preprocessing → Model Inference → Loss/CTC Evaluation → Scoring.
- It follows extensibility patterns so that components (e.g., adding more language alphabets or new data transforms) can be updated independently.

##### Technologies and Frameworks
- Deep learning frameworks (likely PyTorch given similar open-source projects mentioned) form the backbone.
- LMDB is used for dataset storage and retrieval.
- External libraries might include image processing libraries (e.g., OpenCV or PIL) in the dataset transforms.
- The training process leverages CUDA if available.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Sys["Indic Handwriting Text Recognition System"]:::external

    Raw["Raw Handwritten Images"]:::external

    subgraph "Data Preparation & Preprocessing"
        DP1["Dataset.py"]:::data
        DP2["AE_Transforms.py"]:::data
        DP3["Skew_Transform.py"]:::data
        DP4["Grid_Distort.py"]:::data
        DP5["Label_Transform.py"]:::data
        DP6["Imprint_Dataset.py"]:::data
        AL["Alphabet Folder"]:::data
    end

    subgraph "Model Architecture"
        subgraph "Core Models"
            M1["Model.py"]:::model
            M2["Basic_CRNN.py"]:::model
            M3["Res_CRNN.py"]:::model
        end
        subgraph "Spatial Transformer Networks"
            ST1["Affine_STN.py"]:::model
            ST2["TPS_STN.py"]:::model
            ST3["STN_Head.py"]:::model
        end
    end

    subgraph "Training & Evaluation"
        subgraph "Training Scripts"
            T1["base_train.py"]:::training
            T2["lang_train.py"]:::training
            T3["pretrain.py"]:::training
        end
        subgraph "Evaluation Tools"
            E1["Score.py"]:::training
            E2["OOV_Score.py"]:::training
            E3["Create_Dataset.py"]:::training
            E4["Logger.py"]:::training
        end
    end

    subgraph "Utilities & Config"
        U1["Config.py"]:::utility
        U2["pyproject.toml"]:::utility
        U3["Utils.py"]:::utility
        U4["README.md"]:::utility
        U5["LICENSE"]:::utility
    end

    Raw -->|"feeds"| DP1
    Raw -->|"feeds"| DP2
    Raw -->|"feeds"| DP3
    Raw -->|"feeds"| DP4
    Raw -->|"feeds"| DP5
    Raw -->|"feeds"| DP6

    AL -->|"provides_alphabets"| M1

    DP1 -->|"preprocessed_data"| M1
    DP2 --> M1
    DP3 --> M1
    DP4 --> M1
    DP5 --> M1
    DP6 --> M1

    M1 -->|"model_inference"| T1
    M2 --> T1
    M3 --> T1
    ST1 --> M1
    ST2 --> M1
    ST3 --> M1

    T1 -->|"training_outputs"| E1
    T1 --> E2
    T1 --> E3
    T1 --> E4

    E1 -->|"feedback"| T2
    E2 --> T2
    E3 --> T2
    E4 --> T2

    U1 --- DP1
    U1 --- M1
    U1 --- T1
    U3 --- DP2
    U3 --- M2
    U3 --- T2

    Sys --- Raw
    Sys --- AL
    Sys --- U1

    click DP1 "https://github.com/sanny26/indic-htr/blob/main/datasets/dataset.py"
    click DP2 "https://github.com/sanny26/indic-htr/blob/main/datasets/ae_transforms.py"
    click DP3 "https://github.com/sanny26/indic-htr/blob/main/datasets/skew_transform.py"
    click DP4 "https://github.com/sanny26/indic-htr/blob/main/datasets/grid_distort.py"
    click DP5 "https://github.com/sanny26/indic-htr/blob/main/datasets/label_transform.py"
    click DP6 "https://github.com/sanny26/indic-htr/blob/main/datasets/imprint_dataset.py"
    click AL "https://github.com/sanny26/indic-htr/tree/main/alphabet/"

    click M1 "https://github.com/sanny26/indic-htr/blob/main/models/model.py"
    click M2 "https://github.com/sanny26/indic-htr/blob/main/models/basic_crnn.py"
    click M3 "https://github.com/sanny26/indic-htr/blob/main/models/res_crnn.py"
    click ST1 "https://github.com/sanny26/indic-htr/blob/main/models/affine_stn.py"
    click ST2 "https://github.com/sanny26/indic-htr/blob/main/models/tps_stn.py"
    click ST3 "https://github.com/sanny26/indic-htr/blob/main/models/stn_head.py"

    click T1 "https://github.com/sanny26/indic-htr/blob/main/base_train.py"
    click T2 "https://github.com/sanny26/indic-htr/blob/main/lang_train.py"
    click T3 "https://github.com/sanny26/indic-htr/blob/main/pretrain.py"
    click E1 "https://github.com/sanny26/indic-htr/blob/main/tools/score.py"
    click E2 "https://github.com/sanny26/indic-htr/blob/main/tools/oov_score.py"
    click E3 "https://github.com/sanny26/indic-htr/blob/main/tools/create_dataset.py"
    click E4 "https://github.com/sanny26/indic-htr/blob/main/tools/logger.py"
    click U1 "https://github.com/sanny26/indic-htr/blob/main/config.py"
    click U2 "https://github.com/sanny26/indic-htr/blob/main/pyproject.toml"
    click U3 "https://github.com/sanny26/indic-htr/blob/main/utils.py"
    click U4 "https://github.com/sanny26/indic-htr/blob/main/README.md"
    click U5 "https://github.com/sanny26/indic-htr/tree/main/LICENSE"

    classDef external fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef data fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef model fill:#cce5ff,stroke:#004080,stroke-width:2px;
    classDef training fill:#fff2cc,stroke:#b36b00,stroke-width:2px;
    classDef utility fill:#e6ccff,stroke:#660099,stroke-width:2px;
```
