# xiaofengshi/chinese-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/xiaofengshi/chinese-ocr
- Repository: https://github.com/xiaofengshi/chinese-ocr

## Overview

##### Project Type and Purpose
- This is an offline, modular, deep‐learning OCR pipeline.
- Purpose: Given a scene image, detect text regions (CTPN), correct orientation (VGG‐based angle classifier), then perform line‐level, variable‐length text recognition (CRNN using CTC).
- Training and inference scripts exist for TensorFlow/Keras and PyTorch backends.

##### File Structure (Top‐Level Components)
- angle/: VGG16‐based text‐orientation classifier
- ctpn/: Text‐region detector (CNN+RNN) with utility libs, data prep, and outputs
- crnn/: End‐to‐end text recognizer (CNN+GRU/LSTM+CTC)
- ocr/: Higher‐level wrappers/inference for combining modules
- train/: Dataset generation and training pipelines (keras‐train/ pytorch‐train)
- demo.py/demo.ipynb: Entry point for inference demos
- setup scripts: bash scripts to install env & compile C/C++/CUDA utilities
- config files: _config.yml, ctpn text.yml, various model‐path pointers

##### Extract Architecture Details from README
- Three sub‐networks (modules) in series:
1. Angle classification (rotate image to upright)
3. CRNN recognition (line‐level text → character string via CTC)
- Training pipelines are separate per module; pre‐trained weights are downloaded externally.
- Data‐prep scripts generate Pascal VOC–style annotations or LMDB for CRNN.
- External datasets: CTW, RCTW, SynthText, COCO‐Text, etc.

##### Main Components & Interactions
a. Inference Pipeline:
- Input Image → Angle Classifier (angle/predict.py) → Rotated Image
→ Text Detector (ctpn/ctpn/demo.py) → Crop Text Lines
→ Text Recognizer (crnn/test.py or ocr/model_*.py) → Output Text

b. Training Pipelines (side by side):
- Data Preparation (train/create_dataset) → Format for CTPN or CRNN
- CTPN Training (ctpn/ctpn/train_net.py + pascal_voc)
- CRNN Training:
– Keras variant (train/keras-train/train.py)
– PyTorch variant (train/pytorch-train/crnn_main.py)

c. Shared Utilities & Config:
- ctpn/lib: network definitions, ROI layers, proposal logic, nms, utils (Cython/C++)
- crnn/models/utils.py, dataset & keys modules
- setup‐*.sh scripts build native modules, install requirements

##### Architectural Patterns & Design Principles
- Pipeline pattern: clear stage separation with inputs/outputs
- Modularity: each model in its own package, interchangeable backends (TF/Keras vs PyTorch)
- Layered: low‐level utils (Cython/CLI) → model code → top‐level orchestrators (demo/train)
- Reusability: shared dataset loaders, keys mapping

##### Elements
- Labels: specify filenames or scripts (e.g., ctpn/ctpn/train_net.py) for clarity
- Config files: note _config.yml or text.yml as input to detection module

##### Detail Without Overthinking
- Related files into packages but call out key scripts (demo.py, predict.py, crnn.py)

