README.md

---
title: Plate Detector
emoji: 🏃
colorFrom: gray
colorTo: gray
sdk: gradio
sdk_version: 6.14.0
python_version: '3.10'
app_file: app.py
pinned: false
license: mit
---

# 🚗 Vehicle Intelligence System

Advanced license plate detection, OCR, and natural language database querying system with security hardening.

## 🎯 Features

### Detection Pipeline
- 🎥 **YOLO Plate Detection** - Real-time license plate localization
- 🔤 **PaddleOCR** - High-accuracy OCR for plate text extraction
- 🚗 **Vehicle Classification** - Classify vehicle types (car, truck, bike, etc.)
- 🛡️ **Confidence Scoring** - All detections include confidence metrics

### Database & Analytics
- 📊 **Supabase PostgreSQL** - Robust cloud database with automatic backups
- 🔍 **NLP-to-SQL** - Ask questions in natural language, AI converts to SQL
- 🛡️ **SQL Validation** - Prevents injection attacks and dangerous queries
- ⚡ **Optimized Indexes** - Fast queries with proper database indexing
- 📈 **Real-time Analytics** - Dashboard with state distribution, hourly traffic, suspicious vehicles

### Security Features
- ✅ **SQL Injection Prevention** - Whitelist/blacklist keyword validation
- 🔒 **Read-Only Queries** - Only SELECT queries allowed
- 📝 **Query History** - Track all database queries for audit
- 🔐 **State Extraction** - Automatically extract state codes from license plates

## 📂 Modular Architecture

```
plate-detector/
├── app.py              # Main Gradio UI with 3 tabs
├── detector.py         # YOLO, OCR, vehicle classification
├── database.py         # SQL validation, LLM, database operations
├── requirements.txt    # Python dependencies
└── .env               # Environment variables (Supabase, HF token)
```

### Files Explained

**app.py** - Simplified UI layer
- Detection tab: Upload images, detect plates
- Database Query tab: NLP-to-SQL search with example queries
- Analytics tab: Real-time dashboard with metrics

**detector.py** - Computer Vision Module
- License plate detection using YOLO
- OCR using PaddleOCR
- Vehicle classification (10 types)
- State code extraction (TN, KA, KL, etc.)
- Image preprocessing and augmentation

**database.py** - Data & Security Layer
- SQL validation (blocks DELETE, UPDATE, INSERT, DROP)
- SQLCoder LLM integration for NLP-to-SQL
- Database initialization with improved schema
- Automatic index creation for performance
- Query history tracking
- Analytics functions (suspicious vehicles, hourly traffic, etc.)

## 🚀 Deployment

### Environment Variables

Create `.env` file with:

```
DATABASE_URL=postgresql://user:password@host:5432/postgres
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Run Locally

```bash
pip install -r requirements.txt
python app.py
```

Visit: http://localhost:7860

### Deploy on Hugging Face Spaces

1. Push code to HF Spaces repository
2. Add secrets in Settings:
   - `DATABASE_URL` - Supabase connection string
   - `HF_TOKEN` - Hugging Face API token

## 🛡️ Security Measures

### SQL Validation

```python
ALLOWED_KEYWORDS = ["SELECT", "FROM", "WHERE", "COUNT", ...]
BLOCKED_KEYWORDS = ["DROP", "DELETE", "UPDATE", "INSERT", ...]

# Only SELECT queries allowed
# Blocks all dangerous operations
```

### Database Schema

```sql
CREATE TABLE vehicle_logs (
    id BIGSERIAL PRIMARY KEY,
    timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    plate TEXT,
    state TEXT,
    vehicle_type TEXT,
    vehicle_conf FLOAT,
    camera_id TEXT,
    location TEXT,
    image_url TEXT,
    date DATE,
    hour INTEGER,
    day TEXT
);
```

### Indexes for Performance

```sql
CREATE INDEX idx_plate ON vehicle_logs(plate);
CREATE INDEX idx_state ON vehicle_logs(state);
CREATE INDEX idx_vehicle_type ON vehicle_logs(vehicle_type);
CREATE INDEX idx_timestamp ON vehicle_logs(timestamp);
CREATE INDEX idx_date ON vehicle_logs(date);
```

## 🎯 Example Queries

- "How many cars today?"
- "Show all trucks"
- "Count bikes"
- "Show TN vehicles"
- "Show vehicles after 6pm"
- "List latest 10 detections"
- "Count vehicles by type"
- "Show high confidence detections"
- "List all unique plates"
- "Show suspicious vehicles"

## 📊 Analytics Dashboard

- **Vehicles by State** - Distribution of detections across states
- **Traffic by Hour** - Hourly traffic patterns
- **Top Plates** - Most frequently detected license plates
- **Suspicious Vehicles** - High-frequency detections (>20 times)

## 🔮 Future Improvements

- [ ] Vector search for similar plates
- [ ] Async database queries for better performance
- [ ] Image storage and retrieval
- [ ] Camera tracking and geolocation
- [ ] Result caching with Redis
- [ ] FastAPI backend separation
- [ ] React dashboard frontend

## 📦 Dependencies

- ultralytics - YOLO detection
- paddleocr - OCR
- transformers - Vehicle classification
- sqlalchemy - Database ORM
- huggingface-hub - LLM inference
- gradio - Web UI
- opencv - Image processing

## 📄 License

MIT License - See LICENSE file

## 🤝 Contributing

Contributions welcome! Please submit pull requests or issues.

---

**Live Demo:** https://huggingface.co/spaces/BARATH0070/plate-detector