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

> Architecture diagram of the GitHub repository reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics
- Repository: https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics

## Overview

#### 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.

Main entry points: [`notebooks/Phase4.ipynb`](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase4.ipynb) (Phase 4 notebook), [`notebooks/Phase2.ipynb`](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase2.ipynb) (Phase 2 notebook), [`outputs/analytics/tracks_with_zones.json`](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/tracks_with_zones.json) (Zone-enriched tracks), [`notebooks/Phase3.ipynb`](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase3.ipynb) (Phase 3 notebook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_tracking["Tracking"]
  node_phase1["Phase 1 notebook<br/>Jupyter stage<br/>[Phase1.ipynb]"]
  node_yolov8["YOLOv8m person detector<br/>local inference"]
  node_deepsort["DeepSORT tracker<br/>tracking engine"]
  node_raw_tracks["Raw person tracks<br/>track events<br/>[raw_tracks.json]"]
end

subgraph group_zoning["Zone assignment"]
  node_phase2["Phase 2 notebook<br/>Jupyter stage<br/>[Phase2.ipynb]"]
  node_zones["Zone polygons<br/>zone definitions<br/>[zones.json]"]
  node_zone_assignment["Standing-point assignment<br/>spatial rules"]
  node_zoned_tracks["Zone-enriched tracks<br/>audit events"]
end

subgraph group_analytics["Occupancy analytics"]
  node_phase3["Phase 3 notebook<br/>Jupyter stage<br/>[Phase3.ipynb]"]
  node_visit_intervals["Zone visit intervals<br/>analytics state"]
  node_occupancy_log["Frame occupancy log<br/>time-series output"]
  node_zone_summary_csv["Zone summary CSV<br/>analytics output<br/>[zone_analytics.csv]"]
  node_zone_summary_json["Zone summary JSON<br/>analytics output"]
end

subgraph group_rendering["Visualization"]
  node_phase4["Phase 4 notebook<br/>Jupyter stage<br/>[Phase4.ipynb]"]
  node_presentation_outputs["Annotated video and visuals<br/>generated presentation"]
end

node_video_input["Hosted video input<br/>external asset"]
node_python_runtime["Python/Jupyter runtime<br/>runtime dependencies<br/>[requirements.txt]"]

node_video_input -->|"video frames"| node_phase1
node_python_runtime -.->|"runtime"| node_phase1
node_phase1 -->|"frames"| node_yolov8
node_yolov8 -->|"person detections"| node_deepsort
node_deepsort -->|"persistent track IDs"| node_raw_tracks
node_raw_tracks -->|"track observations"| node_phase2
node_phase2 -->|"defines"| node_zones
node_zones -->|"ordered polygons"| node_zone_assignment
node_phase2 -->|"applies"| node_zone_assignment
node_zone_assignment -->|"zone events"| node_zoned_tracks
node_zoned_tracks -->|"observations"| node_phase3
node_phase3 -->|"groups visits"| node_visit_intervals
node_phase3 -->|"writes"| node_occupancy_log
node_visit_intervals -->|"summarizes"| node_zone_summary_csv
node_visit_intervals -->|"summarizes"| node_zone_summary_json
node_zoned_tracks -->|"tracked overlays"| node_phase4
node_occupancy_log -->|"occupancy charts"| node_phase4
node_zone_summary_json -->|"summary visuals"| node_phase4
node_phase4 -->|"renders"| node_presentation_outputs

click node_phase1 "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase1.ipynb"
click node_raw_tracks "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/raw_tracks.json"
click node_phase2 "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase2.ipynb"
click node_zones "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zones.json"
click node_zoned_tracks "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/tracks_with_zones.json"
click node_phase3 "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase3.ipynb"
click node_occupancy_log "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/frame_occupancy_log.csv"
click node_zone_summary_csv "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zone_analytics.csv"
click node_zone_summary_json "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zone_analytics.json"
click node_phase4 "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase4.ipynb"
click node_python_runtime "https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_phase1,node_yolov8,node_deepsort,node_raw_tracks toneBlue
class node_phase2,node_zones,node_zone_assignment,node_zoned_tracks toneAmber
class node_phase3,node_visit_intervals,node_occupancy_log,node_zone_summary_csv,node_zone_summary_json toneMint
class node_phase4,node_presentation_outputs toneRose
class node_video_input,node_python_runtime toneNeutral
```

## Components

### Tracking

- [Phase 1 notebook](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase1.ipynb): Jupyter stage · Runs frame-by-frame detection and persistent tracking. · `notebooks/Phase1.ipynb`
- **YOLOv8m person detector**: local inference · Filters detections to the person class.
- **DeepSORT tracker**: tracking engine · Associates detections into persistent IDs across short occlusions.
- [Raw person tracks](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/raw_tracks.json): track events · `outputs/analytics/raw_tracks.json`

### Zone assignment

- [Phase 2 notebook](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase2.ipynb): Jupyter stage · Assigns tracked people to ordered scene zones. · `notebooks/Phase2.ipynb`
- [Zone polygons](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zones.json): zone definitions · Ordered Entrance, Checkout Area, Aisle, and Exit polygons. · `outputs/analytics/zones.json`
- **Standing-point assignment**: spatial rules · Uses bounding-box bottom center and first-match overlap resolution.
- [Zone-enriched tracks](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/tracks_with_zones.json): audit events · Track-to-zone history for downstream consumers. · `outputs/analytics/tracks_with_zones.json`

### Occupancy analytics

- [Phase 3 notebook](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase3.ipynb): Jupyter stage · Converts zone observations into occupancy and visit metrics. · `notebooks/Phase3.ipynb`
- **Zone visit intervals**: analytics state · Derives entries and dwell; visits under 0.5 seconds are excluded.
- [Frame occupancy log](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/frame_occupancy_log.csv): time-series output · Per-frame occupancy for every zone. · `outputs/analytics/frame_occupancy_log.csv`
- [Zone summary CSV](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zone_analytics.csv): analytics output · Tabular zone-level metrics. · `outputs/analytics/zone_analytics.csv`
- [Zone summary JSON](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/outputs/analytics/zone_analytics.json): analytics output · Structured zone-level metrics including peaks. · `outputs/analytics/zone_analytics.json`

### Visualization

- [Phase 4 notebook](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/notebooks/Phase4.ipynb): Jupyter stage · Builds annotated media and summary visualizations. · `notebooks/Phase4.ipynb`
- **Annotated video and visuals**: generated presentation · Final render paths are external or generated.

### Other components

- **Hosted video input**: external asset · Google Drive availability is required for reruns.
- [Python/Jupyter runtime](https://github.com/reachzaki837/real-time-people-tracking-and-zone-based-occupancy-analytics/blob/main/requirements.txt): runtime dependencies · Uses OpenCV, NumPy, Pandas, SciPy, and Matplotlib alongside inference libraries. · `requirements.txt`

## Connections

- Hosted video input → Phase 1 notebook: video frames
- Python/Jupyter runtime → Phase 1 notebook: runtime
- Phase 1 notebook → YOLOv8m person detector: frames
- YOLOv8m person detector → DeepSORT tracker: person detections
- DeepSORT tracker → Raw person tracks: persistent track IDs
- Raw person tracks → Phase 2 notebook: track observations
- Phase 2 notebook → Zone polygons: defines
- Zone polygons → Standing-point assignment: ordered polygons
- Phase 2 notebook → Standing-point assignment: applies
- Standing-point assignment → Zone-enriched tracks: zone events
- Zone-enriched tracks → Phase 3 notebook: observations
- Phase 3 notebook → Zone visit intervals: groups visits
- Phase 3 notebook → Frame occupancy log: writes
- Zone visit intervals → Zone summary CSV: summarizes
- Zone visit intervals → Zone summary JSON: summarizes
- Zone-enriched tracks → Phase 4 notebook: tracked overlays
- Frame occupancy log → Phase 4 notebook: occupancy charts
- Zone summary JSON → Phase 4 notebook: summary visuals
- Phase 4 notebook → Annotated video and visuals: renders