# genggode/libocr architecture

> Architecture diagram of the GitHub repository genggode/libocr, 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/genggode/libocr
- Repository: https://github.com/genggode/libocr

## Overview

##### Project type and purpose
- This is a **C++ library** (no GUI) exposing a simple C‐style API for OCR.
- Purpose: provide offline, embedded OCR via ONNX models without heavy dependencies.

##### File structure
- Top‐level:
- `include/libocr` – public headers
- `source/` – core implementation, subdivided into:
‑ `image/` (image loading/manipulation)
‑ `onnx/text_detector` (ONNX‑based text detection)
‑ `onnx/text_recognizer` (ONNX‑based text recognition)
‑ `ocr/` (low‑level OCR functions)
‑ `ocr_manager/` (high‑level orchestration)
- `resource/` – embedded ONNX models, dictionaries, embedding utilities
- `test/` – example clients demonstrating dynamic/static linkage

##### README for insights
- Libraries used: ONNX Runtime, optionally OpenCV (found via CMake scripts).
- Build via CMake + vcpkg, outputs `libocr.dll`/`.lib`.
- Public API: `libocr::ocr_file(...)`, `libocr::free_char(...)`.

##### Main components & interactions
a. Client Application
- Calls `ocr_file()` → receives raw image path.
b. Image Module
- Loads image (OpenCV or custom loader).
c. OCR Manager
- Coordinates detection & recognition stages.
d. ONNX Subsystems
- **Text Detector**: runs `model_det.onnx` to find text regions.
- **Text Recognizer**: runs `model_rec.onnx` + `model_rec_dict.txt` to decode text.
e. Resource Embedding
- Embeds model files into binary via `resource/embed_resource.cpp`.
f. ONNX Runtime & Other Dependencies
- Linked via CMake (`find_onnxruntime.cmake`), possibly OpenCV (`find_opencv.cmake`).

