# holmescao/topictrack architecture

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

- Interactive diagram: https://gitdiagram.com/holmescao/topictrack
- Repository: https://github.com/holmescao/topictrack

## Overview

##### Project type and purpose
- TOPICTrack is an open-source multi-object tracking system for video data.
- It is built to achieve state-of-the-art MOT performance by innovating on the association paradigm (parallel association using both motion and appearance features) and handling diverse scenes.
- Its purpose is to combine detection (via YOLOX), online tracking (using modules like Deep SORT and OC-SORT variants) and re-identification (leveraging fast_reid or deep-person-reid models) to generate reliable tracking outputs.

##### Main components
- Detector Module:
- Uses external/YOLOX.
- Input: video frames.
- Re-ID / Appearance Feature Extraction:
- Uses modules from external/fast_reid and external/deep-person-reid.
- Computes appearance embeddings for each detected object.
- Tracker / Association Module:
- Implements the core TOPIC parallel association paradigm.
- Receives motion information (e.g., via Kalman filters, SORT variants in src/deep_sort and trackers folders) and appearance features.
- Integrates both cues to perform robust track association.
- Data Preparation and Conversion:
- Tools for converting various datasets (MOT17, MOT20, DanceTrack, GMOT, BEE24) into COCO format (e.g., files under tools/convert_*).
- Dataset and configuration utilities (dataset.py, files under exps, src/_init_paths.py).
- Training and Evaluation Pipelines:
- Training scripts (tools/train.py, exps configuration files) for both detection models and Re-ID models.
- Evaluation scripts to run metrics on tracking outputs (eval_metrics.sh along with results folder structure).
- Demo / Visualization:
- Demo scripts (demo.py, src/demo.py) that utilize the model for producing visual outputs and video tracking demos.

##### Relationships and data flow
- Datasets (MOT17, MOT20, DanceTrack, GMOT, BEE24) are pre-processed using conversion tools.
- Detection Pipeline:
- Feature Extraction:
- From detections, branch off to the “Re-ID Module” that outputs appearance embeddings.
- Tracking Association:
- Within the tracking module, show two parallel paths:
– One path coming from motion estimation (SORT/kalman filter in sorts and trackers submodules).
– The other coming from appearance features.
- That the “Parallel Association Paradigm” (TOPIC) fuses these cues adaptively.
- Output Generation:
- The association results are then directed to "Result Storage" and "Evaluation Engine" (evaluation scripts, metrics calculation).
- Training Loop:
– Detector Training (using exps configuration, external weights pretraining, and training scripts in tools/train.py).
– Re-ID Training (via fast_reid training scripts inside external/fast_reid and associated configuration files).
- Demo Execution:
- A component for “Demo/Visualization” receives outputs from the Tracking Module and generates visualizations (videos, plots from figs folder).

##### Architectural patterns and technologies
- The architecture is modular – each major function (detection, re-ID, association, evaluation) is decoupled.
- The design capitalizes on established research codebases and offers clear extension points (e.g., new dataset conversion scripts under tools/).
- The use of experiment configuration files in the “exps” folder exemplifies how training, validation and testing are separated by configuration, making the architecture both flexible and maintainable.
- Use of external modules is clearly visible; therefore, label these components with the specific technologies (e.g., “YOLOX – Deep Learning Detector”, “FastReID – Efficiency and Accuracy for Re-ID”).

##### Important details to capture
- Configuration management through the “exps” directory which acts as the bridge between code and experimental setup.
- A clear separation between components used during training (e.g., scripts in tools/train.py, experiments in exps) and those used during testing/inference (demo.py, evaluation scripts).

– Data Input & Preprocessing (datasets, conversion tools)
– Detector module (YOLOX, with pre-trained weights)
– Feature extraction/Re-ID modules (using FastReID/Deep-Person Re-ID)
– The core Tracking & Association module (with parallel streams: motion and appearance, fused by TOPIC)
– Output & Evaluation components
– Training pipelines (with attention to experiment configurations and source structure)

