reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics

Purpose and Execution Model

This is a notebook-driven computer-vision analytics pipeline for tracking people in recorded video and measuring occupancy by scene zone. There is no application server or package entry point: execution proceeds sequentially through notebooks/Phase1.ipynb to notebooks/Phase4.ipynb. Input and final video assets are externally hosted; committed artifacts primarily reside under outputs/analytics/.

1. Detection and Persistent Tracking

notebooks/Phase1.ipynb processes video frames with YOLOv8m, filters to the person class, and passes detections to DeepSORT. DeepSORT assigns persistent IDs using motion/IoU and appearance association, with settings intended to tolerate short occlusions (max_age=30, min_hits=3). This stage is the source of raw per-frame person tracks, materialized as outputs/analytics/raw_tracks.json.

2. Zone Modeling and Assignment

notebooks/Phase2.ipynb establishes four manually drawn, ordered polygons: Entrance, Checkout Area, Aisle, and Exit. Zone definitions are persisted in outputs/analytics/zones.json. For each tracked bounding box, the pipeline uses its bottom-center point as the standing-position proxy; if polygons overlap at a boundary, ordered first-match evaluation provides a single deterministic assignment. Enriched track events are written to outputs/analytics/tracks_with_zones.json.

3. Occupancy and Visit Analytics

notebooks/Phase3.ipynb transforms zone-assigned tracks into temporal metrics. Its main state boundary is between individual track observations and zone-level visit intervals: it counts current occupants per frame, identifies unique track IDs and entries per zone, derives dwell durations, and excludes visits shorter than 0.5 seconds. It also calculates peak occupancy and its timestamp.

4. Structured Output Contract

The pipeline’s principal machine-readable outputs are:

• outputs/analytics/frame_occupancy_log.csv: frame/time-series occupancy for all zones.

• outputs/analytics/zone_analytics.csv: tabular zone summary.

• outputs/analytics/zone_analytics.json: equivalent structured summary.

• outputs/analytics/tracks_with_zones.json: audit-level track-to-zone history.

These files form the handoff boundary for downstream reporting or graph/planning consumers without requiring video inference to be rerun.

5. Visualization and Final Rendering

notebooks/Phase4.ipynb produces presentation outputs from tracked and analyzed data, including annotated frames/video and summary visualizations. Existing diagnostic/report artifacts are kept alongside data in outputs/analytics/, including outputs/analytics/zone_analytics.json and outputs/analytics/frame_occupancy_log.csv. Final videos are described as external/generated output paths rather than being present in the supplied tree.

Runtime and External Dependencies

The runtime is Python/Jupyter, with dependencies declared in requirements.txt. Core services are local inference libraries rather than remote APIs: Ultralytics YOLOv8 for detection, deep_sort_realtime for tracking, OpenCV for video/frame handling, and NumPy/Pandas/SciPy/Matplotlib for data processing and visualization. Video inputs and model/video distribution rely on the linked Google Drive, making external asset availability a prerequisite for a clean rerun.