Metadata-Version: 2.1
Name: fastplateocr-py
Version: 0.1.1
Summary: Accurate and Efficient General OCR System for License Plates
Home-page: https://github.com/vn-anhnth/FastPlateOCR
Author: vn-anhnth
Author-email: vn-anhnth <anhlone3@gmail.com>
License: Apache License 2.0
Project-URL: Homepage, https://github.com/vn-anhnth/FastPlateOCR
Project-URL: Documentation, https://github.com/vn-anhnth/FastPlateOCR/tree/main/docs
Project-URL: Bug Reports, https://github.com/vn-anhnth/FastPlateOCR/issues
Keywords: ocr,license plate recognition,yolo26,svtr,deep learning,computer vision
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Image Recognition
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: opencv-python
Requires-Dist: pyyaml
Requires-Dist: huggingface-hub
Requires-Dist: torch>=1.7.0
Requires-Dist: torchvision
Requires-Dist: ultralytics

# FastPlateOCR

[![PyPI version](https://badge.fury.io/py/fastplateocr-py.svg)](https://pypi.org/project/fastplateocr-py/)

<p align="center">
  <img src="docs/figures/intro1.png" width="800">
  <br>
  <em>Visual samples of challenging real-world license plates (motion blur, diverse layouts, low light) that FastPlateOCR is built to handle.</em>
</p>

🚀 **FastPlateOCR** is an accurate, extremely fast, and flexible End-to-End License Plate Recognition library.

Unlike traditional ALPR systems that rely on heavy architectures, FastPlateOCR introduces cutting-edge structural improvements designed specifically for real-time edge deployment. Our framework achieves ultra-low inference latency without sacrificing accuracy on blurry or degraded license plates through two major architectural optimizations.

## 🧩 FastPlateOCR Pipeline
The framework is structured as a highly optimized two-stage sequential pipeline:

<p align="center">
  <img src="docs/figures/Hung_0060.png" height="150"> ➔ <b>Improved YOLO26n</b> ➔ <img src="docs/figures/Hung_0060_crop.png" height="150"> ➔ <b>Improved SVTRv2-Tiny</b> ➔ <code>59P289136</code>
</p>
<p align="center"><em>Overview of the proposed highly optimized two-stage ALPR pipeline.</em></p>

### 1. Improved YOLO26n for Fast Detection
We replaced the **Original sequential Bottleneck blocks** in the YOLO26 neck with our novel **5x5 RepMixer blocks**.
By leveraging structural re-parameterization, the model trains with a rich multi-branch topology (capturing complex spatial contexts) but mathematically fuses into a single, highly efficient 5x5 convolution during inference. This completely eliminates memory fragmentation and intermediate read/write operations, drastically reducing Memory Access Cost (MAC).

| Original: Sequential Bottleneck | Proposed: RepMixer (Inference Fused) |
| :---: | :---: |
| <img src="docs/figures/standard_bottleneck.png" width="300"> | <img src="docs/figures/rep_mixer_block_inference_phase.png" width="500"> |

### 2. Improved SVTRv2-Tiny for Lightning-Fast Recognition
To make the SVTRv2 OCR model viable for strict real-time constraints, we applied two key modifications:
* **RepMixer-enhanced Feature Extraction:** We replaced **Original standard convolutions** in the early stages with **RepMixer blocks**. A single fused 5x5 kernel efficiently captures continuous morphological strokes (like loops and lines in characters) without the latency penalty of stacked 3x3 convolutions.

| Original: Standard Convolution | Proposed: RepMixer |
| :---: | :---: |
| <img src="docs/figures/original_conv.png" width="300"> | <img src="docs/figures/repmixer.png" width="500"> |

* **Efficient RCTC Decoder:** We entirely discarded the **Original heavy attention-based RCTC Decoder**. Since license plates have a rigid, horizontally aligned structure, we replaced 2D attention with a simple **Height-wise Average Pooling** operation. This elegantly compresses the 2D features into a 1D sequence, completely bypassing expensive matrix multiplications.

| Original: Heavy RCTC Decoder | Proposed: Efficient RCTC Decoder |
| :---: | :---: |
| <img src="docs/figures/original_rctc_decoder.png" width="400"> | <img src="docs/figures/efficient_rctc_decoder.png" width="400"> |

By integrating these specialized components, **FastPlateOCR** delivers unmatched production-ready performance, processing frames at blazing speeds!

---

## 🛠 Installation

```bash
pip install fastplateocr-py
```

*(Note: To use the auto-download feature for pre-trained weights, please ensure `huggingface_hub` is installed).*

## ⚡ Quick Start

FastPlateOCR automatically downloads the best pre-trained models from our HuggingFace repository the first time you run it. You don't need to manually configure any paths!

### 1. End-to-End Recognition (Detect & Read)

```python
import cv2
from fastplateocr import FastPlateOCR

# Initialize (auto-downloads weights if not found)
model = FastPlateOCR()

# Read the plate
results = model.read('car_image.jpg')

for res in results:
    print(f"Plate Text: {res['text']} | Confidence: {res['score']:.4f}")
    print(f"Bounding Box: {res['box']}")
```

### 2. Flexible API: Detect Only
If you only need to locate the license plates without reading the text:
```python
# Disable the recognition model to save memory
model = FastPlateOCR(use_rec=False)
boxes = model.detect('car_image.jpg')
print("Detected boxes:", boxes)
```

### 3. Flexible API: Recognize Only
If you already have a cropped image of a license plate and just want to read the characters:
```python
# Disable the detection model
model = FastPlateOCR(use_det=False)

crop_img = cv2.imread('cropped_plate.jpg')
text, score = model.recognize(crop_img)
print(f"Text: {text} (Score: {score})")
```

### 4. Using Custom Local Weights
If you have fine-tuned your own models or downloaded the weights locally, you can easily load them:
```python
model = FastPlateOCR(
    det_model_path="/path/to/your/yolo.pt",
    rec_model_path="/path/to/your/svtr.pth"
)
```

## 🏋️ Training & Evaluation

FastPlateOCR provides a complete suite of scripts in the `tools/` directory for dataset preparation, training, evaluation, and inference.

### 0. Model Weights Preparation
Before training or evaluation, download the official pre-trained models from our [HuggingFace Repository](https://huggingface.co/anhone3/FastPlateOCR) and place them in the following structure:
```
FastPlateOCR/
├── pretrained_models/
│   ├── yolo26n_rep_mixer/
│   │   └── best.pt
│   └── svtrv2_tiny_efficient_rctc/
│       └── best.pth
```
You can download them manually or use `wget`:
```bash
wget -O pretrained_models/det/yolo26n_rep_mixer/best.pt https://huggingface.co/anhone3/FastPlateOCR/resolve/main/yolo26n_rep_mixer/best.pt
wget -O pretrained_models/rec/svtrv2_tiny_efficient_rctc/best.pth https://huggingface.co/anhone3/FastPlateOCR/resolve/main/svtrv2_tiny_efficient_rctc/best.pth
```

### 1. Data Preparation (Create LMDB)
Because our LMDB script uses hardcoded paths for simplicity, please open `tools/create_lmdb_dataset.py` and modify the `data_dir` variable in the `__main__` block to match your dataset path before running:
```python
if __name__ == '__main__':
    data_dir = './dataset/rec' # Set your dataset directory

    label_file_list = [
        os.path.join(data_dir, 'train_labels.txt'),
        os.path.join(data_dir, 'val_labels.txt'),
        os.path.join(data_dir, 'test_labels.txt')
    ]
```
After modifying the paths, generate the LMDB:
```bash
python tools/create_lmdb_dataset.py
```

### 2. Training (Det & Rec)
Before training, you must configure the dataset paths, batch sizes, and learning rates in the respective `.yml` files.

**For Detection (`configs/det/yolo26/yolo26n_rep_mixer.yml`):**
```yaml
Train:
  data: './dataset/det/data.yaml' # Point this to your YOLO data.yaml
  epochs: 50
  batch: 256
```

**For Recognition (`configs/rec/svtrv2/svtrv2_tiny_efficient_rctc.yml`):**
```yaml
Train:
  dataset:
    name: RatioDataSetTVResize
    data_dir_list: ['./dataset/rec/lmdb_data/train']

Eval:
  dataset:
    name: RatioDataSetTVResize
    data_dir_list: ['./dataset/rec/lmdb_data/val']
```

Once configured, start training:

> [!TIP]
> **Pre-trained Models (Fine-tuning)**
> By default, the training process will load pre-trained weights to speed up convergence. You can change this path or leave it empty (to train from scratch) by editing the `Global.pretrained_model` field inside the `.yml` config files:
> ```yaml
> Global:
>   pretrained_model: './pretrained_models/det/yolo26n_rep_mixer/best.pt'
> ```

```bash
# Train Detection Model (YOLO26)
python tools/train_det.py -c configs/det/yolo26/yolo26n_rep_mixer.yml

# Train Recognition Model (SVTRv2)
python tools/train_rec.py -c configs/rec/svtrv2/svtrv2_tiny_efficient_rctc.yml
```

### 3. Evaluation (Validation)
Evaluate your trained checkpoints on the validation set using the config files:
```bash
# Evaluate Detection (using default pretrained_model path from config)
python tools/eval_det.py -c configs/det/yolo26/yolo26n_rep_mixer.yml

# Evaluate Recognition (using default pretrained_model path from config)
python tools/eval_rec.py -c configs/rec/svtrv2/svtrv2_tiny_efficient_rctc.yml
```

*(Optional)* You can also override the model path on-the-fly using the `-m` flag to evaluate your own newly trained weights:
```bash
# Evaluate Detection with a custom trained checkpoint
python tools/eval_det.py -c configs/det/yolo26/yolo26n_rep_mixer.yml -m output/det/yolo26n_rep_mixer/train/weights/best.pt

# Evaluate Recognition with a custom trained checkpoint
python tools/eval_rec.py -c configs/rec/svtrv2/svtrv2_tiny_efficient_rctc.yml -m output/rec/svtrv2_tiny_efficient_rctc/train/best.pth
```

### 4. Batch Inference
Test your checkpoints directly on directories of images (supports `--save_log` to save predictions):
```bash
# Infer Detection
python tools/infer_det.py -m pretrained_models/det/yolo26n_rep_mixer/best.pt -d dataset/det/test/images --save_log

# Infer Recognition
python tools/infer_rec.py -m pretrained_models/rec/svtrv2_tiny_efficient_rctc/best.pth -d dataset/rec/test --save_log
```

## 🤝 Acknowledgements

- **OpenOCR**: FastPlateOCR is built upon the robust foundation of [OpenOCR](https://github.com/Topdu/OpenOCR).
- **YOLO26 & SVTRv2**: This work heavily leverages the architectural innovations from **YOLO26** for high-speed object detection and **SVTRv2** for accurate text recognition.
  - Read the [YOLO26 Paper](https://arxiv.org/abs/2606.03748)
  - Read the [SVTRv2 Paper](https://arxiv.org/html/2411.15858v1)

## 📧 Contact
For any questions or issues, please open an issue or contact: `anhlone3@gmail.com`.
