SentinelCV is a state-of-the-art, real-time security surveillance pipeline. It ingests live video feeds, detects objects and people with ultra-high precision, tracks them across frames, and triggers automated alerts based on highly customizable polygon zones (e.g., restricted entry, loitering, abandoned objects).
It was built from the ground up to offer a sleek, professional-grade Next.js frontend dashboard paired with a blazingly fast Python/FastAPI backend powered by Ultralytics YOLOv8 and ByteTrack.
A dynamic, real-time monitoring dashboard that displays the live camera feed, active zones, and system status. It tracks all objects and dynamically displays their class labels and confidence scores.
A comprehensive alerts history dashboard that tracks every single breach, loitering incident, and abandoned object. It saves snapshots of the exact moment the breach occurred.
A fully interactive tool to visually draw and map out surveillance zones directly on top of your camera feed.
Easily switch between live webcams, RTSP streams, and uploaded video files.
SentinelCV is built on a decoupled, microservice-inspired architecture to ensure that heavy AI inference does not bottleneck the UI or API layers.
- Video Source: Asynchronous frame ingestion from Webcams, MP4 files, or RTSP streams to prevent I/O blocking.
- Detector & Tracker (YOLOv8 + ByteTrack): Detects all objects in the frame (cars, animals, people) but intelligently filters the ByteTrack persistent ID assignments and alerts to specific threat vectors (people, backpacks, suitcases).
- Zone Engine: A heavily optimized OpenCV ray-casting/polygon math logic engine that calculates centroids of bounding boxes to determine if a target has breached a "Restricted Zone", surpassed a threshold timer in a "Loitering Zone", or left a bag in an "Abandoned Object Zone".
- Alert Manager: Deduplicates noisy alerts, captures high-res frame snapshots, saves records to SQLite, and broadcasts real-time alerts via WebSockets.
- FastAPI Server: Serves the MJPEG stream to the frontend with zero-latency, handles REST endpoints for zone configurations, and manages the WebSocket connections.
- Next.js & React: A highly responsive, single-page application built on Next.js.
- Modern Aesthetics: Designed with a "cyberpunk/security-terminal" aesthetic using Tailwind CSS. It features glassmorphism, glowing accents, and high-contrast color palettes specifically designed for low-light surveillance monitoring rooms.
- Interactive Canvas: The Zone Calibration tool uses the native HTML5
<canvas>API to allow users to click and draw complex polygons, which are serialized and sent to the backend.
- AI/ML: Ultralytics YOLOv8, ByteTrack, PyTorch
- Computer Vision: OpenCV (cv2)
- Backend: Python, FastAPI, Uvicorn, SQLite, WebSockets
- Frontend: TypeScript, Next.js, React, Tailwind CSS, Lucide Icons
Make sure you have conda installed and Node.js (v18+) for the frontend.
- Create and activate the conda environment:
conda create -n cv python=3.10 conda activate cv
- Install the required Python packages:
pip install -r requirements.txt
- Run the backend server:
uvicorn backend.main:app --host 0.0.0.0 --port 8000
(Note: The YOLOv8 weights will automatically download on the first run).
- Open a new terminal and navigate to the
frontenddirectory:cd frontend - Install the Node modules:
npm install
- Start the Next.js development server:
npm run dev
- Open http://localhost:3000 in your browser.
SentinelCV was built with the goal of creating a completely automated, AI-driven perimeter security tool that rivals enterprise software.
The core challenge was optimizing the tracking logic. Initially, naive object detection would trigger false positives on every frame. By implementing ByteTrack for persistent ID assignment and a cooldown-based Alert Manager, the system accurately filters out noise and only alerts on genuine threats. The visual identity of the frontend was carefully curated to look exactly like modern command-center dashboards, prioritizing data density and immediate visual feedback via red/amber/green status indicators.