# bmd1905/vietnamese-ocr architecture

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

- Interactive diagram: https://gitdiagram.com/bmd1905/vietnamese-ocr
- Repository: https://github.com/bmd1905/vietnamese-ocr

## Overview

##### Project Type and Purpose
- This is an end-to-end OCR pipeline tool (not a web app) combining two major subsystems:
a. PaddleOCR – handles text detection.
b. VietOCR – handles Vietnamese text recognition using a Transformer OCR model.
- Users interact via CLI scripts (predict.py) or Jupyter notebooks (predict.ipynb).

##### High-Level Components
A. User Interface Layer
- CLI / Notebook
– predict.py, predict.ipynb
– Accepts image path & output path parameters
B. Orchestration Layer (Controller)
- predict.py main() function
- Loads configurations & dispatches to detection & recognition subsystems
C. Text Detection Subsystem (PaddleOCR)
- Config Loader (YAML configs under PaddleOCR/configs/det)
- Pre-processing
– Image normalization, resizing
- Detection Model
– DB algorithm implemented in ppocr/modeling/backbones + heads + necks
- Post-processing
- Crop & Pad Module
– Crops detected regions and pads them for recognition
D. Text Recognition Subsystem (VietOCR)
- Config Loader (vietocr/config/*.yml)
- Pre-processing
– Resize & normalize cropped image
- CNN + Transformer Model
– CNN backbone extracts visual features
– Transformer decoder generates character sequences
- Post-processing
– Beam search or greedy decoding
– Vocabulary mapping (vietocr/model/vocab.py)
E. Utility & Shared Modules
- Logging, profiling (ppocr/utils/loggers)
- Configuration management (vietocr/tool/config.py)
- Image I/O, augmentation (ppocr/data & vietocr/loader)
F. Output Layer
- JSON/Text file or image overlay with recognized text
- save_to_file / display results

##### Relationships & Data Flow
1. User → CLI/Notebook
– CLI parses arguments, loads configs
2. CLI → Detection Subsystem
– Pass raw image
5. Recognition → Text Strings
6. Orchestrator → Aggregates & saves final result

##### Architectural Patterns & Principles
- Pipeline pattern: clearly separated stages (detect → crop → recognize)
- Strategy for model choice via external YAML configs
- Modular code: detection and recognition are loosely coupled
- Single responsibility per module: ppocr handles all detection concerns; vietocr handles recognition

##### Technologies & Frameworks
- PaddleOCR core (PaddlePaddle) for detection
- PyTorch-based VietOCR for recognition
- YAML config files to switch models
- Python scripts for orchestration and utilities

##### Details to Capture
- Config loading: show that both subsystems read separate YAML trees.
- Cropping and padding step as a bridge between detection & recognition.
- Orchestrator script (predict.py) as the central controller.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer" 
        direction TB
        CLI["CLI (predict.py)"]:::ui
        Notebook["Notebook (predict.ipynb)"]:::ui
    end

    %% Orchestration Layer
    Orchestrator["Orchestrator\npredict.py main()"]:::ui

    %% Detection Subsystem
    subgraph "Text Detection Subsystem (PaddleOCR)" 
        direction TB
        Det_Config["Config Loader\n(YAML)"]:::det
        Det_Pre["Pre-processing"]:::det
        Det_Model["Detection Model"]:::det
        Det_Post["Post-processing"]:::det
        CropPad["Crop & Pad Module"]:::det
    end

    %% Recognition Subsystem
    subgraph "Text Recognition Subsystem (VietOCR)"
        direction TB
        Rec_Config["Config Loader\n(YAML)"]:::rec
        Pre_Rec["Pre-processing"]:::rec
        Model_Rec["CNN + Transformer Model"]:::rec
        Post_Rec["Post-processing"]:::rec
    end

    %% Utility & Shared Modules
    subgraph "Utility & Shared Modules"
        direction TB
        Logging["Logging & Profiling"]:::util
        ConfigTool["Configuration Management"]:::util
        IO["Image I/O & Augmentation"]:::util
    end

    %% Output Layer
    Output["Output Layer\n(save/display)"]:::ui

    %% Data Flow
    CLI -->|"args"| Orchestrator
    Notebook -->|"args"| Orchestrator

    Orchestrator -->|"load det config"| Det_Config
    Orchestrator -->|"load rec config"| Rec_Config

    Orchestrator -->|"raw image"| Det_Pre
    Det_Pre --> Det_Model
    Det_Model --> Det_Post
    Det_Post --> CropPad
    CropPad -->|"cropped images"| Pre_Rec
    Pre_Rec --> Model_Rec
    Model_Rec --> Post_Rec
    Post_Rec -->|"text strings"| Orchestrator
    Orchestrator -->|"final result"| Output

    %% Utility connections
    Orchestrator -.-> Logging
    Det_Pre -.-> IO
    Pre_Rec -.-> IO
    Det_Model -.-> Logging
    Model_Rec -.-> Logging
    Det_Config -.-> ConfigTool
    Rec_Config -.-> ConfigTool

    %% Click Events
    click CLI "https://github.com/bmd1905/vietnamese-ocr/blob/master/predict.py"
    click Notebook "https://github.com/bmd1905/vietnamese-ocr/blob/master/predict.ipynb"
    click Orchestrator "https://github.com/bmd1905/vietnamese-ocr/blob/master/predict.py"
    click Det_Config "https://github.com/bmd1905/vietnamese-ocr/tree/master/PaddleOCR/configs/det"
    click Det_Pre "https://github.com/bmd1905/vietnamese-ocr/tree/master/PaddleOCR/ppocr/data/imaug"
    click Det_Pre "https://github.com/bmd1905/vietnamese-ocr/blob/master/PaddleOCR/ppocr/data/collate_fn.py"
    click Det_Model "https://github.com/bmd1905/vietnamese-ocr/tree/master/PaddleOCR/ppocr/modeling/backbones"
    click Det_Post "https://github.com/bmd1905/vietnamese-ocr/blob/master/PaddleOCR/ppocr/postprocess/db_postprocess.py"
    click CropPad "https://github.com/bmd1905/vietnamese-ocr/blob/master/PaddleOCR/paddleocr.py"
    click Rec_Config "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/config.yml"
    click Rec_Config "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/config/base.yml"
    click Pre_Rec "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/loader/aug.py"
    click Pre_Rec "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/loader/dataloader.py"
    click Model_Rec "https://github.com/bmd1905/vietnamese-ocr/tree/master/vietocr/vietocr/model/backbone"
    click Post_Rec "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/model/beam.py"
    click Logging "https://github.com/bmd1905/vietnamese-ocr/tree/master/PaddleOCR/ppocr/utils/loggers"
    click Logging "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/tool/logger.py"
    click ConfigTool "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/tool/config.py"
    click IO "https://github.com/bmd1905/vietnamese-ocr/tree/master/PaddleOCR/ppocr/data"
    click Output "https://github.com/bmd1905/vietnamese-ocr/blob/master/vietocr/vietocr/tool/predictor.py"

    %% Styles
    classDef det fill:#cfe2f3,stroke:#2a4d69,color:#0f1e2e;
    classDef rec fill:#d9ead3,stroke:#38761d,color:#274e13;
    classDef util fill:#f2f2f2,stroke:#999999,color:#333333;
    classDef ui fill:#fce5cd,stroke:#e69138,color:#7f6000;
```
