CrowdAI

Real-time crowd density and flow analytics engine. Detects people in a video feed, maps their positions onto a perspective-corrected ground plane, clusters them to classify congestion severity, and tracks frame-to-frame movement to flag dangerous crowd flow — triggering live audio alerts when conditions escalate.

How it works

1. Detection — YOLOv8 (yolov8n.pt) locates people in each frame. If YOLO inference isn't available (e.g. no GPU, model fails to load), the system falls back to OpenCV's HOG person detector so the pipeline degrades gracefully instead of stopping.
2. Ground-plane correction — Detected bounding-box positions are transformed from raw camera-perspective pixel coordinates into a top-down ground-plane representation, so density is measured by real spatial proximity rather than distorted camera perspective.
3. Density clustering — The ground-plane points are fed into a DBSCAN clustering model, grouping people into crowd clusters and scoring overall congestion as LOW, MEDIUM, or HIGH.
4. Flow tracking — Frame-to-frame centroid movement is tracked to compute crowd flow velocity, surfacing fast-moving or erratic crowd behavior (e.g. a sudden surge or crush) in addition to static density.
5. Alerts — Live audio alerts fire automatically as congestion or flow-velocity thresholds are crossed, giving an operator an immediate, hands-free signal without needing to watch the feed constantly.

Project structure

CrowdAI/
├── audio/     # Alert sound playback / audio feedback
├── core/      # Detection, ground-plane transform, clustering, and flow-tracking logic
├── ui/        # Live dashboard / overlay rendering
├── utils/     # Shared helper functions
├── main.py    # Entry point — runs the full detection → analytics → alert pipeline
└── yolov8n.pt # Pretrained YOLOv8 nano weights used for person detection

Requirements

• Python 3.9+
• Ultralytics YOLO (YOLOv8 / YOLO11)
• OpenCV (opencv-python)
• scikit-learn (DBSCAN)
• NumPy

Install dependencies:

pip install ultralytics opencv-python scikit-learn numpy

Usage

python main.py

By default the pipeline runs against the configured video source (webcam or file) using the bundled yolov8n.pt weights. Press q to exit the live view.

Configuration

• Camera / ground-plane calibration — The perspective-correction step assumes a fixed camera position. If you're pointing this at a different scene, you'll need to recalibrate the ground-plane reference points for accurate density readings.
• Congestion thresholds — LOW / MEDIUM / HIGH boundaries and flow-velocity alert thresholds are tunable to match the scale and layout of the space being monitored.
• Model — Swap yolov8n.pt for a larger YOLOv8/YOLO11 variant if you need higher detection accuracy and have the compute budget for it.

Notes

This is an independent/research project intended as a proof of concept for crowd-safety monitoring — not a production-hardened deployment. Detection accuracy, calibration, and alert thresholds should be validated against your specific camera setup and use case before relying on it for real safety decisions.

License

TBD