# regob/vehicle_mtmc architecture

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

- Interactive diagram: https://gitdiagram.com/regob/vehicle_mtmc
- Repository: https://github.com/regob/vehicle_mtmc

## Overview

##### Main Components
- Input and Data Sources:
– Video streams and datasets (see “datasets” folder and config paths).
– Pretrained models (resnet50 re-ID, SVM classifiers for vehicle attributes) with instructions for download.
- Detection Module:
– Uses Yolov5 (note the “detection/yolov5” submodule) for vehicle detection.
- Single-Camera Tracking (MOT):
– Implements trackers inside the “mot” directory with separate implementations for ByteTrack and DeepSORT.
- Re-Identification (ReID):
– Found in the “reid” directory, used to extract embeddings to help match vehicle identities.
- Multi-Target Multi-Camera Tracking (MTMC):
– The “mtmc” directory clusters and merges tracks from different cameras using hierarchical clustering.
– Also involves camera layout configuration (config/cityflow, config/zala) to enforce temporal and spatial constraints.
- Evaluation:
– The “evaluate” directory provides scripts and methods to compute metrics such as MOTA and IDF1.
- Auxiliary Tools & Scripts:
– The “tools” folder contains various helper utilities for data conversion, metric calculations, and video processing.
– Test suites for unit testing are maintained under “test”.

##### Architecture Relationships and Data Flow
- Input Flow: Video inputs from one or multiple cameras are fed into the detection module.
- Detection: Each frame is processed by the YOLOv5-based detector to locate vehicles.
- Feature Extraction: Detected objects are passed through a re-ID model to extract features. In parallel, the attribute extraction components (using either torch or other ML models) produce additional labels.
- MOT Tracking: With detection and features, the MOT tracker (either ByteTrack or DeepSORT) creates single-camera tracks.
- MTMC Integration: For multi-camera use cases, the “mtmc” module takes the single-camera tracks, applies hierarchical clustering (using configurations like LINKAGE type and MIN_SIM thresholds), and enforces spatial–temporal constraints based on a provided camera layout.
- Evaluation: The “evaluate” module then computes the tracking metrics on the results.
- Output: Results, annotated videos (e.g., stored in “output”), and logs are generated and stored accordingly.

##### Architectural Patterns & Design Principles
- Modularity: Each major function (detection, tracking, re-ID, MTMC, evaluation) is organized in its own directory.
- Configuration-Driven: The “config” folder (with subfolders for cityflow and zala) contains YAML and calibration files that separate settings from code.
- Extensibility: The system is built to easily support adding new attributes, switching trackers, or integrating new models through configurable parameters.
- Reusability: Use of external submodules (e.g., yolov5, vehicle_reid, and adaptations from DeepSORT and ByteTrack) indicates that the design emphasizes component reuse.

##### Technologies, Frameworks, and Libraries
- Python (likely 3.7–3.10) as the primary development language.
- Deep learning frameworks like PyTorch, as noticed by pretrained models and references to torch.
- Computer vision and tracking dependencies via YOLOv5, ByteTrack, and DeepSORT.
- Utilities and libraries for evaluation, clustering, and video processing.
- External tools for camera calibration are referenced (e.g., Cal_PNP).

## Diagram (Mermaid)

```mermaid
graph TD
    A["Video Input"]:::input
    B["Configuration Files"]:::config

    subgraph "Detection Module"
        C["YOLOv5 Detector"]:::processing
        D["YOLOv5 Submodule"]:::processing
    end

    subgraph "Single-Camera Tracking"
        E["Attribute Extraction"]:::tracker
        F["ReID Feature Extractor"]:::processing
        G["ByteTrack Tracker"]:::tracker
        H["DeepSORT Tracker"]:::tracker
        I["MOT Tracking Output"]:::processing
    end

    J["MTMC Module"]:::processing
    K["Evaluation"]:::processing
    L["Output Results"]:::output

    M["Auxiliary Tools"]:::aux
    N["Test Suite"]:::aux

    %% Data Flow
    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    E --> G
    F --> G
    E --> H
    F --> H
    G --> I
    H --> I
    I --> J
    B --> J
    J --> K
    K --> L
    M --- K
    N --- K

    %% Click Events
    click A "https://github.com/regob/vehicle_mtmc/tree/master/datasets"
    click B "https://github.com/regob/vehicle_mtmc/tree/master/config"
    click C "https://github.com/regob/vehicle_mtmc/blob/master/detection/detection.py"
    click D "https://github.com/regob/vehicle_mtmc/tree/master/detection/yolov5"
    click E "https://github.com/regob/vehicle_mtmc/blob/master/mot/attributes.py"
    click F "https://github.com/regob/vehicle_mtmc/blob/master/reid/feature_extractor.py"
    click F "https://github.com/regob/vehicle_mtmc/tree/master/reid/vehicle_reid"
    click G "https://github.com/regob/vehicle_mtmc/tree/master/mot/byte_track"
    click H "https://github.com/regob/vehicle_mtmc/tree/master/mot/deep_sort"
    click J "https://github.com/regob/vehicle_mtmc/blob/master/mtmc/mtmc_clustering.py"
    click K "https://github.com/regob/vehicle_mtmc/blob/master/evaluate/evaluation.py"
    click K "https://github.com/regob/vehicle_mtmc/blob/master/evaluate/run_evaluate.py"
    click M "https://github.com/regob/vehicle_mtmc/tree/master/tools"
    click N "https://github.com/regob/vehicle_mtmc/tree/master/test"

    %% Styles
    classDef input fill:#ccf,stroke:#333,stroke-width:2px;
    classDef config fill:#ffc,stroke:#333,stroke-width:2px;
    classDef processing fill:#cfc,stroke:#333,stroke-width:2px;
    classDef tracker fill:#fcf,stroke:#333,stroke-width:2px;
    classDef output fill:#fcc,stroke:#333,stroke-width:2px;
    classDef aux fill:#ddf,stroke:#333,stroke-width:2px;
```
