# tstanczyk95/mcbyteplusplus architecture

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

- Interactive diagram: https://gitdiagram.com/tstanczyk95/mcbyteplusplus
- Repository: https://github.com/tstanczyk95/mcbyteplusplus

## Overview

McByte++ is a training-free, tracking-by-detection system for long-term sports-video tracking. The user supplies frames and optionally detections; the demo runs detection, online association and identity management, then writes MOT records and visualizations. With re-ID enabled, it also uses appearance features to reconnect returning subjects; mask propagation and selective camera-motion compensation support the tracking process. YOLOX model code, the EdgeTAM-backed mask manager, and the re-ID package are represented as distinct internal layers. The README documents the overall workflow; some internal call ordering is not shown in the excerpts.

Main entry points: [`tools/demo_track__with_reid.py`](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__with_reid.py) (Demo with re-ID), [`tools/demo_track__no_reid.py`](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__no_reid.py) (Demo without re-ID), [`yolox/tracker/mcbyteplusplus_tracker__with_reid.py`](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/mcbyteplusplus_tracker__with_reid.py) (Online tracker with re-ID), [`yolox/models/yolo_head.py`](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/models/yolo_head.py) (YOLOX detection head)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Demo entry"]
  node_demo_reid["Demo with re-ID"]
  node_demo_plain["Demo without re-ID"]
end

subgraph group_detection["Detection"]
  node_det_input["Detection input"]
  node_yolox_exp["Detector configuration<br/>[base_exp.py]"]
  node_yolox_head["YOLOX detection head<br/>[yolo_head.py]"]
end

subgraph group_tracking["Tracking and identity"]
  node_tracker_reid["Online tracker with re-ID"]
  node_tracker_plain["Online tracker"]
  node_kalman["Motion filtering<br/>[kalman_filter.py]"]
  node_matching["Track matching<br/>[matching.py]"]
  node_cmc["Camera motion compensation<br/>[gmc.py]"]
  node_reid["Appearance features"]
end

subgraph group_masking["Mask propagation"]
  node_mask_manager["Mask manager"]
  node_sam_builder["EdgeTAM predictor builder<br/>[build_sam.py]"]
end

subgraph group_results["Outputs"]
  node_visualize["Tracking visualization<br/>[visualize.py]"]
  node_records["MOT records"]
end

node_operator(("Video operator"))
node_frames["Input frames"]
node_offline_assoc["Offline global association"]

node_operator -->|"runs"| node_demo_reid
node_operator -->|"runs"| node_demo_plain
node_frames -->|"provides frames"| node_demo_reid
node_frames -->|"provides frames"| node_demo_plain
node_det_input -->|"optional detections"| node_demo_reid
node_demo_reid -->|"configures detector"| node_yolox_exp
node_demo_reid -.->|"runs detection"| node_yolox_head
node_demo_plain -.->|"runs detection"| node_yolox_head
node_yolox_head -.->|"supplies detections"| node_tracker_reid
node_yolox_head -.->|"supplies detections"| node_tracker_plain
node_demo_reid -->|"runs tracking"| node_tracker_reid
node_demo_plain -->|"runs tracking"| node_tracker_plain
node_tracker_reid -->|"uses motion filter"| node_kalman
node_tracker_reid -->|"uses matching"| node_matching
node_tracker_reid -->|"uses camera compensation"| node_cmc
node_tracker_reid -->|"extracts features"| node_reid
node_demo_reid -->|"manages masks"| node_mask_manager
node_demo_plain -.->|"manages masks"| node_mask_manager
node_mask_manager -->|"builds predictor"| node_sam_builder
node_demo_reid -->|"renders tracks"| node_visualize
node_demo_plain -->|"renders tracks"| node_visualize
node_demo_reid -->|"writes MOT records"| node_records
node_demo_plain -->|"writes MOT records"| node_records
node_records -.->|"optional post-processing"| node_offline_assoc