## Diagram (Mermaid)

```mermaid
graph TD
    %% Inference Pipeline Subgraph
    subgraph "Inference Pipeline"
        D["Data Conversion (Preprocessing)"]:::preprocessing
        DET["Detector Module (YOLOX-based)"]:::detection
        FEAT["Feature Extraction/Re-ID Module"]:::reid
        MOT["Motion-based Tracking"]:::tracking
        APP["Appearance-based Tracking"]:::tracking
        FUSE["Parallel Association Paradigm"]:::tracking
        EVAL["Result Evaluation Engine"]:::evaluation
    end

    %% Training Pipeline Subgraph
    subgraph "Training Pipeline"
        DET_T["Detector Training"]:::training
        REID_T["Re-ID Training"]:::training
    end

    %% Demo/Visualization Node
    DEMO["Demo/Visualization"]:::demo

    %% Connections for Inference Pipeline
    D -->|"toDetector"| DET
    DET -->|"forDetections"| FEAT
    DET -->|"motionInfo"| MOT
    FEAT -->|"appearanceFeatures"| APP
    MOT -->|"fusesWith"| FUSE
    APP -->|"fusesWith"| FUSE
    FUSE -->|"tracksTo"| EVAL
    FUSE -->|"tracksTo"| DEMO

    %% Click Events for Data Preparation
    click D "https://github.com/holmescao/topictrack/blob/main/tools/convert_mot17_to_coco.py"
    click D "https://github.com/holmescao/topictrack/blob/main/tools/convert_dance_to_coco.py"
    click D "https://github.com/holmescao/topictrack/blob/main/src/tools/convert_dancetrack_to_coco.py"

    %% Click Events for Detector Module
    click DET "https://github.com/holmescao/topictrack/tree/main/external/YOLOX"
    click DET "https://github.com/holmescao/topictrack/tree/main/exps/default"

    %% Click Events for Re-ID Module
    click FEAT "https://github.com/holmescao/topictrack/tree/main/external/fast_reid"
    click FEAT "https://github.com/holmescao/topictrack/tree/main/external/deep-person-reid"

    %% Click Events for Tracking Module (Motion and Appearance)
    click MOT "https://github.com/holmescao/topictrack/tree/main/src/deep_sort"
    click APP "https://github.com/holmescao/topictrack/tree/main/trackers/ocsort_embedding"
    click APP "https://github.com/holmescao/topictrack/tree/main/trackers/tracking_utils"

    %% Click Events for Training Pipeline
    click DET_T "https://github.com/holmescao/topictrack/blob/main/tools/train.py"
    click DET_T "https://github.com/holmescao/topictrack/tree/main/exps/default"
    click REID_T "https://github.com/holmescao/topictrack/tree/main/external/fast_reid"
    click REID_T "https://github.com/holmescao/topictrack/tree/main/external/deep-person-reid"

    %% Click Event for Evaluation
    click EVAL "https://github.com/holmescao/topictrack/blob/main/eval_metrics.sh"

    %% Click Events for Demo/Visualization
    click DEMO "https://github.com/holmescao/topictrack/blob/main/demo.py"
    click DEMO "https://github.com/holmescao/topictrack/blob/main/src/demo.py"
    click DEMO "https://github.com/holmescao/topictrack/tree/main/figs"

    %% Styling Classes
    classDef preprocessing fill:#CFE2F3,stroke:#333,stroke-width:2px;
    classDef detection fill:#FFCCCB,stroke:#333,stroke-width:2px;
    classDef reid fill:#F9CB9C,stroke:#333,stroke-width:2px;
    classDef tracking fill:#D9EAD3,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef training fill:#D0E0E3,stroke:#333,stroke-width:2px;
    classDef demo fill:#F4CCCC,stroke:#333,stroke-width:2px;
```
