# nrl-ai/tracking-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/nrl-ai/tracking-pipeline
- Repository: https://github.com/nrl-ai/tracking-pipeline

## Overview

##### Main Components
- Entry Point & Configuration: Represent the main.py and tracking_config.yaml as the starting point that loads the configuration and selects the desired detection and tracking algorithms.
- Detection Module: Group the Detection directory into subcomponents for each supported detector. Highlight separate subdirectories (nanodet, yolov4, yolov5, and yolox) that contain specific network configurations, model definitions, and utilities for pre-processing data and running the inference.
- Utility and Supporting Libraries: Include modules for data transformations, evaluation, logging, and visualization. This covers files in the "tools", "image", and various util subdirectories under Detection.

##### Relationships and Interactions
- That main.py is the orchestrator: it loads the configuration, initializes the selected detection module (which might branch off to one of several algorithms based on the config), and forwards inference results to the chosen tracking module.
- Flow of data: begin with raw input (video or images), pass through pre-processing (data transformation, augmentation, etc.) before running the detection models, then feed the detection results into a tracking algorithm, and finally produce tracking outputs (tracked object IDs and visualized frames).

##### Architectural Patterns and Design Principles
- Modular Design: Emphasize that separate directories for each detection and tracking algorithm make the system highly pluggable and configurable.
- Abstraction & Separation of Concerns: The clear separation between detection and tracking components (with dedicated configuration files and utility modules) suggests an architecture that leverages abstraction for model selection and execution.
- Extensibility: New detection or tracking algorithms can be added as additional modules (directories) without disrupting the core pipeline.

##### Technologies, Frameworks, and Libraries
- Detection Frameworks: Under Detection, note that frameworks like PyTorch are likely used (given the .py source files and common deep learning model structure) and that each subdirectory contains model definitions, loss functions, and evaluation metrics.
- Tracking Algorithms: Similarly, the tracking modules implement algorithms that include Kalman filters, matching algorithms, and other metric utilities.
- Configuration and Scripting: YAML configurations, batch processing scripts, and various visualization tools support the execution flow.

