# mohit-robo/reid architecture

> Architecture diagram of the GitHub repository mohit-robo/reid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohit-robo/reid
- Repository: https://github.com/mohit-robo/reid

## Overview

1. **What this repo is**
   - A multi-camera person tracking / re-identification system, centered on assigning **stable global IDs** across disjoint camera views.
   - It is split between a production-style orchestration layer in `scripts/` and a reusable package in `trackers/` that contains tracking, IO, evaluation, motion, and tuning subsystems.

2. **Top-level runtime flow**
   - The main live pipeline is `scripts/run_pipeline.py`.
   - It takes one or more video streams, reads frames concurrently, runs per-frame detection and tracking, extracts appearance embeddings, associates local tracks to global identities, and writes annotated output video.
   - The README’s core flow is: **video frames → YOLOv8 detections → BoTSORT local tracks → OSNet embeddings → global identity assignment via AnchorPool → stabilized labels / rendering**.

3. **Per-camera local tracking layer**
   - Each camera stream is processed independently at first.
   - The repository includes multiple tracker implementations under `trackers/core/`: **BoT-SORT, ByteTrack, SORT, OCSORT, and CBIoU**.
   - These implementations share common utilities and tracklet structures, which makes the tracking algorithms interchangeable at the local-camera boundary.

4. **Cross-camera identity subsystem**
   - The MTMC logic lives mostly in `scripts/anchor_pool.py`, `scripts/embedding_associator.py`, `scripts/embedding_bank.py`, `scripts/tracklet.py`, and `scripts/majority_vote.py`.
   - `EmbeddingAssociator` post-processes tracker outputs using appearance similarity.
   - `AnchorPool` is the shared registry of **global identities**; it stores anchor embeddings and performs batched similarity matching to mint or reuse IDs.
   - `EmbeddingBank` maintains per-camera appearance history, and `tracklet.py` adds expired-track handling for the ghost gallery / re-entry logic.
   - `MajorityVoteBuffer` smooths unstable identity labels before they are shown or emitted.

5. **Appearance feature extraction**
   - The system uses **OSNet (`osnet_x1_0`, pretrained on MSMT17)** as the appearance encoder.
   - This is the key cross-camera feature source; it replaces relying only on detector/tracker state for identity continuity.
   - The architecture therefore has a distinct “visual identity” path separate from the motion-based local tracker path.

6. **Camera re-entry and persistence**
   - The architecture explicitly handles temporary disappearance across cameras.
   - Expired local tracklets are moved into a **Ghost Gallery**, where they remain matchable for a TTL window.
   - When a person reappears in another camera, the system can recover the same global ID by matching the new embedding against cached ghost anchors before falling back to a new identity.

7. **Motion and state modeling**
   - The `trackers/motion/` and `trackers/utils/kalman_filter.py` modules provide motion estimation and transformation support.
   - These are the state-estimation pieces used by the local trackers and related utilities.
   - This is a separate concern from appearance matching: motion stabilizes per-camera tracks, while embeddings solve cross-camera identity continuity.

8. **Input/output and data interfaces**
   - `trackers/io/` contains the boundary layer for data ingestion and emission:
     - `video.py` and `frames.py` for stream/frame handling,
     - `mot.py` for MOT-style interchange,
     - `paths.py` for path normalization and asset resolution.
   - The `scripts/gst_video_reader.py` and `scripts/gst_video_writer.py` files show that GStreamer is used for robust video IO and to avoid Python data-loading conflicts in the live pipeline.
   - Output is annotated video, not just numeric results.

9. **Evaluation and tuning**
   - `trackers/eval/` contains standard multi-object tracking metrics and result handling: **CLEAR, HOTA, ID metrics, box/result utilities**.
   - `trackers/scripts/eval.py` and `trackers/scripts/tune.py` indicate the project supports offline evaluation and parameter search, not only live inference.
   - `trackers/tune/tuner.py` and `trackers/scripts/progress.py` suggest an experiment loop around tracker/re-ID settings.

