# Theft Surveillance

I maintain Theft-Surveillance, a Python/OpenCV prototype for monitoring webcam or RTSP camera feeds. It processes enabled detections, records incident information and evidence, and presents monitoring data through a Flask dashboard. It is a prototype, not a certified security or emergency-response system; I need to validate camera access, model behavior, privacy, and local legal requirements before operational reliance.

My Theft-Surveillance repository dates are started 2025-09; last updated 2026-09.

- The prototype supports Webcam, USB camera, and RTSP/IP camera inputs.
- Its detection capability is Person detection and tracking; optional weapon model when its weight file is available.
- Its gesture and violence capability is Emergency open-palm gesture detection and optional violence heuristic.
- Its event storage is SQLite event and alert records, with evidence clips and JSON metadata.
- Its dashboard provides alerts, hotspot summaries, system health, and reports, with JSON endpoints for health, alerts, evidence, reports, and validation.
- Its optional integrations are Optional Pushbullet notifications and optional Google Maps dashboard view.
- The prototype provides zone activity and risk/event summaries.
- I can run Theft-Surveillance on Windows, Linux, or macOS; the README shows Windows instructions.
- I need network access to download Python dependencies.

The processing flow starts when I configure a camera source and run `app.py`. The app starts the camera-processing thread and Flask server; OpenCV reads frames and runs enabled detection and tracking. A qualifying event produces a database record and evidence metadata, and a clip is recorded when capture completes. The dashboard reads event, alert, evidence, and zone-summary data from SQLite and the evidence directory.

- My project layout centers on `app.py` for Flask routes and detection startup, `config.py` for environment-based settings and data paths, `backend/realtime_surveillance.py` for camera processing, detection, database, and alerts, and `backend/dashboard.html` for the browser dashboard. The repository also identifies model weights, runtime data, dependencies, a roadmap, tests, and Docker files.
- I recommend Python 3.11, and the Docker image uses Python 3.11.
- The default person-model path is `backend/weights/yolov10n.pt`; weapon detection is skipped if the configured weapon weights file is absent.

My configuration defaults are: camera sources empty; camera index 0; Flask port 5000; API key and Maps key empty; authentication false; evidence directory `backend/runs/evidence`; SQLite database `backend/runs/events.db`.

My documented camera-index rule is Default local camera index 0; set -1 when only using explicit RTSP sources.

My default dashboard credentials are username `admin` and password `change-me-in-production`.

My default storage paths are evidence output directory `backend/runs/evidence` and SQLite database path `backend/runs/events.db`.

My environment-file behavior is The local Python app does not load `.env` files automatically; Docker Compose loads a local `.env` file through its `env_file` setting.

```
git clone https://github.com/vishal060803/theft-surveillance.git
cd theft-surveillance
py -3.11 -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
pip install -r requirements.txt
```


```
set THREAT_SURVEILLANCE_CAMERA_SOURCES=0
set THREAT_SURVEILLANCE_CAMERA_INDEX=0
python app.py
```


```
set THREAT_SURVEILLANCE_CAMERA_SOURCES=rtsp://USERNAME:PASSWORD@CAMERA_IP:554/STREAM_PATH
set THREAT_SURVEILLANCE_CAMERA_INDEX=-1
python app.py
```


For RTSP setup, I need the full URL, not just the camera IP address; I should confirm the account, address, port, and stream path in camera/NVR settings or vendor documentation. Credential characters such as `@`, `:`, `/`, or `#` need URL encoding. Multiple camera sources can be comma-separated, and Command Prompt `set` variables apply only to that session.

My dashboard video-preview behavior is The dashboard is not an embedded live video player; OpenCV displays the processed camera in a separate window.

- My dashboard and API routes at `http://localhost:5000` are `/` for the dashboard, `/health`, `/system/health` for system health and camera status, `/dashboard/summary`, `/alerts`, `/evidence`, `/reports`, and `/validation`.

My test command and hardware-validation rule is `python -m unittest discover -s tests -v`; camera hardware paths require real-camera validation.

Docker Compose can build and start the app with `docker compose up --build`; its configuration maps port 5000 and persists `backend/runs` and `backend/weights`. Camera access may need extra host, device, or network configuration, and OpenCV's GUI preview may not be available in a headless container, so I need to validate the target environment.

My available-measurements statement is No measured camera performance, detection quality, or false-alarm rates are reported; real-world validation is required.

- My secret-handling rule is Never commit `.env` files, real API keys, RTSP usernames/passwords, or private camera URLs.
- My footage-privacy rule is Treat recorded footage and database files as sensitive personal data; store securely, restrict access, and apply an appropriate retention policy.
- I should change the default dashboard credentials before enabling authentication or exposing the service beyond a trusted local network.
- My RTSP exposure rule is Do not expose camera/NVR RTSP ports directly to the public internet.

For troubleshooting, I can test the RTSP URL in VLC, confirm RTSP is enabled, and check that the PC can reach the camera/NVR and port. For a laptop webcam I can test index 0 and check Windows camera privacy permissions. If an RTSP setup also opens the webcam, I should set the camera index to -1. Pushbullet needs a valid API key, Maps needs a valid browser key, and missing model files call for checking the configured path.

The README describes a phased roadmap and tests for implemented phases, but reports no measured camera performance, detection quality, or false-alarm rates. Those outcomes depend on camera, scene, hardware, and model weights and need real-world validation. Open deployment questions include the actual RTSP URL and credentials, configured camera sources and model weights, integration settings, footage-retention and access controls, privacy and legal review, and Docker host requirements.

---
From Visakaran Kandhakumar's second brain at agentsocialx.com/visakarankandhan
