# lewjiayi/crowd-analysis architecture

> Architecture diagram of the GitHub repository lewjiayi/crowd-analysis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lewjiayi/crowd-analysis
- Repository: https://github.com/lewjiayi/crowd-analysis

## Overview

Crowd-Analysis processes CCTV or video frames into person detections, persistent tracks, crowd-rule checks, and recorded movement/crowd data. Separate scripts turn those records into abnormal-energy summaries, heatmaps and optical flow, and time-series crowd summaries. The sampled source establishes the main processing and Deep SORT relationships; downstream report links are documented in the README, while some report implementations were not sampled.

Main entry points: [`main.py`](https://github.com/lewjiayi/crowd-analysis/blob/main/main.py) (Processing entry point), [`deep_sort/tracker.py`](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/tracker.py) (Track manager), [`video_process.py`](https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py) (Frame processing), [`tracking.py`](https://github.com/lewjiayi/crowd-analysis/blob/main/tracking.py) (Person detection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Video processing"]
  node_config["Runtime settings<br/>[config.py]"]
  node_main["Processing entry point<br/>[main.py]"]
  node_video["Frame processing<br/>[video_process.py]"]
end

subgraph group_tracking["Detection and tracking"]
  node_detect["Person detection<br/>[tracking.py]"]
  node_encoder["Appearance encoder"]
  node_detection["Detection records<br/>[detection.py]"]
  node_tracker["Track manager<br/>[tracker.py]"]
  node_assignment["Track assignment"]
  node_kalman["Motion filter<br/>[kalman_filter.py]"]
  node_track["Track state<br/>[track.py]"]
  node_iou["IoU matching<br/>[iou_matching.py]"]
  node_metric["Feature matching<br/>[nn_matching.py]"]
end

subgraph group_analytics["Crowd analytics"]
  node_social["Distance violations<br/>[video_process.py]"]
  node_restricted["Restricted entry<br/>[video_process.py]"]
  node_abnormal["Abnormal activity<br/>[video_process.py]"]
  node_records[("Processed CSV and JSON<br/>[main.py]")]
end

subgraph group_reports["Data products"]
  node_energy_report["Energy summary"]
  node_movement_report["Movement summary"]
  node_crowd_report["Heatmap and flow"]
end

node_operator(("Video operator"))

node_operator -->|"sets inputs"| node_config
node_config -->|"configures"| node_main
node_main -->|"processes video"| node_video
node_main -->|"creates encoder"| node_encoder
node_main -->|"creates metric"| node_metric
node_main -->|"creates tracker"| node_tracker
node_video -->|"requests detections"| node_detect
node_detect -->|"extracts features"| node_encoder
node_detect -->|"builds detections"| node_detection
node_detect -->|"updates tracks"| node_tracker
node_tracker -->|"assigns detections"| node_assignment
node_tracker -->|"matches by IoU"| node_iou
node_tracker -->|"filters motion"| node_kalman
node_tracker -->|"updates state"| node_track
node_video -->|"checks proximity"| node_social
node_video -->|"checks entry"| node_restricted
node_video -->|"checks energy"| node_abnormal
node_main -->|"writes records"| node_records
node_records -->|"summarizes energy"| node_energy_report
node_records -->|"plots metrics"| node_movement_report
node_records -->|"derives heatmap and flow"| node_crowd_report

click node_config "https://github.com/lewjiayi/crowd-analysis/blob/main/config.py"
click node_main "https://github.com/lewjiayi/crowd-analysis/blob/main/main.py"
click node_video "https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py"
click node_detect "https://github.com/lewjiayi/crowd-analysis/blob/main/tracking.py"
click node_encoder "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/generate_detections.py"
click node_detection "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/detection.py"
click node_tracker "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/tracker.py"
click node_assignment "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/linear_assignment.py"
click node_kalman "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/kalman_filter.py"
click node_track "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/track.py"
click node_iou "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/iou_matching.py"
click node_metric "https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/nn_matching.py"
click node_social "https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py"
click node_restricted "https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py"
click node_abnormal "https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py"
click node_records "https://github.com/lewjiayi/crowd-analysis/blob/main/main.py"
click node_energy_report "https://github.com/lewjiayi/crowd-analysis/blob/main/abnormal_data_process.py"
click node_movement_report "https://github.com/lewjiayi/crowd-analysis/blob/main/movement_data_present.py"
click node_crowd_report "https://github.com/lewjiayi/crowd-analysis/blob/main/crowd_data_present.py"

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_config,node_main,node_video toneBlue
class node_detect,node_encoder,node_detection,node_tracker,node_assignment,node_kalman,node_track,node_iou,node_metric toneAmber
class node_social,node_restricted,node_abnormal,node_records toneMint
class node_energy_report,node_movement_report,node_crowd_report toneRose
class node_operator toneIndigo
```

## Components

### Video processing

- [Runtime settings](https://github.com/lewjiayi/crowd-analysis/blob/main/config.py): `config.py`
- [Processing entry point](https://github.com/lewjiayi/crowd-analysis/blob/main/main.py): `main.py`
- [Frame processing](https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py): `video_process.py`

### Detection and tracking

- [Person detection](https://github.com/lewjiayi/crowd-analysis/blob/main/tracking.py): `tracking.py`
- [Appearance encoder](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/generate_detections.py): `deep_sort/generate_detections.py`
- [Detection records](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/detection.py): `deep_sort/detection.py`
- [Track manager](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/tracker.py): `deep_sort/tracker.py`
- [Track assignment](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/linear_assignment.py): `deep_sort/linear_assignment.py`
- [Motion filter](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/kalman_filter.py): `deep_sort/kalman_filter.py`
- [Track state](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/track.py): `deep_sort/track.py`
- [IoU matching](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/iou_matching.py): `deep_sort/iou_matching.py`
- [Feature matching](https://github.com/lewjiayi/crowd-analysis/blob/main/deep_sort/nn_matching.py): `deep_sort/nn_matching.py`

### Crowd analytics

- [Distance violations](https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py): `video_process.py`
- [Restricted entry](https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py): `video_process.py`
- [Abnormal activity](https://github.com/lewjiayi/crowd-analysis/blob/main/video_process.py): `video_process.py`
- [Processed CSV and JSON](https://github.com/lewjiayi/crowd-analysis/blob/main/main.py): `main.py`

### Data products

- [Energy summary](https://github.com/lewjiayi/crowd-analysis/blob/main/abnormal_data_process.py): `abnormal_data_process.py`
- [Movement summary](https://github.com/lewjiayi/crowd-analysis/blob/main/movement_data_present.py): `movement_data_present.py`
- [Heatmap and flow](https://github.com/lewjiayi/crowd-analysis/blob/main/crowd_data_present.py): `crowd_data_present.py`

### Other components

- **Video operator**

## Connections

- Video operator → Runtime settings: sets inputs (evidence: `README.md`)
- Runtime settings → Processing entry point: configures (evidence: `main.py`)
- Processing entry point → Frame processing: processes video (evidence: `main.py`)
- Processing entry point → Appearance encoder: creates encoder (evidence: `main.py`)
- Processing entry point → Feature matching: creates metric (evidence: `main.py`)
- Processing entry point → Track manager: creates tracker (evidence: `main.py`)
- Frame processing → Person detection: requests detections (evidence: `video_process.py`)
- Person detection → Appearance encoder: extracts features (evidence: `tracking.py`)
- Person detection → Detection records: builds detections (evidence: `tracking.py`)
- Person detection → Track manager: updates tracks (evidence: `tracking.py`)
- Track manager → Track assignment: assigns detections (evidence: `deep_sort/tracker.py`)
- Track manager → IoU matching: matches by IoU (evidence: `deep_sort/tracker.py`)
- Track manager → Motion filter: filters motion (evidence: `deep_sort/tracker.py`)
- Track manager → Track state: updates state (evidence: `deep_sort/tracker.py`)
- Frame processing → Distance violations: checks proximity (evidence: `video_process.py`)
- Frame processing → Restricted entry: checks entry (evidence: `video_process.py`)
- Frame processing → Abnormal activity: checks energy (evidence: `video_process.py`)
- Processing entry point → Processed CSV and JSON: writes records (evidence: `main.py`)
- Processed CSV and JSON → Energy summary: summarizes energy (evidence: `README.md`)
- Processed CSV and JSON → Movement summary: plots metrics (evidence: `README.md`)
- Processed CSV and JSON → Heatmap and flow: derives heatmap and flow (evidence: `README.md`)
