# hoainv99/ocr-vietnamese architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source OCR system specialized for Vietnamese text. It implements a two-stage pipeline:
a. Text detection using the CRAFT model (craft.py, detection.py, craft_utils.py)
b. Text recognition using a Transformer-based OCR model (model_recognition.py, modules/transformerocr.py, modules/*)

##### File structure
Top-level:
- OCR.py – CLI entry point
- recognition.py / detection.py – high-level functions for each pipeline stage
- imgproc.py / utils.py – image pre-processing, helper routines
- model_recognition.py – orchestrates recognition stage
- craft_utils.py / craft.py – CRAFT-based detector
- config/ – YAML configs for different network backbones (resnet, vgg, transformer)
- modules/ – PyTorch model definitions (cnn, resnet, vgg, transformer, vocabulary)
- tools/ – auxiliary scripts (config generation, translation)
- test/ – sample images and expected outputs

Patterns / architecture hints:
- Pipeline pattern: image → pre-process → detect → crop & reorder → recognize → post-process → output
- Config-driven model instantiation (config/*.yml + tools/config.py)
- Modular network design (each backbone in modules/)

##### README for additional insights
- Describes two core components: CRAFT text detector + Transformer text recognizer
- Requires downloading pretrained models and placing them under a specific directory for “End-to-End-OCR”
- CLI usage example `python3 OCR.py --image_path test/test2.png`

##### Be detailed but not over-engineered
- Cover every folder and its role.
- Both code modules and data/configuration files.
- Keep the high-level flow clear; avoid diagramming every class or function—focus on logical components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Model Loading
    subgraph "Configuration & Model Loading"
        ConfigLoader["Configuration Loader"]:::config
        ConfigYML["YAML Configs"]:::config
    end

    %% Core Pipeline
    subgraph "Core Pipeline" 
        PreProcess["Pre-processing Module"]:::core
        TextDetect["Text Detection Module"]:::core
        CropSort["Text Cropping & Sorting"]:::core
        TextRecog["Text Recognition Module"]:::core
        PostProcess["Post-processing & Output Formatter"]:::core
    end

    %% CLI Entry
    CLI["CLI / Entry Point"]:::core

    %% Auxiliary Tools
    subgraph "Auxiliary Tools" 
        Translate["Translation Scripts"]:::utils
    end

    %% External Resources
    ExternalModels["Pre-trained Models"]:::external
    TestAssets["Test Images & Outputs"]:::external

    %% Data Flows
    CLI -->|"reads configs"| ConfigLoader
    ConfigLoader -->|"load YAML"| ConfigYML
    CLI -->|"image path"| PreProcess
    PreProcess -->|"RGB image tensor"| TextDetect
    TextDetect -->|"List<Boxes>"| CropSort
    CropSort -->|"Cropped image patch"| TextRecog
    TextRecog -->|"Recognized text"| PostProcess
    PostProcess -->|"stdout/file"| CLI

    %% Extensibility
    CLI -->|"invoke"| Translate

    %% External
    ConfigLoader -->|"download models"| ExternalModels
    CLI -->|"test run"| TestAssets

    %% Click Events
    click CLI "https://github.com/hoainv99/ocr-vietnamese/blob/master/OCR.py"
    click ConfigLoader "https://github.com/hoainv99/ocr-vietnamese/blob/master/tools/config.py"
    click ConfigYML "https://github.com/hoainv99/ocr-vietnamese/blob/master/config/base.yml"
    click ConfigYML "https://github.com/hoainv99/ocr-vietnamese/blob/master/config/resnet-transformer.yml"
    click ConfigYML "https://github.com/hoainv99/ocr-vietnamese/blob/master/config/resnet_fpn_transformer.yml"
    click ConfigYML "https://github.com/hoainv99/ocr-vietnamese/blob/master/config/vgg-transformer.yml"
    click PreProcess "https://github.com/hoainv99/ocr-vietnamese/blob/master/imgproc.py"
    click PreProcess "https://github.com/hoainv99/ocr-vietnamese/blob/master/utils.py"
    click TextDetect "https://github.com/hoainv99/ocr-vietnamese/blob/master/craft.py"
    click TextDetect "https://github.com/hoainv99/ocr-vietnamese/blob/master/craft_utils.py"
    click TextDetect "https://github.com/hoainv99/ocr-vietnamese/blob/master/detection.py"
    click TextDetect "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/cnn.py"
    click CropSort "https://github.com/hoainv99/ocr-vietnamese/blob/master/detection.py"
    click CropSort "https://github.com/hoainv99/ocr-vietnamese/blob/master/utils.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/model_recognition.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/recognition.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/transformerocr.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/transformer.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/resnet.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/resnet_fpn.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/vgg.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/vgg16_bn.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/beam.py"
    click TextRecog "https://github.com/hoainv99/ocr-vietnamese/blob/master/modules/vocab.py"
    click Translate "https://github.com/hoainv99/ocr-vietnamese/blob/master/tools/translate.py"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef config fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef utils fill:#fff3e0,stroke:#e65100,color:#bf360c
    classDef external fill:#eceff1,stroke:#37474f,color:#263238
```
