TheftGuard AI is an advanced, enterprise-grade video surveillance and anti-theft security solution designed for retail spaces, supermarkets, and smart facilities. It utilizes cutting-edge Computer Vision, real-time Pose Estimation, Object Detection, and Facial Recognition algorithms to detect shoplifting, loitering, restricted area intrusions, and fighting.
The system leverages optimized, multi-threaded pipelines to analyze concurrent camera feeds (local webcams or RTSP network cameras) synchronously, triggering instant browser-synthesized audio sirens and sending remote alerts via Email and Telegram.
Live Demo: theft-detection-dusky.vercel.app
- Asynchronous Frame Reading: Captures frames independently via high-performance python threading (
ThreadedCamera), avoiding sequential frame capture lag or UI freezes. - Robust Multi-Camera Tracking: Dynamically resolves tracker ID conflicts across multiple feeds simultaneously by isolating states uniquely using camera-to-person composites
(camera_id, track_id).
- HTML5 Canvas Drawing Tool: Draw precise security boundaries (Polygons) overlaying live webcam/RTSP feeds directly inside a glassmorphic dashboard modal.
- Resolution-Agnostic Scaling: Autonomously maps client-side mouse vectors into exact
1280x720surveillance matrix coordinates, preventing scaling discrepancies across different screen resolutions. - Camera-Specific Storage: Camera definitions and their respective ROI coordinate lists are saved persistently inside
cameras.json.
- Item Concealment Logic: Recognizes when a person picks up a target retail item and monitors hand-to-pocket/bag gestures, flagging potential concealment attempts.
- Loitering Detection: Evaluates how long a person dwells within a specific ROI. If loitering exceeds the configurable threshold, an alarm is triggered.
- Zone Intrusion Alerts: Instantly sounds sirens if human wrists cross into high-security zones (e.g., cash register areas, restricted aisles).
- Postural Suspicion: Detects unusual physical behavior such as sudden bending down in low-visibility aisles.
- Activity Heatmaps: Localized heatmap accumulators aggregate and visually plot customer traffic patterns individually for each camera stream.
- Face ID Classification: A dedicated, premium Face Management panel to upload portrait photos, register new faces, and assign categorizations:
- Blacklist: Automatically triggers high-priority security alarms and records evidence.
- VIP Whitelist: Identifies trusted staff, loyal clients, or VIP visitors, showing a green greeting badge.
- Instant Face Database Deletion: One-click instant SQLite deletion with automatic memory synchronization.
- Web Audio API Integration: Avoids brittle MP3 loading loops by synthesizing realistic, sweeping emergency sirens directly in the browser's audio processor in real-time when alarms fire.
- High-Priority Cooldowns: Protects users from noise fatigue by enforcing a 3-second smart alarm cooldown period.
- Telegram & SMTP Setup: Instantly broadcast alerts and snapshots via Telegram chat integrations and automated Email notifications.
- Performance Telemetry: Displays dynamic CPU usage and Memory (RAM) virtual bars mapped directly from backend psutil resources.
- Weekly Trends: Integrates custom, sleek Recharts data visualizations highlighting security events categorized by "Suspicious Behavior" and "Reviewed/False Alarms".
- Advanced Filtering & CSV Export: Search historical logs by ID, message, or camera, filter by event categories, and download filtered alerts into a clean Excel/CSV file with a single click.
- Backend Engine: Python 3.10+, FastAPI (Asynchronous API endpoints & WebSockets), OpenCV (Multi-threaded streaming), Ultralytics YOLOv8 (Stand-alone Pose & Object model detection),
face_recognition(Dlib-based CNN face encodings), SQLite3 (Database storage for logs & face matrices). - Frontend Dashboard: Next.js 14+ (App Router), React 18, Tailwind CSS, Recharts (Modern chart libraries), Lucide React (Fluent vector icons), HSL Custom Themes (Harmonious Glassmorphic Dark UI).
- Python 3.9 - 3.11
- Node.js (LTS version)
- CUDA Enabled NVIDIA GPU (Highly recommended for fluid real-time inference)
Clone the repository and install the Python dependencies:
git clone https://github.com/vahapogut/Theft-Detection.git
cd Theft-Detection
pip install -r requirements.txtWindows Note: If
pythonis not in your PATH, use thepylauncher instead:py -m pip install -r requirements.txt
The system uses two pre-trained YOLOv8 models which are included in the repository:
yolov8n.pt— Object detection (person tracking, item monitoring)yolov8n-pose.pt— Pose estimation (posture analysis, gesture detection)
Note: If you have a custom pre-trained theft detection model (shoplifting.pt), place it in the root directory. The system will automatically detect it and upgrade from default pose algorithms to the specialized neural net.
| Package | Purpose | Status When Missing |
|---|---|---|
face_recognition |
Face ID & blacklist/whitelist matching | Face recognition panel disabled gracefully |
psutil |
Real-time CPU/RAM monitoring | Falls back to simulated system metrics |
Windows users: Installing
face_recognitionon Windows requires Visual Studio Build Tools and CMake (for thedlibdependency). The system runs fine without it — only the face recognition tab will show no results. See face_recognition Windows install guide for help.
Install node packages:
cd dashboard
npm installRun the setup tests to confirm everything is working:
py test_setup.py # Tests OpenCV + YOLO object detection
py test_pose.py # Tests YOLO pose model loadingLaunch both the FastAPI service and the Next.js development server concurrently with a single click:
start_system.batThe launcher will:
- Check and auto-install dashboard npm dependencies if missing
- Start the Python/FastAPI backend on
http://localhost:8000 - Start the Next.js dashboard on
http://localhost:3000 - Open the dashboard in your default browser
1. Start the API Server & Inference Loop:
py backend.py(The server will boot on http://localhost:8000 — Swagger docs at http://localhost:8000/docs)
2. Start the Frontend Dashboard:
cd dashboard
npm run dev(The panel will be served on http://localhost:3000)
3. Optional Standalone OpenCV Window Demo:
py standalone_demo.pyUse the Python launcher (py) instead. It's included with the official Python installer from python.org:
py backend.pyThis is expected on Windows unless you've manually installed dlib. The system logs a warning and disables face recognition — all other features (object detection, pose estimation, loitering, ROI, alerts) continue working normally.
- Ensure no other application is using your webcam (Zoom, Teams, etc.)
- Try changing the camera source from
0to1in the Camera Setup panel - For RTSP streams, verify the URL format:
rtsp://username:password@ip:port/path
- Confirm the backend is running (
http://localhost:8000/docsshould load) - Check Windows Firewall isn't blocking port 8000
- Verify
NEXT_PUBLIC_API_URL=http://127.0.0.1:8000exists indashboard/.env.local
- Fork this repository.
- Create your feature branch (
git checkout -b feature/CoolFeature). - Commit your upgrades (
git commit -m 'feat: add cool feature'). - Push to your branch (
git push origin feature/CoolFeature). - Open a Pull Request.
Distributed under the MIT License. See LICENSE for more information.
Project Maintainer & Developer: Abdulvahap Öğüt
GitHub Repository: vahapogut/Theft-Detection