# jay-huy/diffmot architecture

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

- Interactive diagram: https://gitdiagram.com/jay-huy/diffmot
- Repository: https://github.com/jay-huy/diffmot

## Overview

##### Project Type and Purpose
- DiffMOT is a research‐grade, full‐pipeline multiple object tracking system.
- It combines:
- A detector (YOLOX)
- A ReID feature extractor (deep‐person‐reid / fast_reid)
- A diffusion‐based motion prediction model (D²MP)
- A tracker core (association, Kalman‐based & non‐linear update)
- It is designed for real‐time, high‐accuracy tracking on benchmarks (DanceTrack, SportsMOT, MOT17/20).

##### High‐Level Architectural Components
A) Data Preparation & Configuration
- Config files (configs/*.yaml) define dataset paths, thresholds, weights (association, embedding)
- Data processors (dancetrack_data_process.py, sports_data_process.py, mot_data_process.py) convert raw video frames + ground truth into standardized inputs
B) Detection Module (external/YOLOX)
- Pluggable: supports YOLOX‐S/M/L/X
C) ReID Embedding Module (external/deep-person-reid, external/fast_reid)
- Takes cropped detections → outputs deep feature embeddings
D) Motion Prediction Module (models/ & main.py)
- Diffusion‐based motion model (“D²MP”) implemented in models/denoising_diffusion_pytorch.py & related
- Trains to predict non‐linear future positions
E) Tracker Core (tracker/ & tracking_utils/)
- Association logic (matching.py, gmc.py, cmc.py)
- Kalman‐filter variants (tracker/ocsort_tracker/kalmanfilter.py, tracking_utils/kalman_filter.py)
- Track management (DiffMOTtracker.py, basetrack.py)
- Non‐maximum suppression, metric evaluation, logging, visualization
F) Experiment & Evaluation
- experiments/ holds logs, TensorBoard events for training curves
- external/TrackEval for standardized metric computation

##### Component Relationships & Data Flow
- Raw frames → Data Preparation → Detector → Detected BBoxes → ReID Module → Embeddings → Motion Model → Predicted trajectories → Tracker Core (association & update) → Output tracks
- Config Manager feeds hyperparameters into each module
- Logging & Visualization subscribes to all stages for metrics and debugging
- External libraries (YOLOX, deep‐person‐reid, fast_reid, TrackEval) are integrated as pluggable components

##### Architectural Patterns & Principles
- Modular Pipeline: Each stage is a well‐defined module with clear I/O
- Pluggable Components: Swap detectors or ReID extractors via config
- Separation of Concerns: Data I/O, model training, inference, tracking logic, evaluation are distinct
- Reuse of External Tools: Leverage off‐the‐shelf detection, ReID, and evaluation libraries

##### Detailed Elements
- Config Manager (configs/*.yaml) reading
- Data Processors feeding Detector/ReID
- Detector module (external/YOLOX)
- ReID module (external/deep‐person‐reid & fast_reid)
- Diffusion Motion Model (models/*.py, main.py)
- Tracker Core (tracker/, tracking_utils/)
- Evaluation & Logging (experiments/, external/TrackEval)
- Input frames → Detector
- Detector → ReID
- ReID + previous tracks → Motion Model
- Motion Model + embeddings → Association logic
- Association logic → Updated track states
- Final tracks → Output / Visualizer → TrackEval

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Config & Data Preparation
    subgraph "Config & DataPrep"
        cfg["Config Manager"]:::config
        dp1["Dancetrack Processor"]:::config
        dp2["Sports Processor"]:::config
        dp3["MOT Processor"]:::config
    end

    %% Detector Module
    subgraph "Detector Module"
        YOLOX["YOLOX Detector"]:::external
        YA["YOLOX Adaptor"]:::external
    end

    %% ReID Module
    subgraph "ReID Embedding Module"
        DPR["deep-person-reid"]:::external
        FR["fast_reid"]:::external
        FA["fastreid Adaptor"]:::external
    end

    %% Motion Prediction Module
    subgraph "D²MP Motion Model"
        ddp["denoising_diffusion_pytorch.py"]:::core
        diff["diffusion.py"]:::core
        common["common.py"]:::core
        comp["components.py"]:::core
        cond["condition_embedding.py"]:::core
        unet["unet_variants.py"]:::core
        main["diffmot.py"]:::core
    end

    %% Tracker Core
    subgraph "Tracker Core"
        TM["DiffMOTtracker"]:::core
        BS["basetrack"]:::core
        MT["matching"]:::core
        GMC["gmc"]:::core
        CMC["cmc"]:::core
        KOC["kalmanfilter"]:::core
        AOC["association"]:::core
        OCS["ocsort"]:::core
    end

    %% Tracking Utilities
    subgraph "Tracking Utilities"
        KU["kalman_filter"]:::core
        NKA["NSA_kalman_filter"]:::core
        NMS["nms"]:::core
        EV["evaluation"]:::core
        IO["io"]:::core
        LG["log"]:::core
        VIZ["visualization"]:::core
        PC["parse_config"]:::core
        TMER["timer"]:::core
        UT["utils"]:::core
    end

    %% Experiment & Evaluation
    experiments["Experiments / Logs"]:::storage
    TE["TrackEval"]:::external

    %% Data Flow
    cfg -->dp1
    cfg -->dp2
    cfg -->dp3
    dp1 -->YOLOX
    dp2 -->YOLOX
    dp3 -->YOLOX
    YOLOX -->YA
    YA -->FA
    FA -->DPR
    FA -->FR
    DPR -->ddp
    FR -->ddp
    ddp -->diff
    diff -->common
    common -->comp
    comp -->cond
    cond -->unet
    unet -->main
    main -->TM
    main -->BS
    TM -->MT
    TM -->GMC
    TM -->CMC
    BS -->KOC
    BS -->AOC
    BS -->OCS

    %% Logging & Visualization subscriptions
    dp1 -->LG
    YOLOX -->LG
    FA -->LG
    main -->LG
    TM -->LG
    LG -->VIZ

    %% Final Evaluation
    TM -->experiments
    experiments -->TE

    %% Click Events
    click cfg "https://github.com/jay-huy/diffmot/tree/main/configs/"
    click dp1 "https://github.com/jay-huy/diffmot/blob/main/dancetrack_data_process.py"
    click dp2 "https://github.com/jay-huy/diffmot/blob/main/sports_data_process.py"
    click dp3 "https://github.com/jay-huy/diffmot/blob/main/mot_data_process.py"
    click YOLOX "https://github.com/jay-huy/diffmot/tree/main/external/YOLOX/"
    click YA "https://github.com/jay-huy/diffmot/blob/main/external/adaptors/yolox_adaptor.py"
    click DPR "https://github.com/jay-huy/diffmot/tree/main/external/deep-person-reid/"
    click FR "https://github.com/jay-huy/diffmot/tree/main/external/fast_reid/"
    click FA "https://github.com/jay-huy/diffmot/blob/main/external/adaptors/fastreid_adaptor.py"
    click ddp "https://github.com/jay-huy/diffmot/blob/main/models/denoising_diffusion_pytorch.py"
    click diff "https://github.com/jay-huy/diffmot/blob/main/models/diffusion.py"
    click common "https://github.com/jay-huy/diffmot/blob/main/models/common.py"
    click comp "https://github.com/jay-huy/diffmot/blob/main/models/components.py"
    click cond "https://github.com/jay-huy/diffmot/blob/main/models/condition_embedding.py"
    click unet "https://github.com/jay-huy/diffmot/blob/main/models/unet_variants.py"
    click main "https://github.com/jay-huy/diffmot/blob/main/diffmot.py"
    click TM "https://github.com/jay-huy/diffmot/blob/main/tracker/DiffMOTtracker.py"
    click BS "https://github.com/jay-huy/diffmot/blob/main/tracker/basetrack.py"
    click MT "https://github.com/jay-huy/diffmot/blob/main/tracker/matching.py"
    click GMC "https://github.com/jay-huy/diffmot/blob/main/tracker/gmc.py"
    click CMC "https://github.com/jay-huy/diffmot/blob/main/tracker/cmc.py"
    click KOC "https://github.com/jay-huy/diffmot/blob/main/tracker/ocsort_tracker/kalmanfilter.py"
    click AOC "https://github.com/jay-huy/diffmot/blob/main/tracker/ocsort_tracker/association.py"
    click OCS "https://github.com/jay-huy/diffmot/blob/main/tracker/ocsort_tracker/ocsort.py"
    click KU "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/kalman_filter.py"
    click NKA "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/NSA_kalman_filter.py"
    click NMS "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/nms.py"
    click EV "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/evaluation.py"
    click IO "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/io.py"
    click LG "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/log.py"
    click VIZ "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/visualization.py"
    click PC "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/parse_config.py"
    click TMER "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/timer.py"
    click UT "https://github.com/jay-huy/diffmot/blob/main/tracking_utils/utils.py"
    click experiments "https://github.com/jay-huy/diffmot/tree/main/experiments/"
    click TE "https://github.com/jay-huy/diffmot/tree/main/external/TrackEval/"

    %% Styles
    classDef core fill:#B3CDE3,stroke:#333,stroke-width:1px
    classDef external fill:#CCEBC5,stroke:#333,stroke-width:1px
    classDef config fill:#FBB4AE,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFFCC,stroke:#333,stroke-width:1px
```
