Sentry

Automatic Number Plate Recognition

End-to-end AI pipeline for localizing, tracking, and reading Indian license plates. Features a highly optimized two-stage YOLO26 + PaddleOCR architecture, a unified CLI, an interactive launcher, and a premium web dashboard.

Screenshots

Homepage	Processing Logs
Processed CSV	Output Video
Output Image

---

Table of Contents

• Quick Start
• Features
• Architecture
• Installation
• Usage
• Output Files
• Project Structure
• Documentation
• License

---

Quick Start

Prerequisites

• Python 3.9+
• A CUDA-capable GPU (4GB+ VRAM recommended for optimal tracking performance)

Installation & Launch

# 1. Setup the environment
python scripts/setup_local.py

# 2. Activate the virtual environment
venv\Scripts\Activate.ps1  # Windows
source venv/bin/activate   # Linux/macOS

# 3. Launch the interactive menu
python main.py

The interactive menu lets you easily download datasets, train the detector, run video/image inference, or launch the premium web dashboard.

---

Features

🏎️ High-Performance Local Pipeline

• Two-Stage Detection: Uses yolo26s.pt to detect vehicles, and a specialized yolo26s plate localizer for high-precision bounding boxes.
• Robust Tracking: Implements SORT (Simple Online and Realtime Tracking) to maintain vehicle identity across frames.
• Throughput Controls: Prevent FPS collapse in dense traffic with frame spacing, blur gating, and dynamic OCR budgets.

🔍 Advanced Indian Plate OCR

• Pre-processing Ensemble: Enhances contrast, denoises, and applies adaptive thresholding before OCR.
• Temporal Text Stabilization: Uses confidence-weighted voting across rolling track history to lock in the best read.
• Smart Cleanup: Automatically strips IND-prefix noise, applies positional character correction, and validates against Indian vehicle registration regex patterns.

🌐 Premium Glassmorphism Dashboard

• Modern UI: Features Vanta.GLOBE animated backgrounds and a sleek, translucent UI.
• Live Monitoring: Real-time polling of pipeline progress, OCR logs, and backend events.
• Multi-Media Support: Seamlessly handles both static images (.jpg, .png) and dynamic video (.mp4) processing.

---

Architecture

Sentry utilizes a powerful frame-by-frame pipeline engineered for precision and speed.

1. Vehicle Detection      → YOLO26s finds cars, buses, and motorcycles
2. Tracking               → SORT assigns stable IDs to vehicles
3. Plate Localization     → Custom YOLO26s isolates the plate inside the vehicle crop
4. Quality Gating         → Blur rejection, frame gap throttles, and OCR budget caps
5. OCR & Cleanup          → PaddleOCR extraction + positional correction & regex validation
6. Temporal Stabilization → Confidence-weighted voting across vehicle lifetime
7. CSV Logging            → Raw and smoothed trajectory + OCR output emission
8. Polished Render        → High-quality video generation with stabilized tracking

---

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/Sentry.git
   cd Sentry

2. Run the automated setup:

   python scripts/setup_local.py

3. Activate the environment:

   # Windows
   venv\Scripts\Activate.ps1

   # Linux/macOS
   source venv/bin/activate

---

Usage

Interactive Menu

Run python main.py to open the interactive terminal launcher.

CLI Usage

For scripting or advanced use, Sentry provides a unified CLI via cli.py.

# Process a video
python cli.py video --source outputs/input.mp4

# Process an image
python cli.py image --source outputs/photo.jpg

# Start the web app on port 8000
python cli.py web

# Train the plate localizer
python cli.py train

# Download datasets
python cli.py download

---

Output Files

All processing results are neatly organized in the outputs/ directory.

Video Processing (input.mp4):

• input_annotated.mp4: First-pass video with live tracking and OCR boxes.
• input_results_raw.csv: Per-frame raw OCR reads.
• input_results.csv: Smoothed, deduplicated final plate reads per vehicle.
• input_final.mp4: High-quality polished render showing final stabilized plates.

Image Processing (input.jpg):

• input_sentry.jpg: Annotated image with detected plates and OCR text.
• input_results.csv: Cleaned CSV of all plates found in the image.

---

Project Structure

Sentry/
├── main.py                     # Interactive terminal launcher
├── cli.py                      # Unified command-line interface
├── sentry/                     # Core pipeline engine
│   ├── pipeline_core.py        # Pipeline orchestration & memory
│   ├── sort.py                 # SORT tracking implementation
│   └── util.py                 # OCR preprocessing & Indian plate regex
├── webapp/                     # Premium Dashboard backend
│   ├── api.py                  # FastAPI routes
│   ├── jobs.py                 # Async background job manager
│   └── config.py               # Constants and configuration
├── scripts/                    # Automation and MLOps tools
│   ├── train.py                # Plate localizer fine-tuning
│   └── download_dataset.py     # HF/Roboflow dataset fetching
├── docs/                       # Technical documentation
├── outputs/                    # Processed videos, images, and CSVs
└── screenshots/                # Dashboard preview images

---

Documentation

For a deep dive into the underlying architecture, OCR temporal voting mechanisms, and pipeline throughput controls, please refer to the Architecture Documentation.

---

License

MIT License - See LICENSE file for details.