Crowd Safety Intelligence Suite

An end-to-end crowd analysis project that combines:

• People counting from video (YOLO)
• Density heatmap generation (for hotspots/spikes)
• Nearby BLE device analysis on Arduino/ESP32
• FastAPI backend for processing and integration
• Web frontend for simulation and visualization

The goal is to help teams monitor crowd conditions in near real-time and make safer decisions.

---

Why this project matters

This project is useful for places where crowd behavior changes quickly (events, campuses, transport hubs, malls, public spaces).

Key benefits

• Early risk detection
  • Spot crowd-density spikes before they become unsafe.
• Security support
  • Detect unusual surges, persistent clustering, or unexpected activity patterns.
• Operational awareness
  • Understand where people are concentrated and how patterns evolve over time.
• Faster response
  • Improve staffing, queue routing, and emergency handling with data-driven signals.
• Low-friction deployment options
  • Camera-based analytics + BLE environment sensing for complementary insights.

---

Project components

1) pc-model/ — People Counter (YOLO)

Counts people in video streams/files and returns statistics such as:

• frames processed
• max people in frame
• unique tracked people IDs

Optional annotated video output is supported.

2) heatmap-model/ — Crowd Density Heatmap

Builds persistent density maps from detections and renders:

• raw heatmap matrix (.npy)
• colored heatmap image
• overlay heatmap on source image

Useful for identifying repeated congestion zones.

3) ble-model/ — Arduino BLE Nearby Analyzer

ESP32 Arduino sketch that scans nearby BLE advertisers and tracks:

• unique devices seen
• RSSI (signal strength) trends (last/min/max)
• device seen frequency
• strongest currently observed device

This can provide additional environmental context in areas where camera coverage is limited.

4) backend/ — FastAPI Integration Layer

Provides HTTP APIs for processing uploaded media:

• GET /health
• POST /simulation/process

Routes files to either YOLO counting (video) or heatmap generation (image).

5) website/ — Frontend UI

React + TypeScript + Vite interface for interacting with the backend and visual outputs.

---

High-level workflow

1. Input media is uploaded from frontend (video/image).
2. Backend detects mode:
   • video → people counting
   • image → density heatmap
3. Model output is returned as stats and optional output artifacts.
4. BLE analyzer can run separately on ESP32 to provide nearby device analytics.

---

Repository structure

.
├── backend/          # FastAPI service
├── ble-model/        # Arduino BLE analyzer sketch + README
├── heatmap-model/    # Heatmap module + tests + outputs
├── pc-model/         # YOLO people counting scripts + outputs
├── website/          # React/Vite frontend
└── preview_assets/   # sample media/assets

---

Quick start

Backend (Python)

From repository root:

poetry install
poetry run python -m uvicorn backend.app:app --host 0.0.0.0 --port 8000 --reload

Backend docs are in backend/README.md.

Frontend (Web)

From website/:

npm install
npm run dev

(Or use your preferred package manager.)

Arduino BLE model

Open ble-model/ble_model.ino in Arduino IDE, select ESP32 board, upload, and open Serial Monitor at 115200 baud.

Details: ble-model/README.md.

---

Example real-world uses

• Event venues: detect crowding near stages/exits
• Transit stations: identify queue buildup and unusual flow changes
• Campus security: observe spikes around gates/corridors
• Retail/public facilities: improve staffing and crowd routing

---

Notes and limitations

• Vision outputs depend on camera angle, lighting, and occlusion.
• BLE signals are noisy and do not directly equal exact person counts.
• Best results come from combining multiple signals (video + heatmap + BLE context).

---

License

See LICENSE.