- Clearly separates training vs inference
- Highlights the three main deep‐learning modules
- Shows the flow of data from raw images to final text
- Captures all essential architectural elements, configurations, and external dependencies.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data & Config Layer
    subgraph "Data & Config"
        direction TB
        D1["asset/ (sample inputs/models)"]:::data
        D2["_config.yml"]:::data
        D3["External Datasets (CTW, COCO-Text, SynthText)"]:::external
        D4["Pre-trained Weights (Baidu Cloud)"]:::external
    end

    %% Training Pipelines
    subgraph "Training Pipelines"
        direction TB
        subgraph "CTPN Training" 
            direction TB
            CT_Dprep["ToVoc.py / split_label.py"]:::train
            CT_Train["train_net.py"]:::train
            CT_Config["text.yml"]:::data
        end
        subgraph "CRNN Keras Training"
            direction TB
            CK_Data["train/keras-train/dataset.py"]:::train
            CK_Model["train/keras-train/model.py"]:::train
            CK_Train["train/keras-train/train.py"]:::train
            CK_All["train/keras-train/allinonetrain.py"]:::train
        end
        subgraph "CRNN PyTorch Training"
            direction TB
            CP_Data["train/pytorch-train/dataset.py"]:::train
            CP_Model["train/pytorch-train/models/crnn.py"]:::train
            CP_Train["crnn_main.py"]:::train
        end
        subgraph "Dataset Generation"
            direction TB
            DG_LMDB["create_dataset.py"]:::train
            DG_Script["create-dataset.sh"]:::train
        end
    end

    %% Inference Pipeline
    subgraph "Inference Pipeline"
        direction TB
        I1["Input Image"]:::external
        Angle["Angle Classification\n(predict.py)"]:::infer
        Rotated["Rotated Image"]:::infer
        CTPN_Infer["CTPN Detection\n(demo.py)"]:::infer
        Crops["Crop Text Lines"]:::infer
        CRNN_Infer["CRNN Recognition\n(test.py)"]:::infer
        OCR_Wrapper["OCR Wrapper\n(model.py / model_tf.py)"]:::infer
        Output["Output Text"]:::external
        DemoEP["demo.py / demo.ipynb"]:::infer
    end

    %% Utilities & Native Modules
    subgraph "Utilities & Native Modules"
        direction TB
        U1["ctpn/lib/ (network defs & utils)"]:::util
        U2["setup.sh / setup-cpu.sh\nsetup-python3.sh"]:::util
    end

    %% Connections - Data to Training
    D3 -->|provides data| CT_Dprep
    CT_Config --> CT_Train
    CT_Dprep --> CT_Train
    D3 --> CK_Data
    D3 --> CP_Data
    DG_LMDB --> CK_Data
    DG_LMDB --> CP_Data

    %% Connections - Pretrained Weights to Inference
    D4 --> Angle
    D4 --> CTPN_Infer
    D4 --> CRNN_Infer

    %% Inference Flow
    I1 --> Angle
    Angle --> Rotated
    Rotated --> CTPN_Infer
    CTPN_Infer --> Crops
    Crops --> CRNN_Infer
    CRNN_Infer --> OCR_Wrapper
    OCR_Wrapper --> Output
    DemoEP -.-> Angle
    DemoEP -.-> CTPN_Infer
    DemoEP -.-> CRNN_Infer

    %% Utilities Dependencies
    U1 --> CT_Train
    U1 --> CTPN_Infer
    U2 --> U1

    %% Click Events
    click Angle "https://github.com/xiaofengshi/chinese-ocr/blob/master/angle/predict.py"
    click CTPN_Infer "https://github.com/xiaofengshi/chinese-ocr/blob/master/ctpn/ctpn/demo.py"
    click CT_Train "https://github.com/xiaofengshi/chinese-ocr/blob/master/ctpn/ctpn/train_net.py"
    click CT_Config "https://github.com/xiaofengshi/chinese-ocr/blob/master/ctpn/ctpn/text.yml"
    click U1 "https://github.com/xiaofengshi/chinese-ocr/tree/master/ctpn/lib/"
    click CT_Dprep "https://github.com/xiaofengshi/chinese-ocr/blob/master/ctpn/prepare_training_data/ToVoc.py"
    click CT_Dprep "https://github.com/xiaofengshi/chinese-ocr/blob/master/ctpn/prepare_training_data/split_label.py"
    click CRNN_Infer "https://github.com/xiaofengshi/chinese-ocr/blob/master/crnn/test.py"
    click CRNN_Infer "https://github.com/xiaofengshi/chinese-ocr/blob/master/crnn/crnn.py"
    click CK_Model "https://github.com/xiaofengshi/chinese-ocr/blob/master/crnn/models/crnn.py"
    click CK_Model "https://github.com/xiaofengshi/chinese-ocr/blob/master/crnn/models/utils.py"
    click OCR_Wrapper "https://github.com/xiaofengshi/chinese-ocr/blob/master/ocr/model.py"
    click OCR_Wrapper "https://github.com/xiaofengshi/chinese-ocr/blob/master/ocr/model_tf.py"
    click DemoEP "https://github.com/xiaofengshi/chinese-ocr/blob/master/demo.py"
    click DemoEP "https://github.com/xiaofengshi/chinese-ocr/blob/master/demo.ipynb"
    click D2 "https://github.com/xiaofengshi/chinese-ocr/blob/master/_config.yml"
    click CK_Train "https://github.com/xiaofengshi/chinese-ocr/blob/master/train/keras-train/train.py"
    click CP_Train "https://github.com/xiaofengshi/chinese-ocr/blob/master/train/pytorch-train/crnn_main.py"
    click DG_LMDB "https://github.com/xiaofengshi/chinese-ocr/blob/master/train/create_dataset/create_dataset.py"
    click DG_Script "https://github.com/xiaofengshi/chinese-ocr/blob/master/train/create-dataset.sh"
    click U2 "https://github.com/xiaofengshi/chinese-ocr/blob/master/setup.sh"
    click U2 "https://github.com/xiaofengshi/chinese-ocr/blob/master/setup-cpu.sh"
    click U2 "https://github.com/xiaofengshi/chinese-ocr/blob/master/setup-python3.sh"

    %% Styles
    classDef data fill:#f9d5a2,stroke:#e09f3e,color:#000
    classDef train fill:#a3dda8,stroke:#55a630,color:#000
    classDef infer fill:#9ec1cf,stroke:#2b6777,color:#000
    classDef util fill:#dddddd,stroke:#777777,color:#000
    classDef external fill:none,stroke-dasharray: 5 5,stroke:#888888,color:#000
```