click node_demo_reid "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__with_reid.py"
click node_demo_plain "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__no_reid.py"
click node_yolox_exp "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/exp/base_exp.py"
click node_yolox_head "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/models/yolo_head.py"
click node_tracker_reid "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/mcbyteplusplus_tracker__with_reid.py"
click node_tracker_plain "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/mcbyteplusplus_tracker__no_reid.py"
click node_kalman "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/kalman_filter.py"
click node_matching "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/matching.py"
click node_cmc "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/gmc.py"
click node_reid "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/deep-person-reid/torchreid/utils/feature_extractor.py"
click node_mask_manager "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/mask_propagation/mask_manager__edgetam.py"
click node_sam_builder "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/mask_propagation/EdgeTAM/sam2/build_sam.py"
click node_visualize "https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/utils/visualize.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_demo_reid,node_demo_plain toneBlue
class node_det_input,node_yolox_exp,node_yolox_head toneAmber
class node_tracker_reid,node_tracker_plain,node_kalman,node_matching,node_cmc,node_reid toneMint
class node_mask_manager,node_sam_builder toneRose
class node_visualize,node_records,node_operator,node_frames,node_offline_assoc toneIndigo
```

## Components

### Demo entry

- [Demo with re-ID](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__with_reid.py): `tools/demo_track__with_reid.py`
- [Demo without re-ID](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/tools/demo_track__no_reid.py): `tools/demo_track__no_reid.py`

### Detection

- **Detection input**
- [Detector configuration](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/exp/base_exp.py): `yolox/exp/base_exp.py`
- [YOLOX detection head](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/models/yolo_head.py): `yolox/models/yolo_head.py`

### Tracking and identity

- [Online tracker with re-ID](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/mcbyteplusplus_tracker__with_reid.py): `yolox/tracker/mcbyteplusplus_tracker__with_reid.py`
- [Online tracker](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/mcbyteplusplus_tracker__no_reid.py): `yolox/tracker/mcbyteplusplus_tracker__no_reid.py`
- [Motion filtering](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/kalman_filter.py): `yolox/tracker/kalman_filter.py`
- [Track matching](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/matching.py): `yolox/tracker/matching.py`
- [Camera motion compensation](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/tracker/gmc.py): `yolox/tracker/gmc.py`
- [Appearance features](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/deep-person-reid/torchreid/utils/feature_extractor.py): `deep-person-reid/torchreid/utils/feature_extractor.py`

### Mask propagation

- [Mask manager](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/mask_propagation/mask_manager__edgetam.py): `mask_propagation/mask_manager__edgetam.py`
- [EdgeTAM predictor builder](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/mask_propagation/EdgeTAM/sam2/build_sam.py): `mask_propagation/EdgeTAM/sam2/build_sam.py`

### Outputs

- [Tracking visualization](https://github.com/tstanczyk95/mcbyteplusplus/blob/main/yolox/utils/visualize.py): `yolox/utils/visualize.py`
- **MOT records**

### Other components

- **Video operator**
- **Input frames**
- **Offline global association**

## Connections

- Video operator → Demo with re-ID: runs (evidence: `README.md`)
- Video operator → Demo without re-ID: runs (evidence: `README.md`)
- Input frames → Demo with re-ID: provides frames (evidence: `README.md`)
- Input frames → Demo without re-ID: provides frames (evidence: `README.md`)
- Detection input → Demo with re-ID: optional detections (evidence: `README.md`)
- Demo with re-ID → Detector configuration: configures detector (evidence: `tools/demo_track__with_reid.py`)
- Demo with re-ID → YOLOX detection head: runs detection
- Demo without re-ID → YOLOX detection head: runs detection
- YOLOX detection head → Online tracker with re-ID: supplies detections
- YOLOX detection head → Online tracker: supplies detections
- Demo with re-ID → Online tracker with re-ID: runs tracking (evidence: `tools/demo_track__with_reid.py`)
- Demo without re-ID → Online tracker: runs tracking (evidence: `README.md`)
- Online tracker with re-ID → Motion filtering: uses motion filter (evidence: `yolox/tracker/mcbyteplusplus_tracker__with_reid.py`)
- Online tracker with re-ID → Track matching: uses matching (evidence: `yolox/tracker/mcbyteplusplus_tracker__with_reid.py`)
- Online tracker with re-ID → Camera motion compensation: uses camera compensation (evidence: `yolox/tracker/mcbyteplusplus_tracker__with_reid.py`)
- Online tracker with re-ID → Appearance features: extracts features (evidence: `yolox/tracker/mcbyteplusplus_tracker__with_reid.py`)
- Demo with re-ID → Mask manager: manages masks (evidence: `tools/demo_track__with_reid.py`)
- Demo without re-ID → Mask manager: manages masks
- Mask manager → EdgeTAM predictor builder: builds predictor (evidence: `mask_propagation/mask_manager__edgetam.py`)
- Demo with re-ID → Tracking visualization: renders tracks (evidence: `tools/demo_track__with_reid.py`)
- Demo without re-ID → Tracking visualization: renders tracks (evidence: `README.md`)
- Demo with re-ID → MOT records: writes MOT records (evidence: `README.md`)
- Demo without re-ID → MOT records: writes MOT records (evidence: `README.md`)
- MOT records → Offline global association: optional post-processing (evidence: `README.md`)
