# harshlunia7/indicstr12_icdar architecture

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

- Interactive diagram: https://gitdiagram.com/harshlunia7/indicstr12_icdar
- Repository: https://github.com/harshlunia7/indicstr12_icdar

## Overview

##### Project Type and Purpose
- This is an open-source research codebase for Indic scene text recognition (“IndicSTR12_ICDAR”), implementing three different model pipelines (CRNN, STAR-Net, and Parseq) on the same dataset, with end-to-end scripts for data preparation, training, evaluation, and demos.

##### High-Level File Structure Analysis
- Top-Level Directories:
- crnn/ – Implementation of the CRNN model pipeline
- starnet/ – Implementation of the STAR-Net model pipeline
- parseq/ – Implementation of the Parseq model pipeline (with Hydra‐style config management)
- Shared Concerns:
- dataset.py, utils.py in each pipeline for data loading, preprocessing, lexicon handling
- demo*.py and script.sh for inference demos
- train.py, finetune.py, mytrain.py for training loops
- tool/ subfolder for data-conversion utilities (LMDB creation, format converters)
- parseq/ additionally contains:
- config/ and configs/ for dataset, model, experiment definitions via YAML
- strhub/ subpackage exposing models as a PyTorch Hub entry point

##### Key Components
A. Data Layer
– Raw Scene Text Images (IndicSTR12 dataset)
– Data Conversion Tools (tool/ scripts → LMDB, Coco, etc.)
– Preprocessing Modules (dataset.py → resize, normalize, augment)
B. Core Model Pipelines (three parallel blocks)
1. CRNN Pipeline (crnn/models/... )
- Transformation → Feature Extraction → Sequence Modeling → CTC Decoder
2. STAR-Net Pipeline (starnet/models/modules/…)
- Spatial Transformer → CNN Backbone → RNN or Attention → Decoder
3. Parseq Pipeline (parseq/strhub/models/parseq)
- Patch Embedding → Transformer Encoder → Positional Encoding → Sequence Head
– Each pipeline has: training script, finetune script, demo script
C. Configuration & Orchestration
– parseq’s Hydra configs (config/*.yaml)
– params.py or params dictionaries in CRNN/STAR-Net
– Script wrappers (script.sh) to launch jobs (single-GPU or distributed)
D. External Frameworks & Libraries
– PyTorch (core DL)
– Hydra (configuration)
– LMDB, OpenCV or PIL (I/O)
– Lua Torch conversion (convert_t7.lua)
E. Outputs & Evaluation
– Trained model artifacts (.pt, .t7)
– Logs, metrics (accuracy, CER/WER)
– Demo visualizations (overlayed text)

##### Relationships and Data Flows
- From Preprocessed Data → each Pipeline’s Data Loader
- Within each Pipeline block: Data Loader → Preprocessing → Model → Loss Computation → Checkpoint Writer
- From Checkpoint → Inference Demo → Output Images/Reports
- Configuration inputs (YAML/params.py) feed into both Training and Demo scripts

##### Architectural Patterns & Design Principles
- Modular pipeline design: clearly separated data, model, and training modules
- Single responsibility: each script or module does one job (convert, load, train, demo)
- Extensibility points: add new model under strhub/models or new config in parseq/configs
- Reusable utilities in utils.py and common tool scripts

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        RawImages["Raw Scene Text Images"]:::data
        CRNNTools["CRNN Conversion Tools"]:::tools
        STools["STAR-Net Conversion Tools"]:::tools
        PTools["Parseq Conversion Tools"]:::tools
        Preprocessed["LMDB / Preprocessed Data"]:::data
        RawImages --> CRNNTools --> Preprocessed
        RawImages --> STools --> Preprocessed
        RawImages --> PTools --> Preprocessed
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        SharedUtils["utils.py"]:::module
    end
    SharedUtils --> Preprocessed

    %% CRNN Pipeline
    subgraph "CRNN Pipeline"
        CRNNLoader["crnn/dataset.py"]:::module
        CRNNPre["Preprocessing"]:::module
        subgraph "CRNN Model"
            CRNNTrans["Transformation"]:::module
            CRNNFeat["Feature Extraction"]:::module
            CRNNSeq["Sequence Modeling"]:::module
            CRNNCTC["CTC Decoder"]:::module
            CRNNTrans --> CRNNFeat --> CRNNSeq --> CRNNCTC
        end
        CRNNScriptTrain["train.py"]:::script
        CRNNScriptFine["finetune.py"]:::script
        CRNNScriptMy["mytrain.py"]:::script
        CRNNScriptDemo["demo.py"]:::script
        CRNNScriptSh["script.sh"]:::script

        Preprocessed --> CRNNLoader --> CRNNPre --> CRNNTrans
        CRNNCTC --> CRNNScriptTrain
        CRNNCTC --> CRNNScriptFine
        CRNNCTC --> CRNNScriptMy
        CRNNCTC --> CRNNScriptDemo
        CRNNCTC --> CRNNScriptSh
    end

    %% STAR-Net Pipeline
    subgraph "STAR-Net Pipeline"
        STLoader["starnet/dataset.py"]:::module
        STPre["Preprocessing"]:::module
        subgraph "STAR-Net Model"
            STTrans["Spatial Transformer"]:::module
            STFeat["CNN Backbone"]:::module
            STSeq["RNN/Attention"]:::module
            STDec["Decoder"]:::module
            STTrans --> STFeat --> STSeq --> STDec
        end
        STScriptTrain["train.py"]:::script
        STScriptFine["finetune.py"]:::script
        STScriptDemo["demo.py"]:::script
        STScriptSh["script.sh"]:::script

        Preprocessed --> STLoader --> STPre --> STTrans
        STDec --> STScriptTrain
        STDec --> STScriptFine
        STDec --> STScriptDemo
        STDec --> STScriptSh
    end

    %% Parseq Pipeline
    subgraph "Parseq Pipeline"
        PLoader["parseq/strhub/data/dataset.py"]:::module
        PAug["augment.py"]:::module
        PUtils["utils.py"]:::module
        subgraph "Parseq Model"
            PPatch["Patch Embedding"]:::module
            PPos["Positional Encoding"]:::module
            PEnc["Transformer Encoder"]:::module
            PHead["Sequence Head"]:::module
            PPatch --> PPos --> PEnc --> PHead
        end
        PScriptTrain["train.py"]:::script
        PScriptFine["finetune.py"]:::script
        PScriptTune["tune.py"]:::script
        PScriptBench["bench.py"]:::script
        PScriptTest["test.py"]:::script

        Preprocessed --> PLoader --> PAug --> PUtils --> PPatch
        PHead --> PScriptTrain
        PHead --> PScriptFine
        PHead --> PScriptTune
        PHead --> PScriptBench
        PHead --> PScriptTest
    end

    %% Configuration Layer
    subgraph "Configuration & Orchestration"
        HydraConfig["Hydra Configs"]:::config
        ParamsCRNN["crnn/params.py"]:::config
        ParamsST["starnet/params.py"]:::config
        ScriptWrapper["script.sh wrappers"]:::script
        HydraConfig --> CRNNLoader
        HydraConfig --> STLoader
        HydraConfig --> PLoader
    end

    %% External Frameworks
    subgraph "External Frameworks"
        Torch["PyTorch"]:::external
        HydraExt["Hydra"]:::external
        LMDBExt["LMDB"]:::external
        OpenCV["OpenCV/PIL"]:::external
    end
    Torch --> CRNNTrans
    Torch --> STTrans
    Torch --> PPatch
    HydraExt --> HydraConfig
    LMDBExt --> Preprocessed
    OpenCV --> Preprocessed

    %% Outputs & Evaluation
    subgraph "Outputs & Evaluation"
        Checkpoints["Checkpoints (.pt, .t7)"]:::output
        Logs["Logs & Metrics"]:::output
        DemoOuts["Demo Visualizations"]:::output
    end
    CRNNScriptTrain --> Checkpoints
    STScriptTrain --> Checkpoints
    PScriptTrain --> Checkpoints
    CRNNScriptTrain --> Logs
    STScriptTrain --> Logs
    PScriptTrain --> Logs
    CRNNScriptDemo --> DemoOuts
    STScriptDemo --> DemoOuts
    PScriptBench --> DemoOuts

    %% Click Events
    click CRNNTools "https://github.com/harshlunia7/indicstr12_icdar/tree/main/crnn/tool/"
    click STools "https://github.com/harshlunia7/indicstr12_icdar/tree/main/starnet/tool/"
    click PTools "https://github.com/harshlunia7/indicstr12_icdar/tree/main/parseq/tools/"
    click CRNNLoader "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/dataset.py"
    click CRNNPre "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/utils.py"
    click CRNNTrans "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/models/modules/transformation.py"
    click CRNNFeat "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/models/modules/feature_extraction.py"
    click CRNNSeq "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/models/modules/sequence_modeling.py"
    click CRNNCTC "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/models/model.py"
    click CRNNScriptTrain "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/train.py"
    click CRNNScriptFine "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/finetune.py"
    click CRNNScriptMy "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/mytrain.py"
    click CRNNScriptDemo "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/demo.py"
    click CRNNScriptSh "https://github.com/harshlunia7/indicstr12_icdar/blob/main/crnn/script.sh"

    click STLoader "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/dataset.py"
    click STPre "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/utils.py"
    click STTrans "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/models/modules/transformation.py"
    click STFeat "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/models/modules/feature_extraction.py"
    click STSeq "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/models/modules/sequence_modeling.py"
    click STDec "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/models/model.py"
    click STScriptTrain "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/train.py"
    click STScriptFine "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/finetune.py"
    click STScriptDemo "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/demo.py"
    click STScriptSh "https://github.com/harshlunia7/indicstr12_icdar/blob/main/starnet/script.sh"

    click PLoader "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/strhub/data/dataset.py"
    click PAug "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/strhub/data/augment.py"
    click PUtils "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/strhub/data/utils.py"
    click PPatch "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/strhub/models/parseq/modules.py"
    click PEnc "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/strhub/models/parseq/system.py"
    click PScriptTrain "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/train.py"
    click PScriptFine "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/finetune.py"
    click PScriptTune "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/tune.py"
    click PScriptBench "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/bench.py"
    click PScriptTest "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/test.py"
    click HydraConfig "https://github.com/harshlunia7/indicstr12_icdar/blob/main/parseq/config/main.yaml"

    %% Styles
    classDef data fill:#FFF2CC,stroke:#E0A800,stroke-width:2px
    classDef tools fill:#E8F6F3,stroke:#17A2B8,stroke-width:2px
    classDef module fill:#DDEBF7,stroke:#2B579A,stroke-width:2px
    classDef script fill:#F4ECF7,stroke:#6F42C1,stroke-width:2px
    classDef config fill:#FDEDEC,stroke:#C82333,stroke-width:2px
    classDef external fill:#E2E3E5,stroke:#6C757D,stroke-width:2px
    classDef output fill:#E8F5E9,stroke:#28A745,stroke-width:2px
```