10. **Dataset and download support**
   - `trackers/datasets/` and `trackers/utils/downloader.py` manage dataset manifests and retrieval.
   - The root `download_videos.sh` and `filter_and_download.py` are focused on fetching or filtering sample videos for pipeline runs.
   - This means the repo includes both runtime inference and data acquisition tooling, which is important when diagramming the full system boundary.

11. **Packaging and deployment**
   - The repo is designed to run both locally and in Docker.
   - `Dockerfile` and `run_docker.sh` package the runtime environment; the README also calls out extra dependencies like `torchreid`, `gdown`, `torchvision`, and system GStreamer libraries.
   - In practice, the deployment boundary is: containerized Python runtime + GPU-enabled PyTorch + video IO stack + pretrained weights.

12. **Validation boundaries**
   - `tests/` contains install and phase tests (`test_install.py`, `test_phase0.py`, `test_phase1.py`, `test_phase2.py`).
   - These imply the repository is organized around incremental pipeline phases, with tests verifying that the environment and major architecture stages remain functional.

13. **How to draw the architecture**
   - The central diagram should show:
     - multiple video inputs,
     - per-stream decode/read,
     - per-frame detection and local tracking,
     - OSNet embedding extraction,
     - shared global ID registry / AnchorPool,
     - ghost-gallery re-entry path,
     - majority-vote stabilization,
     - annotated video output,
     - and an offline evaluation/tuning branch fed from saved results.
   - The `trackers/` package is the reusable algorithmic core; `scripts/` is the orchestration and productization layer.

