Metadata-Version: 2.4
Name: robovai-ocr
Version: 1.0.7
Summary: Enterprise Computer Vision & OCR Core for Parking Management Systems (ALPR, Face Verification, National ID OCR)
Home-page: https://msalatmani.org
Author: Mohamed Shaban (محمد شعبان العتماني)
Author-email: "Mohamed Shaban (محمد شعبان العتماني)" <msalatmani@gmail.com>
License: MIT
Project-URL: Homepage, https://msalatmani.org
Project-URL: Company, https://robovai.tech
Project-URL: Source, https://github.com/m0shaban
Project-URL: Documentation, https://msalatmani.org/#capabilities
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Multimedia :: Graphics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: opencv-python>=4.8.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: ultralytics>=8.0.0
Requires-Dist: easyocr>=1.7.0
Requires-Dist: pillow>=9.5.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: uvicorn>=0.22.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: httpx>=0.24.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: python-multipart>=0.0.6
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# RoboVAI OCR Enterprise Core 🚗🆔👤

[![PyPI Version](https://img.shields.io/pypi/v/robovai-ocr.svg?color=blue)](https://pypi.org/project/robovai-ocr/)
[![Python Version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11%20%7C%203.12-blue)](https://pypi.org/project/robovai-ocr/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://img.shields.io/badge/tests-15%2F15%20PASSING-brightgreen.svg)](https://github.com/m0shaban)

**RoboVAI OCR Enterprise Core** (`robovai-ocr` v1.0.5) is a production-grade Computer Vision & OCR system developed by **Mohamed Shaban (محمد شعبان العتماني)** — Founder & AI Architect at [RoboVAI](https://msalatmani.org).

It provides specialized AI engines tailored for **Smart Parking Management Systems, Barrier Gate Controls, and Identity Verification Systems**:
1. **ALPREngine**: Automatic License Plate Recognition for Egyptian, Arabic & International plates.
2. **IDEngine**: Egyptian National ID & Driver License Deep Learning Engine (14-digit National ID decoding, full name, address, DOB, governorate, photo crop).
3. **FaceEngine**: Facial recognition, driver authorization matching & registration database.

---

## 📊 Benchmark Performance Results (2,085 Dataset Images)

Benchmark evaluated on full enterprise dataset (`robovai_plates` 2,085 images):

| Metric | Benchmark Result | Performance Status |
| :--- | :--- | :--- |
| **Total Images Processed** | **2,085 Images** | 100% Full Dataset Benchmark |
| **Plate Detection Rate** | **2,084 / 2,085 (99.95%)** | 🎯 Near-Perfect Detection |
| **Valid OCR Extraction Rate** | **1,825 / 2,084 (87.57%)** | ⚡ High Reliability OCR |
| **Avg Detection Confidence** | **91.95%** | 🔥 YOLOv8/v11 Fine-Tuned Bounding Box |
| **Avg OCR Confidence** | **50.11%** | 🔍 Split-Region Whitelisted Character Normalization |
| **Passing Unit Tests** | **15 / 15 (100% PASS)** | ✅ Production Verified |

---

## 🌟 Key Architectural Features

- **Multi-Scale TTA Inference**: Automatically applies 1.5x upscaling on low-resolution or distant frames with adaptive fallback confidence (`conf = 0.15`).
- **Split-Region Whitelisted OCR**: Separates Egyptian plates into **Left Region** (Digits 0-9) and **Right Region** (Arabic Letters) to eliminate letter-digit confusion.
- **National ID Decoder**: Automatically decodes 14-digit Egyptian National IDs into Date of Birth, Gender, Century, and Governorate of origin.
- **High-Throughput Async Pipeline**: Decouples fast YOLO object tracking from heavier OCR background execution to maintain real-time RTSP/Webcam stream processing.
- **Green Box Visualizer**: Renders high-visibility green bounding box `(0, 255, 0)` with text label banners for live video feeds and Web Dashboards.

---

## 🚀 Quick Start & Installation

### Option 1: Install from PyPI
```bash
pip install --upgrade robovai-ocr
```

### Option 2: Install from Source (Development Mode)
```bash
git clone https://github.com/m0shaban/robovai_ocr_system.git
cd robovai_ocr_system
pip install -e .
```

---

## 💻 Python SDK Usage Example

```python
from robovai_ocr import RoboVAIEngine, Config

# 1. Initialize RoboVAI Engine
engine = RoboVAIEngine(device="cpu") # Or "cuda:0" for GPU

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

# 3. Egyptian National ID & Driver License 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"
# }

# 4. Driver Face Verification
face_result = engine.verify_driver_face("driver.jpg", db_path="data/driver_faces")
print(face_result)
```

---

## 📡 REST API & Web Dashboard Server

Launch the FastAPI Server & Control Center Dashboard on **Port 8500**:

```bash
# Launch server via CLI
robovai-server --host 0.0.0.0 --port 8500
```

- **Interactive Control Center Dashboard**: `http://localhost:8500/`
- **OpenAPI / Swagger Documentation**: `http://localhost:8500/docs`

### Key REST & WebSocket Endpoints

- `POST /api/v1/alpr`: License plate detection & OCR extraction.
- `POST /api/v1/id-card`: Egyptian National ID & Driver License OCR.
- `POST /api/v1/face`: Driver facial recognition & database matching.
- `POST /api/v1/pipeline`: Asynchronous background queue processing.
- `WS /ws/stream`: Real-time WebSocket RTSP stream processing.

---

## 💻 Command Line Interface (CLI)

```bash
# Process single license plate
robovai-cli alpr --image path/to/car.jpg

# Process Egyptian National ID card
robovai-cli idcard --image path/to/id.jpg
```

---

## 👨‍💻 Author & Enterprise Contact

- **Author**: Mohamed Shaban (محمد شعبان العتماني)
- **Role**: AI Architect & Founder of RoboVAI
- **Personal Website**: [https://msalatmani.org](https://msalatmani.org)
- **Company Website**: [https://robovai.tech](https://robovai.tech)
- **PyPI Package**: [https://pypi.org/project/robovai-ocr/](https://pypi.org/project/robovai-ocr/)
- **License**: MIT License
