# topdu/openocr architecture

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

- Interactive diagram: https://gitdiagram.com/topdu/openocr
- Repository: https://github.com/topdu/openocr

## Overview

##### Main Components
- Data Management & Configuration:
– Configuration files under “configs” for datasets (configs/dataset), detection (configs/det), and recognition (configs/rec).
– “tools/data” which contains various dataset loaders and collate functions.
- Detection Module:
– “opendet” directory contains losses, metrics, modeling (backbones, heads, necks), postprocessing, and preprocessing specific to scene text detection.
- Recognition Module:
– “openrec” directory holds losses, metrics, modeling and its submodules (encoders, decoders, transforms, preprocess, postprocess) for scene text recognition.
- Core Engine & Integration:
– The main entry file (via __init__.py) and the “OpenOCR” class that abstracts the whole system.
– “tools” directory contains scripts for training (train_det.py, train_rec.py), inference (infer_det.py, infer_rec.py, infer_e2e.py), conversion (toonnx.py), and utilities.
- Inference Backends:
– Support for both Pytorch inference and ONNX-based inference as seen in the README and corresponding tools.
- Utility and Deployment:
– “tools/utils” with dictionaries, logging, checkpoint utilities, etc.
– Demo and Gradio integration with demo_gradio.py, indicating an interactive demo setup.

##### Relationships and Interactions
- Data Flow:
– Raw image input is fed into a preprocessing stage (found both in “opendet/preprocess” and “openrec/preprocess”).
– Preprocessed data is then sent to the detection module (for locating text regions) in the “opendet” branch.
– Outputs from the recognition module may then be postprocessed (using their respective postprocessing logic) to produce the final OCR result.
- Configuration Layer:
– All modules use YAML configuration files (located in “configs/”) for model settings, datasets, training hyperparameters, and inference parameters.
- Model Training & Inference:
– “tools/engine”, “tools/train_det.py”, “tools/train_rec.py”, and “tools/infer*” scripts act as drivers that coordinate between configuration, model building, and applying proper losses and metrics.
- Backend Switching:

##### Architectural Patterns and Design Principles
- Modularity: Clearly separated modules for detection and recognition promote ease of extension—for instance, integrating new recognition algorithms (like SVTRv2, IGTR, SMTR) is as straightforward as adding new configuration files and updating “openrec/modeling”.
- Pipeline Pattern: The OCR processing chain fits a typical pipeline model that flows from input (data preprocessing) → core processing (detection and recognition modules) → output (postprocessing and inference results).
- Cross-Framework Support: Highlight the design choice to support both PyTorch and ONNX execution engines.