Main entry points: [`scripts/run_pipeline.py`](https://github.com/mohit-robo/reid/blob/main/scripts/run_pipeline.py) (Run pipeline), [`trackers/core/base.py`](https://github.com/mohit-robo/reid/blob/main/trackers/core/base.py) (Track base), [`scripts/embedding_associator.py`](https://github.com/mohit-robo/reid/blob/main/scripts/embedding_associator.py) (Embedding assoc), [`trackers/core/botsort/tracker.py`](https://github.com/mohit-robo/reid/blob/main/trackers/core/botsort/tracker.py) (BoTSORT)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scripts["Orchestration"]
  node_run_pipeline["Run pipeline<br/>live MTMC runner<br/>[run_pipeline.py]"]
  node_gst_reader["Video reader<br/>GStreamer input"]
  node_gst_writer["Video writer<br/>GStreamer output"]
  node_anchor_pool[("AnchorPool<br/>global ID registry<br/>[anchor_pool.py]")]
  node_embed_assoc["Embedding assoc<br/>appearance matcher"]
  node_embed_bank["Embedding bank<br/>camera memory<br/>[embedding_bank.py]"]
  node_tracklet_mgr["Tracklet state<br/>ghost gallery<br/>[tracklet.py]"]
  node_majority_vote["Majority vote<br/>label smoother<br/>[majority_vote.py]"]
end

subgraph group_core["Tracking Core"]
  node_botsort["BoTSORT<br/>local tracker<br/>[tracker.py]"]
  node_bytetrack["ByteTrack<br/>local tracker<br/>[tracker.py]"]
  node_sort["SORT<br/>local tracker<br/>[tracker.py]"]
  node_ocsort["OCSORT<br/>local tracker<br/>[tracker.py]"]
  node_cbiou["CBIoU<br/>local tracker<br/>[tracker.py]"]
  node_track_base["Track base<br/>shared tracklet model<br/>[base.py]"]
end

subgraph group_platform["Platform"]
  node_video_io["Video IO<br/>frames/video boundary<br/>[video.py]"]
  node_mot_io["MOT IO<br/>result interchange<br/>[mot.py]"]
  node_motion["Motion models<br/>state estimation<br/>[estimator.py]"]
  node_eval["Evaluation<br/>metrics suite<br/>[evaluate.py]"]
  node_tune["Tuning<br/>experiment loop<br/>[tuner.py]"]
  node_datasets["Datasets<br/>manifest/download<br/>[manifest.py]"]
  node_utils["Utilities<br/>shared helpers<br/>[general.py]"]
end

subgraph group_ops["Ops"]
  node_docker["Docker<br/>container runtime"]
  node_download_tools["Download tools<br/>data acquisition<br/>[download_videos.sh]"]
  node_tests["Tests<br/>verification<br/>[test_phase0.py]"]
end

node_run_pipeline -->|"reads"| node_gst_reader
node_run_pipeline -->|"uses"| node_video_io
node_run_pipeline -->|"tracks"| node_botsort
node_run_pipeline -->|"re-id"| node_embed_assoc
node_run_pipeline -->|"global IDs"| node_anchor_pool
node_run_pipeline -->|"stabilizes"| node_majority_vote
node_run_pipeline -->|"writes"| node_gst_writer
node_botsort -->|"extends"| node_track_base
node_bytetrack -->|"extends"| node_track_base
node_sort -->|"extends"| node_track_base
node_ocsort -->|"extends"| node_track_base
node_cbiou -->|"extends"| node_track_base
node_botsort -->|"uses"| node_motion
node_ocsort -->|"uses"| node_motion
node_track_base -->|"depends on"| node_utils
node_embed_assoc -->|"updates"| node_embed_bank
node_embed_assoc -->|"matches"| node_anchor_pool
node_tracklet_mgr -->|"ghost match"| node_anchor_pool
node_eval -->|"reads"| node_mot_io
node_tune -->|"optimizes"| node_eval
node_datasets -->|"feeds"| node_download_tools
node_docker -->|"packages"| node_run_pipeline
node_tests -->|"verifies"| node_run_pipeline

click node_run_pipeline "https://github.com/mohit-robo/reid/blob/main/scripts/run_pipeline.py"
click node_gst_reader "https://github.com/mohit-robo/reid/blob/main/scripts/gst_video_reader.py"
click node_gst_writer "https://github.com/mohit-robo/reid/blob/main/scripts/gst_video_writer.py"
click node_anchor_pool "https://github.com/mohit-robo/reid/blob/main/scripts/anchor_pool.py"
click node_embed_assoc "https://github.com/mohit-robo/reid/blob/main/scripts/embedding_associator.py"
click node_embed_bank "https://github.com/mohit-robo/reid/blob/main/scripts/embedding_bank.py"
click node_tracklet_mgr "https://github.com/mohit-robo/reid/blob/main/scripts/tracklet.py"
click node_majority_vote "https://github.com/mohit-robo/reid/blob/main/scripts/majority_vote.py"
click node_botsort "https://github.com/mohit-robo/reid/blob/main/trackers/core/botsort/tracker.py"
click node_bytetrack "https://github.com/mohit-robo/reid/blob/main/trackers/core/bytetrack/tracker.py"
click node_sort "https://github.com/mohit-robo/reid/blob/main/trackers/core/sort/tracker.py"
click node_ocsort "https://github.com/mohit-robo/reid/blob/main/trackers/core/ocsort/tracker.py"
click node_cbiou "https://github.com/mohit-robo/reid/blob/main/trackers/core/cbiou/tracker.py"
click node_track_base "https://github.com/mohit-robo/reid/blob/main/trackers/core/base.py"
click node_video_io "https://github.com/mohit-robo/reid/blob/main/trackers/io/video.py"
click node_mot_io "https://github.com/mohit-robo/reid/blob/main/trackers/io/mot.py"
click node_motion "https://github.com/mohit-robo/reid/blob/main/trackers/motion/estimator.py"
click node_eval "https://github.com/mohit-robo/reid/blob/main/trackers/eval/evaluate.py"
click node_tune "https://github.com/mohit-robo/reid/blob/main/trackers/tune/tuner.py"
click node_datasets "https://github.com/mohit-robo/reid/blob/main/trackers/datasets/manifest.py"
click node_utils "https://github.com/mohit-robo/reid/blob/main/trackers/utils/general.py"
click node_docker "https://github.com/mohit-robo/reid/tree/main/Dockerfile"
click node_download_tools "https://github.com/mohit-robo/reid/blob/main/download_videos.sh"
click node_tests "https://github.com/mohit-robo/reid/blob/main/tests/test_phase0.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_run_pipeline,node_gst_reader,node_gst_writer,node_anchor_pool,node_embed_assoc,node_embed_bank,node_tracklet_mgr,node_majority_vote toneBlue
class node_botsort,node_bytetrack,node_sort,node_ocsort,node_cbiou,node_track_base toneAmber
class node_video_io,node_mot_io,node_motion,node_eval,node_tune,node_datasets,node_utils toneMint
class node_docker,node_download_tools,node_tests toneRose
```

## Components

### Orchestration

Live MTMC pipeline, global identity coordination, and video I/O wrappers.

- [Run pipeline](https://github.com/mohit-robo/reid/blob/main/scripts/run_pipeline.py): live MTMC runner · Entry point that drives multi-camera detection, tracking, re-identification, and rendering. · `scripts/run_pipeline.py`
- [Video reader](https://github.com/mohit-robo/reid/blob/main/scripts/gst_video_reader.py): GStreamer input · Robust stream ingestion for live or file-based video sources. · `scripts/gst_video_reader.py`
- [Video writer](https://github.com/mohit-robo/reid/blob/main/scripts/gst_video_writer.py): GStreamer output · Annotated video emission for the live pipeline. · `scripts/gst_video_writer.py`
- [AnchorPool](https://github.com/mohit-robo/reid/blob/main/scripts/anchor_pool.py): global ID registry · Shared store that mints, reuses, and matches global identities by embedding similarity. · `scripts/anchor_pool.py`
- [Embedding assoc](https://github.com/mohit-robo/reid/blob/main/scripts/embedding_associator.py): appearance matcher · Post-processes tracker outputs using cross-camera appearance similarity. · `scripts/embedding_associator.py`
- [Embedding bank](https://github.com/mohit-robo/reid/blob/main/scripts/embedding_bank.py): camera memory · Maintains per-camera appearance history and candidate embeddings. · `scripts/embedding_bank.py`
- [Tracklet state](https://github.com/mohit-robo/reid/blob/main/scripts/tracklet.py): ghost gallery · Handles expired tracks, re-entry windows, and ghost-gallery persistence. · `scripts/tracklet.py`
- [Majority vote](https://github.com/mohit-robo/reid/blob/main/scripts/majority_vote.py): label smoother · Stabilizes noisy identity assignments before output. · `scripts/majority_vote.py`

### Tracking Core

Reusable local multi-object tracking algorithms and shared tracklet utilities.

- [BoTSORT](https://github.com/mohit-robo/reid/blob/main/trackers/core/botsort/tracker.py): local tracker · Primary per-camera tracker implementation used by the pipeline. · `trackers/core/botsort/tracker.py`
- [ByteTrack](https://github.com/mohit-robo/reid/blob/main/trackers/core/bytetrack/tracker.py): local tracker · Alternative per-camera tracking implementation. · `trackers/core/bytetrack/tracker.py`
- [SORT](https://github.com/mohit-robo/reid/blob/main/trackers/core/sort/tracker.py): local tracker · Baseline tracking implementation for local association. · `trackers/core/sort/tracker.py`
- [OCSORT](https://github.com/mohit-robo/reid/blob/main/trackers/core/ocsort/tracker.py): local tracker · Motion-aware tracker variant for local association. · `trackers/core/ocsort/tracker.py`
- [CBIoU](https://github.com/mohit-robo/reid/blob/main/trackers/core/cbiou/tracker.py): local tracker · IoU-based tracking variant for local association. · `trackers/core/cbiou/tracker.py`
- [Track base](https://github.com/mohit-robo/reid/blob/main/trackers/core/base.py): shared tracklet model · Common tracker abstractions and tracklet state used across algorithms. · `trackers/core/base.py`

### Platform

Input/output, motion/state support, evaluation, tuning, datasets, and helper utilities.

- [Video IO](https://github.com/mohit-robo/reid/blob/main/trackers/io/video.py): frames/video boundary · Frame and video handling boundary for ingesting and emitting media. · `trackers/io/video.py`
- [MOT IO](https://github.com/mohit-robo/reid/blob/main/trackers/io/mot.py): result interchange · MOT-style interchange and record formatting for tracker outputs. · `trackers/io/mot.py`
- [Motion models](https://github.com/mohit-robo/reid/blob/main/trackers/motion/estimator.py): state estimation · Motion estimation and geometric transforms supporting local tracking. · `trackers/motion/estimator.py`
- [Evaluation](https://github.com/mohit-robo/reid/blob/main/trackers/eval/evaluate.py): metrics suite · CLEAR, HOTA, identity metrics, and result evaluation utilities. · `trackers/eval/evaluate.py`
- [Tuning](https://github.com/mohit-robo/reid/blob/main/trackers/tune/tuner.py): experiment loop · Search and progress tooling for tracker and re-ID parameter tuning. · `trackers/tune/tuner.py`
- [Datasets](https://github.com/mohit-robo/reid/blob/main/trackers/datasets/manifest.py): manifest/download · Dataset manifests and download helpers for sample or benchmark data. · `trackers/datasets/manifest.py`
- [Utilities](https://github.com/mohit-robo/reid/blob/main/trackers/utils/general.py): shared helpers · Common device, geometry, detection, and Kalman-filter helpers. · `trackers/utils/general.py`

### Ops

Containerization, downloads, documentation, and tests around the runtime.

- [Docker](https://github.com/mohit-robo/reid/tree/main/Dockerfile): container runtime · Packaged runtime environment for GPU-enabled video processing. · `Dockerfile`
- [Download tools](https://github.com/mohit-robo/reid/blob/main/download_videos.sh): data acquisition · Scripts for fetching and filtering source videos. · `download_videos.sh`
- [Tests](https://github.com/mohit-robo/reid/blob/main/tests/test_phase0.py): verification · Install and phased tests covering environment and pipeline stages. · `tests/test_phase0.py`

## Connections

- Run pipeline → Video reader: reads · Consumes one or more video streams.
- Run pipeline → Video IO: uses · Coordinates frame and video boundaries.
- Run pipeline → BoTSORT: tracks · Runs per-camera local tracking.
- Run pipeline → Embedding assoc: re-id · Links local tracks to cross-camera identities.
- Run pipeline → AnchorPool: global IDs · Looks up and updates stable identities.
- Run pipeline → Majority vote: stabilizes · Smooths unstable labels before rendering.
- Run pipeline → Video writer: writes · Emits annotated output video.
- BoTSORT → Track base: extends · Builds on shared tracker abstractions.
- ByteTrack → Track base: extends · Builds on shared tracker abstractions.
- SORT → Track base: extends · Builds on shared tracker abstractions.
- OCSORT → Track base: extends · Builds on shared tracker abstractions.
- CBIoU → Track base: extends · Builds on shared tracker abstractions.
- BoTSORT → Motion models: uses · Combines motion cues with detection updates.
- OCSORT → Motion models: uses · Combines motion cues with detection updates.
- Track base → Utilities: depends on · Shares common geometry, state, and filtering helpers.
- Embedding assoc → Embedding bank: updates · Stores per-camera appearance history.
- Embedding assoc → AnchorPool: matches · Compares embeddings against global anchors.
- Tracklet state → AnchorPool: ghost match · Supports re-entry from expired-track memory.
- Evaluation → MOT IO: reads · Evaluates saved tracking outputs.
- Tuning → Evaluation: optimizes · Searches tracker and re-ID settings against metrics.
- Datasets → Download tools: feeds · Supplies source data acquisition and filtering.
- Docker → Run pipeline: packages · Encapsulates the live runtime environment.
- Tests → Run pipeline: verifies · Checks staged pipeline functionality and installation.