##### Specific Elements
- Labels for each major component: “Main Application (main.py)”, “Configuration Manager (tracking_config.yaml)”, “Detection Engines (NanoDet, YOLOv4, YOLOv5, YOLOX)”, “Tracking Engines (Sort, DeepSort, ByteTrack, Motpy, Norfair)”, “Utilities & Data Processing” (showing areas like data augmentation, loss computation, and visualization).
- Annotations indicating that the Detection and Tracking modules are loosely coupled, with a central configuration file guiding which implementations are used.
- Optionally, a note that external dependencies (e.g., pre-trained weights stored in specific directories as mentioned in the README) are expected to be injected at runtime.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input and Pre-Processing
    Input["Raw Input (Video/Images)"]:::input
    Preproc["Data Preprocessing & Transformation"]:::preprocess

    %% Entry Point & Configuration
    subgraph "Entry Point & Configuration"
        MainApp["Main Application (main.py)"]:::entry
        Config["Configuration Manager (tracking_config.yaml)"]:::entry
    end

    %% Detection Engines
    subgraph "Detection Engines"
        NanoDet["NanoDet"]:::detection
        YOLOv4["YOLOv4"]:::detection
        YOLOv5["YOLOv5"]:::detection
        YOLOX["YOLOX"]:::detection
    end

    %% Tracking Engines
    subgraph "Tracking Engines"
        ByteTrack["ByteTrack"]:::tracking
        DeepSort["DeepSort"]:::tracking
        Motpy["Motpy"]:::tracking
        Norfair["Norfair"]:::tracking
        Sort["Sort"]:::tracking
    end

    %% Utilities & Data Processing
    subgraph "Utilities & Data Processing"
        Tools["Tools & Colors"]:::utility
        NanoDetUtil["NanoDet Utilities"]:::utility
    end

    %% Output
    Output["Output Visualization (Tracked Frames)"]:::output

    %% Connections
    Input -->|"feeds"| Preproc
    Preproc -->|"processed data"| MainApp
    Config ---|"loaded config"| MainApp
    MainApp -->|"selects detection"| NanoDet
    MainApp -->|"selects detection"| YOLOv4
    MainApp -->|"selects detection"| YOLOv5
    MainApp -->|"selects detection"| YOLOX
    Tools ---|"supports"| NanoDet
    Tools ---|"supports"| YOLOv4
    Tools ---|"supports"| YOLOv5
    Tools ---|"supports"| YOLOX
    NanoDetUtil ---|"provides utilities"| NanoDet

    NanoDet -->|"detection results"| ByteTrack
    NanoDet -->|"detection results"| DeepSort
    NanoDet -->|"detection results"| Motpy
    NanoDet -->|"detection results"| Norfair
    NanoDet -->|"detection results"| Sort

    YOLOv4 -->|"detection results"| ByteTrack
    YOLOv4 -->|"detection results"| DeepSort
    YOLOv4 -->|"detection results"| Motpy
    YOLOv4 -->|"detection results"| Norfair
    YOLOv4 -->|"detection results"| Sort

    YOLOv5 -->|"detection results"| ByteTrack
    YOLOv5 -->|"detection results"| DeepSort
    YOLOv5 -->|"detection results"| Motpy
    YOLOv5 -->|"detection results"| Norfair
    YOLOv5 -->|"detection results"| Sort

    YOLOX -->|"detection results"| ByteTrack
    YOLOX -->|"detection results"| DeepSort
    YOLOX -->|"detection results"| Motpy
    YOLOX -->|"detection results"| Norfair
    YOLOX -->|"detection results"| Sort

    ByteTrack ---|"tracks objects"| Output
    DeepSort ---|"tracks objects"| Output
    Motpy ---|"tracks objects"| Output
    Norfair ---|"tracks objects"| Output
    Sort ---|"tracks objects"| Output

    %% Click Events
    click MainApp "https://github.com/nrl-ai/tracking-pipeline/blob/master/main.py"
    click Config "https://github.com/nrl-ai/tracking-pipeline/blob/master/tracking_config.yaml"
    click NanoDet "https://github.com/nrl-ai/tracking-pipeline/tree/master/Detection/nanodet"
    click YOLOv4 "https://github.com/nrl-ai/tracking-pipeline/tree/master/Detection/yolov4"
    click YOLOv5 "https://github.com/nrl-ai/tracking-pipeline/tree/master/Detection/yolov5"
    click YOLOX "https://github.com/nrl-ai/tracking-pipeline/tree/master/Detection/yolox"
    click ByteTrack "https://github.com/nrl-ai/tracking-pipeline/tree/master/Tracking/bytetrack"
    click DeepSort "https://github.com/nrl-ai/tracking-pipeline/tree/master/Tracking/deep_sort"
    click Motpy "https://github.com/nrl-ai/tracking-pipeline/tree/master/Tracking/motpy"
    click Norfair "https://github.com/nrl-ai/tracking-pipeline/tree/master/Tracking/norfair"
    click Sort "https://github.com/nrl-ai/tracking-pipeline/tree/master/Tracking/sort"
    click Tools "https://github.com/nrl-ai/tracking-pipeline/blob/master/tools/colors.py"
    click NanoDetUtil "https://github.com/nrl-ai/tracking-pipeline/tree/master/Detection/nanodet/util"

    %% Styles
    classDef entry fill:#F9A825,stroke:#333,stroke-width:2px;
    classDef detection fill:#66BB6A,stroke:#333,stroke-width:2px;
    classDef tracking fill:#42A5F5,stroke:#333,stroke-width:2px;
    classDef utility fill:#B0BEC5,stroke:#333,stroke-width:2px;
    classDef input fill:#FFCC80,stroke:#333,stroke-width:2px;
    classDef preprocess fill:#FFD54F,stroke:#333,stroke-width:2px;
    classDef output fill:#AED581,stroke:#333,stroke-width:2px;
```