##### Relevant Technologies and Frameworks
- Programming Language: Python
- Deep Learning Framework: PyTorch (with support for ONNX export and runtime)
- Deployment & Interactive Demo: Gradio for UI demos.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Management & Configuration
    subgraph "Data Management & Configuration"
        C1["Dataset Configs"]:::config
        C2["Detection Configs"]:::config
        C3["Recognition Configs"]:::config
        C4["Data Loaders & Collate"]:::data
    end

    %% Raw Image Input
    RI["Raw Image Input"]:::input

    %% Scene Text Detection Module
    subgraph "Scene Text Detection Module"
        D1["Preprocessing (opendet)"]:::preproc
        D2["Backbone (opendet)"]:::detection
        D3["Neck (opendet)"]:::detection
        D4["Head (opendet)"]:::detection
        D5["Loss (opendet)"]:::training
        D6["Metric (opendet)"]:::training
        D7["Postprocessing (opendet)"]:::postproc
    end

    %% Detected Regions intermediary node
    DR["Detected Text Regions"]:::intermediate

    %% Scene Text Recognition Module
    subgraph "Scene Text Recognition Module"
        R1["Preprocessing (openrec)"]:::preproc
        R2["Encoder (openrec)"]:::recognition
        R3["Decoder (openrec)"]:::recognition
        R4["Transform (openrec)"]:::recognition
        R5["Loss (openrec)"]:::training
        R6["Metric (openrec)"]:::training
        R7["Postprocessing (openrec)"]:::postproc
    end

    %% Final OCR Output
    OCR["Final OCR Output"]:::output

    %% Core Engine & Integration
    subgraph "Core Engine & Integration"
        E1["OpenOCR Engine"]:::engine
        subgraph "Training Engine"
            T1["Trainer (tools/engine)"]:::train
            T2["Config Manager (tools/engine)"]:::train
            T3["Train Detection"]:::train
            T4["Train Recognition"]:::train
        end
        subgraph "Inference Pipelines"
            I3["Inference (Detection)"]:::infer
            I4["Inference (Recognition)"]:::infer
            I5["End-to-End Inference"]:::infer
            I6["Torch Inference"]:::infer
            I7["ONNX Engine"]:::infer
            I8["ONNX Conversion"]:::infer
        end
    end

    %% Utilities & Deployment
    subgraph "Utilities & Deployment"
        U1["Utility & Logging"]:::utils
        U2["Interactive Demo (Gradio)"]:::demo
    end

    %% Data Flow Connections
    RI --> C1
    RI --> C2
    RI --> C3
    RI --> C4
    C4 --> D1
    D1 --> D2
    D2 --> D3
    D3 --> D4
    D4 --> D7
    D7 --> DR
    DR --> R1
    R1 --> R2
    R2 --> R3
    R3 --> R4
    R4 --> R7
    R7 --> OCR

    %% Core Engine Integration Connections (dashed)
    E1 --- D2
    E1 --- R2
    T3 --- D5
    T3 --- D6
    T4 --- R5
    T4 --- R6
    I3 --- D7
    I4 --- R7
    I5 --- OCR
    I6 --- R7
    I7 --- I8

    %% Utilities Connections
    U1 --- E1
    U2 --- E1

    %% Class Definitions for colors and shapes
    classDef input fill:#f4f1de,stroke:#000,stroke-width:1px;
    classDef config fill:#a8dadc,stroke:#457b9d,stroke-width:1px;
    classDef data fill:#f4a261,stroke:#e76f51,stroke-width:1px;
    classDef preproc fill:#ffcad4,stroke:#ff6392,stroke-width:1px;
    classDef detection fill:#bde0fe,stroke:#90caf9,stroke-width:1px;
    classDef recognition fill:#caffbf,stroke:#80ed99,stroke-width:1px;
    classDef postproc fill:#d0f4de,stroke:#32a852,stroke-width:1px;
    classDef training fill:#ffe066,stroke:#f4a261,stroke-width:1px;
    classDef engine fill:#ff9f1c,stroke:#d97706,stroke-width:1px;
    classDef train fill:#f6bd60,stroke:#e59866,stroke-width:1px;
    classDef infer fill:#84a59d,stroke:#3d5a80,stroke-width:1px;
    classDef utils fill:#b8e0d2,stroke:#379683,stroke-width:1px;
    classDef demo fill:#d3c0cd,stroke:#9d4edd,stroke-width:1px;
    classDef intermediate fill:#e0c3fc,stroke:#8e44ad,stroke-width:1px;
    classDef output fill:#c8e6c9,stroke:#2e7d32,stroke-width:1px;

    %% Click Events for Data Management & Configuration
    click C1 "https://github.com/topdu/openocr/tree/main/configs/dataset"
    click C2 "https://github.com/topdu/openocr/tree/main/configs/det"
    click C3 "https://github.com/topdu/openocr/tree/main/configs/rec"
    click C4 "https://github.com/topdu/openocr/blob/main/tools/data/collate_fn.py"

    %% Click Events for Scene Text Detection Module
    click D1 "https://github.com/topdu/openocr/blob/main/opendet/preprocess/crop_resize.py"
    click D2 "https://github.com/topdu/openocr/blob/main/opendet/modeling/backbones/repvit.py"
    click D3 "https://github.com/topdu/openocr/blob/main/opendet/modeling/necks/db_fpn.py"
    click D4 "https://github.com/topdu/openocr/blob/main/opendet/modeling/heads/db_head.py"
    click D5 "https://github.com/topdu/openocr/blob/main/opendet/losses/db_loss.py"
    click D6 "https://github.com/topdu/openocr/blob/main/opendet/metrics/det_metric.py"
    click D7 "https://github.com/topdu/openocr/blob/main/opendet/postprocess/db_postprocess.py"

    %% Click Events for Scene Text Recognition Module
    click R1 "https://github.com/topdu/openocr/blob/main/openrec/preprocess/resize.py"
    click R2 "https://github.com/topdu/openocr/blob/main/openrec/modeling/encoders/svtrv2.py"
    click R3 "https://github.com/topdu/openocr/blob/main/openrec/modeling/decoders/aster_decoder.py"
    click R4 "https://github.com/topdu/openocr/blob/main/openrec/modeling/transforms/aster_tps.py"
    click R5 "https://github.com/topdu/openocr/blob/main/openrec/losses/abinet_loss.py"
    click R6 "https://github.com/topdu/openocr/blob/main/openrec/metrics/rec_metric.py"
    click R7 "https://github.com/topdu/openocr/blob/main/openrec/postprocess/ctc_postprocess.py"

    %% Click Events for Core Engine & Integration
    click E1 "https://github.com/topdu/openocr/blob/main/__init__.py"
    click T1 "https://github.com/topdu/openocr/blob/main/tools/engine/trainer.py"
    click T2 "https://github.com/topdu/openocr/blob/main/tools/engine/config.py"
    click T3 "https://github.com/topdu/openocr/blob/main/tools/train_det.py"
    click T4 "https://github.com/topdu/openocr/blob/main/tools/train_rec.py"
    click I3 "https://github.com/topdu/openocr/blob/main/tools/infer_det.py"
    click I4 "https://github.com/topdu/openocr/blob/main/tools/infer_rec.py"
    click I5 "https://github.com/topdu/openocr/blob/main/tools/infer_e2e.py"
    click I6 "https://github.com/topdu/openocr/blob/main/tools/infer/predict_rec.py"
    click I7 "https://github.com/topdu/openocr/blob/main/tools/infer/onnx_engine.py"
    click I8 "https://github.com/topdu/openocr/blob/main/tools/toonnx.py"

    %% Click Events for Utilities & Deployment
    click U1 "https://github.com/topdu/openocr/blob/main/tools/utils/ckpt.py"
    click U2 "https://github.com/topdu/openocr/blob/main/demo_gradio.py"
```
