# jaidedai/easyocr architecture

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

- Interactive diagram: https://gitdiagram.com/jaidedai/easyocr
- Repository: https://github.com/jaidedai/easyocr

## Overview

1. **Repository purpose**
   EasyOCR is a Python OCR library with a two-stage inference pipeline: text detection finds candidate text regions in an image, and text recognition decodes the text inside each region. The public API is centered around `easyocr.Reader`, with both a Python API and a small CLI wrapper.

2. **Top-level package boundary**
   The `easyocr/` package is the runtime library shipped to users. It contains the inference pipeline, model definitions, image preprocessing, language resources, and command-line entrypoint. The `trainer/` subtree is a separate training stack for building or fine-tuning detector and recognizer models, and `unit_test/` is an isolated validation harness.

3. **Inference orchestration**
   `easyocr/easyocr.py`, `easyocr/model/model.py`, and `easyocr/model/constructor.py` are the main runtime coordination layer. They load models, prepare language settings, route images through detection and recognition, and return results in the public output format: bounding boxes, text strings, and confidence scores.

4. **Detection subsystem**
   Detection is implemented as a pluggable stage. The repo includes the original CRAFT-based path in `easyocr/craft.py`, `easyocr/craft_utils.py`, and `easyocr/detection.py`, plus a DBNet path in `easyocr/detection_db.py` and `easyocr/DBNet/`. This is the geometric stage that turns an image into text boxes or polygons before recognition happens.

5. **DBNet implementation boundary**
   `easyocr/DBNet/` is a self-contained detector package with its own backbones, decoders, loss functions, and model wrapper. It supports architectures such as MobileNetV3 and ResNet backbones, and includes deformable convolution / pooling native ops under `easyocr/DBNet/assets/ops/dcn/`, which are compiled extensions used to accelerate detection models.

6. **Recognition subsystem**
   Recognition is modeled as a CRNN-style stack in `easyocr/model/` and the training-oriented analogs under `trainer/modules/`. The recognition pipeline is built from feature extraction, sequence modeling, and CTC-style decoding. The runtime model files are split into reusable modules such as `vgg_model.py` and `modules.py`, with `recognition.py` acting as the higher-level recognition flow.

7. **Language assets and decoding vocabulary**
   The `easyocr/character/` and `easyocr/dict/` directories provide per-language character sets and dictionaries. These resources are part of the model boundary: they constrain the recognizer’s output space and support language-specific decoding across 80+ scripts. This is a key architectural dependency because language selection directly affects model loading and post-processing.

8. **Image preprocessing and post-processing**
   `easyocr/imgproc.py`, `easyocr/utils.py`, and `easyocr/craft_utils.py` handle image normalization, resizing, coordinate transforms, box grouping, and text region cleanup. These utilities sit between the raw input image and the model outputs, and they are essential for converting detector output into stable text crops for recognition.

9. **CLI and packaging surface**
   `easyocr/cli.py` exposes the command-line interface, while `setup.py`, `setup.cfg`, `MANIFEST.in`, and `Dockerfile` define distribution and containerization boundaries. The README indicates that model weights are downloaded automatically from the project’s model hub unless preinstalled locally, so runtime includes an external model-download dependency.

10. **Training stack**
   The `trainer/` directory is a separate but related system for detector and recognizer training. It includes dataset loaders, augmentation, losses, metrics, experiment configs, distributed training scripts, and saved-model folders. `trainer/craft/` is a dedicated CRAFT training environment, while `trainer/train.py` and `trainer/test.py` cover the recognition training workflow.

11. **Data generation and pseudo-labeling**
   Within `trainer/craft/data/` and `trainer/craft/data/pseudo_label/`, the repository includes synthetic data and pseudo-label generation tools such as box enlargement, Gaussian map creation, watershed segmentation, and character box generation. This indicates an offline data-engineering pipeline used to produce detector supervision rather than relying only on manually annotated boxes.

