Metadata-Version: 2.1
Name: fastplateocr-py
Version: 0.1.0
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: 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

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

This project is deeply inspired by and based on the excellent [OpenOCR](https://github.com/Top-Fighter/OpenOCR) framework. We have specialized and optimized the architecture specifically for reading License Plates in challenging real-world conditions.

By integrating the lightweight object detection prowess of **YOLO26 (with RepMixer Bottlenecks)** and the lightning-fast text recognition of **SVTRv2**, FastPlateOCR delivers production-ready performance!

---

## 🛠 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:
```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
python tools/eval_det.py -c configs/det/yolo26/yolo26n_rep_mixer.yml

# Evaluate Recognition
python tools/eval_rec.py -c configs/rec/svtrv2/svtrv2_tiny_efficient_rctc.yml
```

### 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`.
