# mikel-brostrom/boxmot architecture

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

- Interactive diagram: https://gitdiagram.com/mikel-brostrom/boxmot
- Repository: https://github.com/mikel-brostrom/boxmot

## Overview

##### Project type and purpose
- BoxMOT is an open-source Python library and CLI tool for multi-object tracking (MOT).
- It provides a pluggable, state-of-the-art tracking framework that integrates seamlessly with detection, segmentation, and pose models and a zoo of ReID backbones.
- Users interact via a unified CLI (`boxmot`) that supports subcommands for tracking, generating detections and embeddings, evaluation, tuning, and exporting ReID models.

##### File structure
- Top-level entry points:
- Dockerfile, pyproject.toml and manifest for packaging.
- README.md and LICENSE.
- `boxmot/engine/cli.py` — CLI interface.
- Modular library layout under `boxmot/`:
- `appearance/` — ReID backbones, exporters, auto-backends.
- `configs/` — YAML configs for each tracker method.
- `data/` — dataset loader and utilities.
- `engine/` — orchestrates detection, tracking, evaluation, tuning.
- `motion/` — motion models and Kalman filters.
- `postprocessing/` — output smoothing (GSI).
- `trackers/` — implementations of SOTA trackers (boosttrack, botsort, etc.).
- `utils/` — common helpers (association, IOU, plotting).
- Example notebooks under `examples/`.
- Tests under `tests/` for unit and performance.

##### README for additional insights
- Architecture is pipeline-driven:
Input source → Detector → (optional) ReID embedding → Tracker → Postprocessing → Output/evaluation.
- Supports multiple backends (PyTorch, ONNX, TensorRT, OpenVINO) for ReID export and inference.
- Configs dictate hyperparameters for detectors, trackers, and motion models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    CLI["CLI Frontend"]:::core
    Config["Configuration Manager"]:::data
    DataLoader["Data Loader"]:::core
    Detector["Detector Factory"]:::algorithm
    subgraph "Appearance/ReID Module"
        ReIDAPI["ReID API"]:::core
        Backends["Backends"]:::algorithm
        Exporters["Exporters"]:::algorithm
    end
    subgraph "Tracker Module"
        BaseTracker["Tracker Base"]:::core
        TrackerZoo["Tracker Zoo"]:::core
        Trackers["Algorithms"]:::algorithm
    end
    subgraph "Motion Module"
        Kalman["Kalman Filters"]:::algorithm
        CMC["Consensus Motion (CMC)"]:::algorithm
    end
    Post["Postprocessing"]:::core
    subgraph "Output & Evaluation"
        TrackOrch["Tracking Orchestration"]:::core
        Eval["Evaluation"]:::core
    end
    subgraph "External Frameworks"
        PT["PyTorch"]:::external
        ONNX["ONNX Runtime"]:::external
        TRT["TensorRT"]:::external
        OVI["OpenVINO"]:::external
    end
    subgraph "Data & Config Assets"
        Assets["Datasets"]:::data
        Weights["Pre-trained Weights"]:::data
    end

    %% Flow
    CLI -->|"loads config"| Config
    Config -->|"parameters"| DataLoader
    DataLoader -->|"frames"| Detector
    Detector -->|"boxes/masks/poses"| ReIDAPI
    ReIDAPI -->|"embeddings"| Backends
    Backends -->|"embeddings"| Exporters
    Exporters -->|"final embeddings"| Trackers
    Detector -->|"detections"| Trackers
    Trackers -->|"detections+embeddings"| Kalman
    Kalman -->|"predictions"| Trackers
    Trackers -->|"tracklets"| Post
    Post -->|"smoothed tracklets"| TrackOrch
    TrackOrch -->|"results"| Eval
    DataLoader -->|"dets+embs"| TrackOrch
    Eval -->|"metrics"| CLI

    %% External dependencies
    ReIDAPI --> PT
    ReIDAPI --> ONNX
    ReIDAPI --> TRT
    ReIDAPI --> OVI
    Detector --> PT

    %% Assets
    Assets --> DataLoader
    Weights --> Detector
    Weights --> ReIDAPI

    %% Click events
    click CLI "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/engine/cli.py"
    click Config "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/configs/"
    click DataLoader "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/data/loader.py"
    click Detector "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/engine/detectors/"
    click ReIDAPI "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/appearance/reid/"
    click Backends "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/appearance/backends/"
    click Exporters "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/appearance/exporters/"
    click BaseTracker "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/trackers/basetracker.py"
    click TrackerZoo "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/tracker_zoo.py"
    click Trackers "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/trackers/"
    click Kalman "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/motion/kalman_filters/"
    click CMC "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/motion/cmc/"
    click Post "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/postprocessing/gsi.py"
    click TrackOrch "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/engine/track.py"
    click Eval "https://github.com/mikel-brostrom/boxmot/blob/master/boxmot/engine/val.py"
    click Assets "https://github.com/mikel-brostrom/boxmot/tree/master/assets/"
    click Weights "https://github.com/mikel-brostrom/boxmot/tree/master/boxmot/engine/weights/"

    %% Styles
    classDef core fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1
    classDef algorithm fill:#C8E6C9,stroke:#388E3C,color:#1B5E20
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#E65100
    classDef data fill:#E0E0E0,stroke:#757575,color:#424242
```
