How jaidedai/easyocr works
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.py EasyOCR API · model/model.py DBNet Model · model/model.py Model Loader · detection.py CRAFT Detect
Components 24
Runtime OCR
User-facing inference library and CLI.
- EasyOCR API · Public Reader-oriented entrypoint and orchestration layer.
easyocr/easyocr.py - CLI · Small command-line interface for running OCR from the shell.
easyocr/cli.py - Model Loader · Loads detector and recognizer weights and constructs runtime models.
easyocr/model/model.py - Image Proc · Image normalization, resizing, and tensor preparation.
easyocr/imgproc.py - Utils · Coordinate transforms, box grouping, and runtime helpers.
easyocr/utils.py - Characters · Per-language character sets that constrain recognition output.
easyocr/character - Dictionaries · Per-language word lists and decoding dictionaries.
easyocr/dict
Detection
Text region detection implementations and geometry utilities.
- CRAFT Detect · Original CRAFT-based detection entrypoint and box geometry.
easyocr/detection.py - CRAFT Core · CRAFT model and geometry utilities used by the detector path.
easyocr/craft.py - CRAFT Utils · Box grouping, heatmap handling, and text region cleanup.
easyocr/craft_utils.py - DBNet Detect · DBNet-based detection entrypoint used as an alternative detector.
easyocr/detection_db.py
Recognition
Sequence recognition and decoding components.
- Recognition Flow · High-level recognition orchestration from cropped text to decoded output.
easyocr/recognition.py - CRNN Modules · Feature extraction, sequence modeling, and prediction blocks.
easyocr/model/modules.py - VGG Model · Shared CNN backbone used by recognition models.
easyocr/model/vgg_model.py
DBNet
Standalone DBNet detector stack and native ops.
- DBNet Model · DBNet model wrapper and detector construction logic.
easyocr/DBNet/model/model.py - DBNet Builder · Builds DBNet detector instances from configuration and weights.
easyocr/DBNet/model/constructor.py - Backbones · MobileNetV3 and ResNet feature extractors for DBNet.
easyocr/DBNet/backbones - Decoders · Segmentation heads and losses used by DBNet detection.
easyocr/DBNet/decoders - DCN Ops · Compiled deformable convolution and pooling operators.
easyocr/DBNet/assets/ops/dcn
Training
Separate detector and recognizer training stack.
- Trainer Core · Training-side analogs for recognition feature extraction and prediction.
trainer/modules - Datasets · Training data loading and dataset composition.
trainer/dataset.py - Train Scripts · Main training and evaluation programs for the trainer stack.
trainer/train.py - CRAFT Trainer · Dedicated CRAFT training environment with its own data and scripts.
trainer/craft
Validation
Packaged test harness and fixtures.
- Unit Harness · Packaged validation harness and fixtures for runtime verification.
unit_test
Connections 24
- 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.