# tajwarchy/multi-camera-people-tracking architecture

> Architecture diagram of the GitHub repository tajwarchy/multi-camera-people-tracking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tajwarchy/multi-camera-people-tracking
- Repository: https://github.com/tajwarchy/multi-camera-people-tracking

## Overview

This repository implements a multi-camera pedestrian tracking system: synchronized camera frames are processed into per-camera detections, local tracks and appearance embeddings; cross-camera association assigns global identities; calibrated projections and those identities drive a bird’s-eye view and composite video. Separate utilities prepare and score ReID evaluation crops. The sampled sources establish the core runtime calls; calibration and frame-extraction roles are documented in the README, so links to later stages are shown only where documented.

Main entry points: [`src/pipeline_single_cam.py`](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/pipeline_single_cam.py) (Camera pipeline), [`src/config_loader.py`](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/config_loader.py) (Config loading), [`src/run_association.py`](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/run_association.py) (Association runner), [`src/bev_projector.py`](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/bev_projector.py) (BEV projection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Inputs and calibration"]
  node_frame_extraction["Frame extraction<br/>[extract_frames.py]"]
  node_calibration["Calibration parsing"]
  node_configuration["Config loading<br/>[config_loader.py]"]
end

subgraph group_tracking["Per-camera tracking"]
  node_single_camera["Camera pipeline"]
  node_detection["Person detection<br/>[detector.py]"]
  node_local_tracking["Local tracking<br/>[tracker.py]"]
  node_appearance["Appearance embeddings<br/>[embedder.py]"]
end

subgraph group_identity["Global identity"]
  node_association_runner["Association runner<br/>[run_association.py]"]
  node_reid["Cross-camera ReID<br/>[reid_associator.py]"]
end

subgraph group_outputs["Mapping and evaluation"]
  node_bev_projection["BEV projection<br/>[bev_projector.py]"]
  node_bev_animation["BEV animation<br/>[bev_animator.py]"]
  node_video_composition["Composite export<br/>[main_pipeline.py]"]
  node_evaluation_preparation["Evaluation crop prep"]
  node_reid_evaluation["ReID evaluation<br/>[eval_reid.py]"]
end

node_video_sources(("Camera videos"))

node_video_sources -->|"provides video"| node_frame_extraction
node_frame_extraction -.->|"supplies frames"| node_single_camera
node_configuration -->|"configures"| node_single_camera
node_single_camera -->|"calls detect"| node_detection
node_single_camera -->|"updates tracks"| node_local_tracking
node_single_camera -->|"extracts features"| node_appearance
node_configuration -->|"configures"| node_association_runner
node_association_runner -->|"runs association"| node_reid
node_single_camera -->|"stores records"| node_association_runner
node_configuration -->|"configures"| node_bev_projection
node_calibration -.->|"provides homographies"| node_bev_projection
node_bev_projection -->|"projects tracks"| node_bev_animation
node_configuration -->|"configures"| node_video_composition
node_bev_animation -->|"supplies BEV frames"| node_video_composition
node_single_camera -->|"renders annotations"| node_video_composition
node_configuration -->|"configures"| node_evaluation_preparation
node_association_runner -.->|"writes enriched records"| node_evaluation_preparation
node_configuration -->|"configures"| node_reid_evaluation
node_evaluation_preparation -.->|"creates query/gallery crops"| node_reid_evaluation

click node_frame_extraction "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/extract_frames.py"
click node_calibration "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/parse_calibration.py"
click node_configuration "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/config_loader.py"
click node_single_camera "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/pipeline_single_cam.py"
click node_detection "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/detector.py"
click node_local_tracking "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/tracker.py"
click node_appearance "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/embedder.py"
click node_association_runner "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/run_association.py"
click node_reid "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/reid_associator.py"
click node_bev_projection "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/bev_projector.py"
click node_bev_animation "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/bev_animator.py"
click node_video_composition "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/main_pipeline.py"
click node_evaluation_preparation "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/prepare_reid_eval.py"
click node_reid_evaluation "https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/eval_reid.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_frame_extraction,node_calibration,node_configuration toneBlue
class node_single_camera,node_detection,node_local_tracking,node_appearance toneAmber
class node_association_runner,node_reid toneMint
class node_bev_projection,node_bev_animation,node_video_composition,node_evaluation_preparation,node_reid_evaluation toneRose
class node_video_sources toneIndigo
```

## Components

### Inputs and calibration

- [Frame extraction](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/extract_frames.py): `src/extract_frames.py`
- [Calibration parsing](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/parse_calibration.py): `src/parse_calibration.py`
- [Config loading](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/config_loader.py): `src/config_loader.py`

### Per-camera tracking

- [Camera pipeline](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/pipeline_single_cam.py): `src/pipeline_single_cam.py`
- [Person detection](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/detector.py): `src/detector.py`
- [Local tracking](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/tracker.py): `src/tracker.py`
- [Appearance embeddings](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/embedder.py): `src/embedder.py`

### Global identity

- [Association runner](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/run_association.py): `src/run_association.py`
- [Cross-camera ReID](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/reid_associator.py): `src/reid_associator.py`

### Mapping and evaluation

- [BEV projection](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/bev_projector.py): `src/bev_projector.py`
- [BEV animation](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/bev_animator.py): `src/bev_animator.py`
- [Composite export](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/main_pipeline.py): `src/main_pipeline.py`
- [Evaluation crop prep](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/prepare_reid_eval.py): `src/prepare_reid_eval.py`
- [ReID evaluation](https://github.com/tajwarchy/multi-camera-people-tracking/blob/main/src/eval_reid.py): `src/eval_reid.py`

### Other components

- **Camera videos**

## Connections

- Camera videos → Frame extraction: provides video (evidence: `README.md`)
- Frame extraction → Camera pipeline: supplies frames
- Config loading → Camera pipeline: configures (evidence: `src/pipeline_single_cam.py`)
- Camera pipeline → Person detection: calls detect (evidence: `src/pipeline_single_cam.py`)
- Camera pipeline → Local tracking: updates tracks (evidence: `src/pipeline_single_cam.py`)
- Camera pipeline → Appearance embeddings: extracts features (evidence: `src/pipeline_single_cam.py`)
- Config loading → Association runner: configures (evidence: `src/run_association.py`)
- Association runner → Cross-camera ReID: runs association (evidence: `src/run_association.py`)
- Camera pipeline → Association runner: stores records (evidence: `src/run_association.py`)
- Config loading → BEV projection: configures (evidence: `src/main_pipeline.py`)
- Calibration parsing → BEV projection: provides homographies (evidence: `README.md`)
- BEV projection → BEV animation: projects tracks (evidence: `src/bev_animator.py`)
- Config loading → Composite export: configures (evidence: `src/main_pipeline.py`)
- BEV animation → Composite export: supplies BEV frames (evidence: `src/main_pipeline.py`)
- Camera pipeline → Composite export: renders annotations (evidence: `src/main_pipeline.py`)
- Config loading → Evaluation crop prep: configures (evidence: `src/prepare_reid_eval.py`)
- Association runner → Evaluation crop prep: writes enriched records
- Config loading → ReID evaluation: configures (evidence: `src/eval_reid.py`)
- Evaluation crop prep → ReID evaluation: creates query/gallery crops