##### Architectural patterns & principles
- **Modular layering**:
- Public API layer (`libocr.h`)
- Core orchestration (`ocr_manager`)
- Specialized modules (image, detector, recognizer)
- **Dependency inversion**: clients depend on API, not implementation.
- **Embedded resources**: static bundling of models for zero‐setup usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Test Clients
    subgraph "Client Applications" 
        direction TB
        Client_Dyn["Example Dynamic Link"]:::client
        Client_Run["Example Runtime Link"]:::client
        Client_Static["Example Static Link"]:::client
    end

    %% Public API Layer
    subgraph "Public API Layer"
        direction TB
        PublicAPI["libocr::ocr_file(), free_char()"]:::internal
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        ImageLoader["Image Module"]:::internal
        OCRManager["OCR Manager"]:::internal
        OCRCore["OCR Core Functions"]:::internal
    end

    %% ONNX Subsystems
    subgraph "ONNX Subsystems"
        direction TB
        Detector["Text Detector"]:::internal
        Recognizer["Text Recognizer"]:::internal
        ONNXCommon["ONNX Common Definitions"]:::internal
    end

    %% Resources
    subgraph "Embedded Resources"
        direction TB
        ResourceEmbed["Resource Embedder"]:::resource
        Models["Embedded Models & Dict"]:::resource
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        ONNXRT["ONNX Runtime"]:::external
        OpenCV["OpenCV (optional)"]:::external
    end

    %% Data Flow
    Client_Dyn -->|"calls ocr_file()"| PublicAPI
    Client_Run -->|"calls ocr_file()"| PublicAPI
    Client_Static -->|"calls ocr_file()"| PublicAPI

    PublicAPI -->|"path to image"| ImageLoader
    ImageLoader -->|"raw image bytes"| OCRManager
    OCRManager -->|"detect()"| Detector
    Detector -->|"ONNX tensor"| ONNXRT
    ONNXRT -->|"regions"| Detector
    Detector -->|"regions"| OCRManager

    OCRManager -->|"recognize()"| Recognizer
    Recognizer -->|"ONNX tensor"| ONNXRT
    ONNXRT -->|"raw text codes"| Recognizer
    Recognizer -->|"UTF8 text"| OCRManager

    OCRManager -->|"result struct"| PublicAPI
    PublicAPI -->|"UTF8 text"| Client_Dyn
    PublicAPI -->|"UTF8 text"| Client_Run
    PublicAPI -->|"UTF8 text"| Client_Static

    %% Resource interactions
    OCRManager ---|"loads models"| ResourceEmbed
    OCRManager ---|"reads dict"| ResourceEmbed
    ResourceEmbed -->|"embedded bytes"| Models
    Models -->|"model_det.onnx, model_rec.onnx, dict"| OCRManager

    %% Other dependencies
    ImageLoader -->|"uses"| OpenCV

    %% Click Events
    click PublicAPI "https://github.com/genggode/libocr/blob/dev/include/libocr/libocr.h"
    click PublicAPI "https://github.com/genggode/libocr/blob/dev/source/libocr.cpp"
    click PublicAPI "https://github.com/genggode/libocr/blob/dev/source/libocr.def"

    click ImageLoader "https://github.com/genggode/libocr/blob/dev/source/image/image.h"
    click ImageLoader "https://github.com/genggode/libocr/blob/dev/source/image/image.cpp"

    click OCRManager "https://github.com/genggode/libocr/blob/dev/source/ocr_manager/ocr_manager.h"
    click OCRManager "https://github.com/genggode/libocr/blob/dev/source/ocr_manager/ocr_manager.cpp"

    click OCRCore "https://github.com/genggode/libocr/blob/dev/source/ocr/ocr.h"
    click OCRCore "https://github.com/genggode/libocr/blob/dev/source/ocr/ocr.cpp"

    click Detector "https://github.com/genggode/libocr/blob/dev/source/onnx/text_detector/text_detector.h"
    click Detector "https://github.com/genggode/libocr/blob/dev/source/onnx/text_detector/text_detector.cpp"
    click Detector "https://github.com/genggode/libocr/blob/dev/source/onnx/text_detector/clipper.hpp"
    click Detector "https://github.com/genggode/libocr/blob/dev/source/onnx/text_detector/clipper.cpp"

    click Recognizer "https://github.com/genggode/libocr/blob/dev/source/onnx/text_recognizer/text_recognizer.h"
    click Recognizer "https://github.com/genggode/libocr/blob/dev/source/onnx/text_recognizer/text_recognizer.cpp"

    click ONNXCommon "https://github.com/genggode/libocr/blob/dev/source/onnx/onnx.h"

    click ResourceEmbed "https://github.com/genggode/libocr/blob/dev/resource/embed_resource.h"
    click ResourceEmbed "https://github.com/genggode/libocr/blob/dev/resource/embed_resource.cpp"
    click ResourceEmbed "https://github.com/genggode/libocr/blob/dev/resource/embed.list"
    click ResourceEmbed "https://github.com/genggode/libocr/blob/dev/resource/embed_utils/main.cpp"

    click Models "https://github.com/genggode/libocr/blob/dev/resource/model_det.onnx"
    click Models "https://github.com/genggode/libocr/blob/dev/resource/model_rec.onnx"
    click Models "https://github.com/genggode/libocr/blob/dev/resource/model_rec_dict.txt"

    click ONNXRT "https://github.com/genggode/libocr/blob/dev/cmake/find_onnxruntime.cmake"
    click OpenCV "https://github.com/genggode/libocr/blob/dev/cmake/find_opencv.cmake"

    click Client_Dyn "https://github.com/genggode/libocr/blob/dev/test/example_dynamiclink_loadtime/example_dynamiclink_loadtime.cpp"
    click Client_Run "https://github.com/genggode/libocr/blob/dev/test/example_dynamiclink_runtime/example_dynamiclink_runtime.cpp"
    click Client_Static "https://github.com/genggode/libocr/blob/dev/test/example_staticlink_compiletime/example_staticlink_compiletime.cpp"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#00008B,stroke-width:1px
    classDef external fill:#90EE90,stroke:#006400,stroke-width:1px
    classDef resource fill:#FFA500,stroke:#FF8C00,stroke-width:1px
    classDef client fill:#D8BFD8,stroke:#800080,stroke-width:1px
```