12. **External and native dependencies**
   The project is built on PyTorch, with OpenCV-style image handling implied by the API and preprocessing code. The deformable convolution/pooling operators are native C++/CUDA extensions, so some models require compilation at install time or during setup. The release README also references Hugging Face Spaces and the project’s own model hub as external distribution surfaces, but these are not part of core inference.

13. **Testing and validation**
   `unit_test/` contains a packaged test fixture, demo notebooks, and a runnable test harness. This sits outside the main inference path and is mainly used to verify packaging, model loading, and output consistency across environments.

14. **Architectural summary**
   In diagram terms, the core flow is: input image → preprocessing → text detection → crop/box extraction → text recognition → decoded string/confidence output. Surrounding that core are language resource files, downloadable weights, optional CLI entrypoints, and a separate training subsystem for detector/recognizer development.

Main entry points: [`easyocr/easyocr.py`](https://github.com/jaidedai/easyocr/blob/master/easyocr/easyocr.py) (EasyOCR API), [`easyocr/DBNet/model/model.py`](https://github.com/jaidedai/easyocr/blob/master/easyocr/DBNet/model/model.py) (DBNet Model), [`easyocr/model/model.py`](https://github.com/jaidedai/easyocr/blob/master/easyocr/model/model.py) (Model Loader), [`easyocr/detection.py`](https://github.com/jaidedai/easyocr/blob/master/easyocr/detection.py) (CRAFT Detect)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime OCR"]
  node_easyocr_api["EasyOCR API<br/>inference facade<br/>[easyocr.py]"]
  node_easyocr_cli["CLI<br/>command wrapper<br/>[cli.py]"]
  node_runtime_models["Model Loader<br/>runtime models<br/>[model.py]"]
  node_imgproc["Image Proc<br/>preprocess<br/>[imgproc.py]"]
  node_utils["Utils<br/>[utils.py]"]
  node_characters["Characters<br/>language vocab"]
  node_dictionaries["Dictionaries<br/>language lexicon"]
end

subgraph group_detector["Detection"]
  node_craft_detect["CRAFT Detect<br/>detector path<br/>[detection.py]"]
  node_craft_core["CRAFT Core<br/>craft detector<br/>[craft.py]"]
  node_craft_utils["CRAFT Utils<br/>geometry utils<br/>[craft_utils.py]"]
  node_dbnet_detect["DBNet Detect<br/>detector path<br/>[detection_db.py]"]
end

subgraph group_recognizer["Recognition"]
  node_recognition_flow["Recognition Flow<br/>decode pipeline<br/>[recognition.py]"]
  node_recognition_modules["CRNN Modules<br/>recognizer blocks<br/>[modules.py]"]
  node_vgg_model["VGG Model<br/>feature extractor<br/>[vgg_model.py]"]
end

subgraph group_dbnet["DBNet"]
  node_dbnet_model["DBNet Model<br/>segmentation detector<br/>[model.py]"]
  node_dbnet_constructor["DBNet Builder<br/>model assembly<br/>[constructor.py]"]
  node_dbnet_backbones["Backbones"]
  node_dbnet_decoders["Decoders<br/>loss/heads"]
  node_dbnet_ops["DCN Ops<br/>native extension"]
end

subgraph group_training["Training"]
  node_trainer_recog["Trainer Core<br/>recognizer training"]
  node_trainer_dataset["Datasets<br/>data pipeline<br/>[dataset.py]"]
  node_trainer_entry["Train Scripts<br/>training entrypoints<br/>[train.py]"]
  node_trainer_craft["CRAFT Trainer<br/>detector training"]
end

subgraph group_validation["Validation"]
  node_unit_tests["Unit Harness<br/>validation suite"]
end

node_easyocr_api -->|"preprocesses"| node_imgproc
node_easyocr_api -->|"detects via"| node_craft_detect
node_easyocr_api -->|"detects via"| node_dbnet_detect
node_easyocr_api -->|"recognizes"| node_recognition_flow
node_easyocr_api -->|"loads"| node_runtime_models
node_easyocr_api -->|"uses"| node_characters
node_easyocr_api -->|"uses"| node_dictionaries
node_easyocr_cli -->|"wraps"| node_easyocr_api
node_runtime_models -->|"assembles"| node_recognition_modules
node_runtime_models -->|"uses"| node_vgg_model
node_recognition_flow -->|"uses"| node_recognition_modules
node_recognition_flow -->|"postprocesses"| node_utils
node_craft_detect -->|"drives"| node_craft_core
node_craft_detect -->|"postprocesses"| node_craft_utils
node_dbnet_detect -->|"runs"| node_dbnet_model
node_dbnet_model -->|"builds from"| node_dbnet_constructor
node_dbnet_model -->|"uses"| node_dbnet_backbones
node_dbnet_model -->|"uses"| node_dbnet_decoders
node_dbnet_model -->|"accelerates with"| node_dbnet_ops
node_trainer_entry -->|"feeds"| node_trainer_dataset
node_trainer_entry -->|"trains"| node_trainer_recog
node_trainer_craft -->|"mirrors"| node_craft_core
node_trainer_craft -->|"uses"| node_trainer_dataset
node_unit_tests -->|"validates"| node_easyocr_api

click node_easyocr_api "https://github.com/jaidedai/easyocr/blob/master/easyocr/easyocr.py"
click node_easyocr_cli "https://github.com/jaidedai/easyocr/blob/master/easyocr/cli.py"
click node_runtime_models "https://github.com/jaidedai/easyocr/blob/master/easyocr/model/model.py"
click node_recognition_flow "https://github.com/jaidedai/easyocr/blob/master/easyocr/recognition.py"
click node_recognition_modules "https://github.com/jaidedai/easyocr/blob/master/easyocr/model/modules.py"
click node_vgg_model "https://github.com/jaidedai/easyocr/blob/master/easyocr/model/vgg_model.py"
click node_imgproc "https://github.com/jaidedai/easyocr/blob/master/easyocr/imgproc.py"
click node_utils "https://github.com/jaidedai/easyocr/blob/master/easyocr/utils.py"
click node_craft_detect "https://github.com/jaidedai/easyocr/blob/master/easyocr/detection.py"
click node_craft_core "https://github.com/jaidedai/easyocr/blob/master/easyocr/craft.py"
click node_craft_utils "https://github.com/jaidedai/easyocr/blob/master/easyocr/craft_utils.py"
click node_dbnet_detect "https://github.com/jaidedai/easyocr/blob/master/easyocr/detection_db.py"
click node_dbnet_model "https://github.com/jaidedai/easyocr/blob/master/easyocr/DBNet/model/model.py"
click node_dbnet_constructor "https://github.com/jaidedai/easyocr/blob/master/easyocr/DBNet/model/constructor.py"
click node_dbnet_backbones "https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/backbones"
click node_dbnet_decoders "https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/decoders"
click node_dbnet_ops "https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/assets/ops/dcn"
click node_characters "https://github.com/jaidedai/easyocr/tree/master/easyocr/character"
click node_dictionaries "https://github.com/jaidedai/easyocr/tree/master/easyocr/dict"
click node_trainer_recog "https://github.com/jaidedai/easyocr/tree/master/trainer/modules"
click node_trainer_dataset "https://github.com/jaidedai/easyocr/blob/master/trainer/dataset.py"
click node_trainer_entry "https://github.com/jaidedai/easyocr/blob/master/trainer/train.py"
click node_trainer_craft "https://github.com/jaidedai/easyocr/tree/master/trainer/craft"
click node_unit_tests "https://github.com/jaidedai/easyocr/tree/master/unit_test"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_easyocr_api,node_easyocr_cli,node_runtime_models,node_imgproc,node_utils,node_characters,node_dictionaries toneBlue
class node_craft_detect,node_craft_core,node_craft_utils,node_dbnet_detect toneAmber
class node_recognition_flow,node_recognition_modules,node_vgg_model toneMint
class node_dbnet_model,node_dbnet_constructor,node_dbnet_backbones,node_dbnet_decoders,node_dbnet_ops toneRose
class node_trainer_recog,node_trainer_dataset,node_trainer_entry,node_trainer_craft toneIndigo
class node_unit_tests toneTeal
```

## Components

### Runtime OCR

User-facing inference library and CLI.

- [EasyOCR API](https://github.com/jaidedai/easyocr/blob/master/easyocr/easyocr.py): inference facade · Public Reader-oriented entrypoint and orchestration layer. · `easyocr/easyocr.py`
- [CLI](https://github.com/jaidedai/easyocr/blob/master/easyocr/cli.py): command wrapper · Small command-line interface for running OCR from the shell. · `easyocr/cli.py`
- [Model Loader](https://github.com/jaidedai/easyocr/blob/master/easyocr/model/model.py): runtime models · Loads detector and recognizer weights and constructs runtime models. · `easyocr/model/model.py`
- [Image Proc](https://github.com/jaidedai/easyocr/blob/master/easyocr/imgproc.py): preprocess · Image normalization, resizing, and tensor preparation. · `easyocr/imgproc.py`
- [Utils](https://github.com/jaidedai/easyocr/blob/master/easyocr/utils.py): postprocess utils · Coordinate transforms, box grouping, and runtime helpers. · `easyocr/utils.py`
- [Characters](https://github.com/jaidedai/easyocr/tree/master/easyocr/character): language vocab · Per-language character sets that constrain recognition output. · `easyocr/character`
- [Dictionaries](https://github.com/jaidedai/easyocr/tree/master/easyocr/dict): language lexicon · Per-language word lists and decoding dictionaries. · `easyocr/dict`

### Detection

Text region detection implementations and geometry utilities.

- [CRAFT Detect](https://github.com/jaidedai/easyocr/blob/master/easyocr/detection.py): detector path · Original CRAFT-based detection entrypoint and box geometry. · `easyocr/detection.py`
- [CRAFT Core](https://github.com/jaidedai/easyocr/blob/master/easyocr/craft.py): craft detector · CRAFT model and geometry utilities used by the detector path. · `easyocr/craft.py`
- [CRAFT Utils](https://github.com/jaidedai/easyocr/blob/master/easyocr/craft_utils.py): geometry utils · Box grouping, heatmap handling, and text region cleanup. · `easyocr/craft_utils.py`
- [DBNet Detect](https://github.com/jaidedai/easyocr/blob/master/easyocr/detection_db.py): detector path · DBNet-based detection entrypoint used as an alternative detector. · `easyocr/detection_db.py`

### Recognition

Sequence recognition and decoding components.

- [Recognition Flow](https://github.com/jaidedai/easyocr/blob/master/easyocr/recognition.py): decode pipeline · High-level recognition orchestration from cropped text to decoded output. · `easyocr/recognition.py`
- [CRNN Modules](https://github.com/jaidedai/easyocr/blob/master/easyocr/model/modules.py): recognizer blocks · Feature extraction, sequence modeling, and prediction blocks. · `easyocr/model/modules.py`
- [VGG Model](https://github.com/jaidedai/easyocr/blob/master/easyocr/model/vgg_model.py): feature extractor · Shared CNN backbone used by recognition models. · `easyocr/model/vgg_model.py`

### DBNet

Standalone DBNet detector stack and native ops.

- [DBNet Model](https://github.com/jaidedai/easyocr/blob/master/easyocr/DBNet/model/model.py): segmentation detector · DBNet model wrapper and detector construction logic. · `easyocr/DBNet/model/model.py`
- [DBNet Builder](https://github.com/jaidedai/easyocr/blob/master/easyocr/DBNet/model/constructor.py): model assembly · Builds DBNet detector instances from configuration and weights. · `easyocr/DBNet/model/constructor.py`
- [Backbones](https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/backbones): cnn backbones · MobileNetV3 and ResNet feature extractors for DBNet. · `easyocr/DBNet/backbones`
- [Decoders](https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/decoders): loss/heads · Segmentation heads and losses used by DBNet detection. · `easyocr/DBNet/decoders`
- [DCN Ops](https://github.com/jaidedai/easyocr/tree/master/easyocr/DBNet/assets/ops/dcn): native extension · Compiled deformable convolution and pooling operators. · `easyocr/DBNet/assets/ops/dcn`

### Training

Separate detector and recognizer training stack.

- [Trainer Core](https://github.com/jaidedai/easyocr/tree/master/trainer/modules): recognizer training · Training-side analogs for recognition feature extraction and prediction. · `trainer/modules`
- [Datasets](https://github.com/jaidedai/easyocr/blob/master/trainer/dataset.py): data pipeline · Training data loading and dataset composition. · `trainer/dataset.py`
- [Train Scripts](https://github.com/jaidedai/easyocr/blob/master/trainer/train.py): training entrypoints · Main training and evaluation programs for the trainer stack. · `trainer/train.py`
- [CRAFT Trainer](https://github.com/jaidedai/easyocr/tree/master/trainer/craft): detector training · Dedicated CRAFT training environment with its own data and scripts. · `trainer/craft`

### Validation

Packaged test harness and fixtures.

- [Unit Harness](https://github.com/jaidedai/easyocr/tree/master/unit_test): validation suite · Packaged validation harness and fixtures for runtime verification. · `unit_test`

## Connections

- EasyOCR API → Image Proc: preprocesses · Normalizes and prepares input images.
- EasyOCR API → CRAFT Detect: detects via · Runs text region detection before recognition.
- EasyOCR API → DBNet Detect: detects via · Optional DBNet detection path.
- EasyOCR API → Recognition Flow: recognizes · Crops detected regions and decodes text.
- EasyOCR API → Model Loader: loads · Coordinates model loading and runtime construction.
- EasyOCR API → Characters: uses · Selects language-specific character sets.
- EasyOCR API → Dictionaries: uses · Applies language dictionaries during decoding.
- CLI → EasyOCR API: wraps · CLI entrypoint delegates to the public API.
- Model Loader → CRNN Modules: assembles · Builds recognition-side model components.
- Model Loader → VGG Model: uses · Uses the shared CNN backbone for recognition.
- Recognition Flow → CRNN Modules: uses · Runs feature extraction, sequence modeling, and prediction.
- Recognition Flow → Utils: postprocesses · Uses coordinate and output helpers during decoding.
- CRAFT Detect → CRAFT Core: drives · Uses CRAFT model logic for text detection.
- CRAFT Detect → CRAFT Utils: postprocesses · Groups and cleans detected text regions.
- DBNet Detect → DBNet Model: runs · Invokes the DBNet detector wrapper.
- DBNet Model → DBNet Builder: builds from · Constructs detector instances from config.
- DBNet Model → Backbones: uses · Uses MobileNetV3/ResNet feature extractors.
- DBNet Model → Decoders: uses · Uses segmentation heads and detection losses.
- DBNet Model → DCN Ops: accelerates with · Relies on native deformable convolution/pooling ops.
- Train Scripts → Datasets: feeds · Training scripts consume dataset loaders.
- Train Scripts → Trainer Core: trains · Main trainer stack builds recognition models.
- CRAFT Trainer → CRAFT Core: mirrors · Separate CRAFT training environment around detector core.
- CRAFT Trainer → Datasets: uses · Training data pipeline supports detector learning.
- Unit Harness → EasyOCR API: validates · Exercises runtime loading and output consistency.
