Metadata-Version: 2.4
Name: robovai_ocr
Version: 1.0.0
Summary: Enterprise Computer Vision & OCR Core for Parking Management Systems
Author: RoboVAI Engineering
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: requires-python

# RoboVAI OCR & CV Core Engine 🚗🆔👤

**RoboVAI OCR** is a production-grade, modular Computer Vision and OCR system designed specifically for **Parking Management Software Integration**. It provides state-of-the-art AI capabilities for:
1. **Automatic License Plate Recognition (ALPR)** (Egyptian, Arabic & International plates).
2. **Driver Face Verification** (Face detection & authorization matching).
3. **National ID & Driver License OCR** (Structured 14-digit Egyptian ID parsing, DOB, governorate, expiry date, full name extraction).

---

## 🌟 Key Features

- **Multi-Engine Hybrid OCR**: Dual EasyOCR + PaddleOCR fallback with adaptive image preprocessing (CLAHE contrast enhancement, bilateral filtering, noise reduction, deskewing).
- **High-Throughput Async Pipeline**: Separates fast YOLO object tracking from heavier OCR background execution to process high-concurrency streams without dropped frames.
- **Tracking Memory Cache**: Caches OCR results per vehicle `track_id` to eliminate redundant slow OCR computations for identical cars in frame.
- **Egyptian & Arabic Plate Parser**: Converts raw OCR outputs into formatted plate numbers and letters (e.g., `س ط أ 1 2 3`).
- **National ID Auto-Decoder**: Decodes Egyptian 14-digit national IDs directly into date of birth, gender, century, and governorate of origin.
- **Flexible Integration**: Use directly as a **Python SDK** or deploy as a **FastAPI REST API / WebSocket Stream Server** with Webhooks for automated parking barrier gate control.

---

## 🚀 Quick Start & Installation

### Option 1: Python SDK Installation
```bash
cd robovai_ocr
pip install -e .
```

### Option 2: Run via CLI
```bash
# Process a single plate image
robovai-cli alpr --image path/to/car.jpg

# Process a national ID card
robovai-cli idcard --image path/to/id.jpg

# Launch API & WebSocket server
robovai-server --host 0.0.0.0 --port 8000
```

---

## 💻 Python SDK Usage Example

```python
from robovai_ocr import RoboVAIEngine, Config

# Initialize engine
engine = RoboVAIEngine(device="cuda:0")

# 1. License Plate Recognition
plate_result = engine.read_license_plate("car_image.jpg")
print(plate_result)
# Output: {"plate_number": "س ط أ 1 2 3", "confidence": 0.96, "bbox": [120, 300, 450, 420]}

# 2. National ID Card Extraction
id_result = engine.extract_national_id("id_card.jpg")
print(id_result)
# Output: {
#   "national_id": "29901010100123",
#   "full_name": "احمد محمد علي",
#   "dob": "1999-01-01",
#   "gender": "Male",
#   "governorate": "Cairo"
# }

# 3. Face Matching
face_result = engine.verify_driver_face("driver_photo.jpg", db_path="data/drivers")
print(face_result)
# Output: {"match": True, "driver_id": "DRV-1029", "confidence": 0.94}
```

---

## 📡 REST API & WebSockets

Start the server:
```bash
robovai-server --port 8000
```
Open interactive docs at `http://localhost:8000/docs`.

### REST Endpoints
- `POST /api/v1/alpr`: License plate detection & OCR.
- `POST /api/v1/face`: Driver face verification.
- `POST /api/v1/id-card`: National ID & driver license OCR.
- `POST /api/v1/pipeline`: High-throughput background queue processing.
- `WS /ws/stream`: Real-time RTSP/Webcam stream processing.

---

## 🏋️ Fine-Tuning & Training

To train YOLO on a custom parking plate or ID card dataset:
```bash
python training/train_yolo.py --data training/dataset_config.yaml --epochs 100
```
