From ea349663fd6e278f7ff5a639bde16f8b0165b1f9 Mon Sep 17 00:00:00 2001
From: "bahawal.baloch" <bahawal.baloch@utopiabrands.com>
Date: Wed, 1 Apr 2026 12:55:22 +0500
Subject: [PATCH] Add README.md for Surveillance Dashboard

- Introduced comprehensive documentation outlining the features, project structure, requirements, setup instructions, and environment variables for the surveillance dashboard application.
- Included details on person detection, group gathering alerts, and GPU requirements for optimal performance.
---
 README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d94de6d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# Surveillance Dashboard
+
+Real-time multi-camera surveillance app with:
+
+- Person detection using Ultralytics YOLO
+- Group gathering detection (2+ people together)
+- Alert when group duration is over 20 seconds
+- Web dashboard with live feed, camera selector, and alert history
+- GPU-only inference (CUDA required)
+
+## Features
+
+- Switch between multiple cameras from UI
+- Draw person boxes and group timer overlays
+- Save alert snapshots to `alerts/`
+- Read camera credentials from `.env`
+
+## Project Structure
+
+- `camera_stream.py` - backend stream processing, detection, and API
+- `templates/dashboard.html` - dashboard UI
+- `requirements.txt` - minimal Python dependencies
+- `.env` - credentials and camera IPs
+- `alerts/` - captured alert images
+
+## Requirements
+
+- Python 3.11+ (3.14 can work but ecosystem support may vary)
+- NVIDIA GPU + CUDA drivers
+- RTSP cameras reachable from this machine
+- Utopia VPN access to reach the camera network
+
+## Setup
+
+Create and activate virtual environment:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Install PyTorch with CUDA (recommended command from PyTorch site):
+
+```powershell
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
+```
+
+Install project dependencies:
+
+```powershell
+pip install -r requirements.txt
+```
+
+## Environment Variables
+
+Create `.env` in project root:
+
+```env
+username=YOUR_CAMERA_USERNAME
+password=YOUR_CAMERA_PASSWORD
+camera_ip_1=192.168.x.x
+camera_ip_2=192.168.x.x
+```
+
+To add more cameras, add more `camera_ip_*` keys and update code list size if needed.
+
+## Run
+
+```powershell
+.\.venv\Scripts\python camera_stream.py
+```
+
+Open:
+
+- http://localhost:5000
+
+## Notes
+
+- App is configured to require CUDA GPU; it will exit if CUDA is not available.
+- Alert condition: at least 2 people in a group for 20+ seconds.
+- Alert snapshots are stored in `alerts/`.
+- Utopia VPN is required to access camera streams from outside the office network.
+- For VPN or camera network access, contact Samad (IT Department, Head Office).