How to Use YOLOX with BoxMOT for Detection and Tracking

BoxMOT integrates YOLOX detection models through automatic model-type routing in boxmot.detectors and the YoloXStrategy inference class, enabling seamless multi-object tracking via CLI or Python API.

The BoxMOT repository provides a unified framework for multi-object tracking that supports multiple detector backends, including the popular YOLOX architecture. By leveraging specific filename patterns and dedicated inference strategies, BoxMOT automatically handles model loading, preprocessing, and post-processing for YOLOX variants. This guide explains how to use YOLOX with BoxMOT for detection and tracking, covering both command-line workflows and programmatic integration.

YOLOX Integration Architecture

BoxMOT's YOLOX support is built on three core components that work together to route detection requests, execute inference, and manage model weights.

Model-Type Routing

The entry point for YOLOX detection begins in boxmot/detectors/__init__.py, where the get_yolo_inferer function examines the detector filename or CLI string. If the name contains any YOLOX substring—yolox_n, yolox_s, yolox_m, yolox_l, or yolox_x—the router selects the YOLOX inference class automatically.

# From boxmot/detectors/__init__.py (lines 22-33)

# Logic that maps model names to YoloXStrategy

if any(x in str(detector) for x in ['yolox_n', 'yolox_s', 'yolox_m', 'yolox_l', 'yolox_x']):
    from boxmot.detectors.yolox import YoloXStrategy
    return YoloXStrategy

This routing mechanism allows you to specify YOLOX models by name without manually importing classes or configuring backends.

YoloXStrategy Implementation

The YoloXStrategy class in boxmot/detectors/yolox.py implements the complete detect-preprocess-postprocess pipeline. It mirrors the official YOLOX loading routine and automatically downloads pretrained weights from the built-in YOLOX_ZOO if the .pt file does not exist locally via download_file from boxmot.utils.download.

Key capabilities of this strategy include:

• Automatic dependency management: Uses RequirementsChecker to install the yolox package if missing
• Device optimization: Includes MPS (Apple Silicon) support through monkey-patching of YOLOXHead.decode_outputs to avoid dtype-string issues
• Flexible input handling: Accepts numpy arrays or torch tensors depending on the pipeline stage

CLI Command Mapping

The tracking CLI in boxmot/engine/cli.py accepts a positional detector argument (or the --yolo-model option) that gets forwarded to the routing logic. When you supply a YOLOX model name, the CLI creates a YoloXStrategy instance at lines 10-15 and executes the tracking loop starting at line 17.

Step-by-Step Usage

Follow these steps to run YOLOX-based detection and tracking with BoxMOT.

1. Install Dependencies

While BoxMOT can install YOLOX automatically via RequirementsChecker when first used, you may pre-install the package:

pip install yolox

2. Run Tracking via CLI

Use the track command with any supported YOLOX model filename. The name must contain the YOLOX substring for proper routing:

# Track using YOLOX-S with DeepOCSORT tracker

boxmot track yolox_s.pt osnet_x0_25_msmt17 deepocsort \
    --source video.mp4 \
    --show

BoxMOT will:

1. Resolve yolox_s.pt → YoloXStrategy via get_yolo_inferer
2. Download weights from YOLOX_ZOO if missing
3. Initialize the model with default image size [1080, 1920]
4. Run detection on each frame and feed results to the specified tracker

3. Use Custom Checkpoints

Provide a path containing the YOLOX substring to use custom-trained weights:

boxmot track my_yolox_custom_MOT20.pt osnet_x0_25_msmt17 strongsort \
    --source 0  # webcam input

The routing logic applies the same YoloXStrategy class, but BoxMOT will not overwrite your local checkpoint file.

4. Generate Detections in Batch

For offline processing or embedding generation, use the generate command with multiple YOLOX models:

boxmot generate yolox_x.pt yolox_n.pt \
    osnet_x0_25_msmt17 \
    --source /data/videos \
    --imgsz 1080 1920

Advanced Configuration Options

Image Size Adjustment

YOLOX defaults to [1080, 1920] (stored in YoloXStrategy.default_imgsz). Override this for different input resolutions:

boxmot track yolox_m.pt osnet_x0_25_msmt17 botsort \
    --source video.mp4 \
    --imgsz 720 1280

The size parameter is stored in YoloXStrategy.imgsz and passed to yolox_preprocess during inference.

Class-Specific Detection

Restrict detection to specific COCO class IDs using the --classes flag. The YOLOX post-processing pipeline respects this filter:

boxmot track yolox_l.pt osnet_x0_25_msmt17 deepocsort \
    --source video.mp4 \
    --classes 0 1 2  # person, bicycle, car only

Python API Integration

For custom pipelines, instantiate YoloXStrategy directly:

from boxmot.detectors.yolox import YoloXStrategy
from pathlib import Path
import torch

# Path to model (auto-downloads if missing)

model_path = Path("yolox_s.pt")
device = torch.device("cuda:0" if torch.cuda.is_available() else "cpu")

# Initialize strategy

strategy = YoloXStrategy(model_path, device, args=None)

# im can be list of numpy images (H,W,3) or 4-D torch tensor [B,3,H,W]

preds = strategy(im, augment=False, visualize=False, embed=False)

Key Implementation Details

Automatic Weight Management: If the specified .pt file is absent, YoloXStrategy.__init__ triggers download_file to fetch weights from the URLs defined in YOLOX_ZOO, ensuring zero-configuration deployment.

Hardware Compatibility: The YOLOX module specifically handles MPS device quirks by patching YOLOXHead.decode_outputs, preventing dtype-related crashes on Apple Silicon hardware.

Strategy Pattern: The separation between boxmot/detectors/__init__.py (routing) and boxmot/detectors/yolox.py (implementation) allows BoxMOT to support multiple detector families while maintaining clean, backend-specific preprocessing logic.

Summary

• BoxMOT routes YOLOX models automatically when filenames contain yolox_n, yolox_s, yolox_m, yolox_l, or yolox_x substrings via boxmot/detectors/__init__.py.
• The YoloXStrategy class in boxmot/detectors/yolox.py handles complete inference, including automatic weight downloads from YOLOX_ZOO.
• Use the CLI commands boxmot track or boxmot generate with YOLOX model names to execute detection and tracking pipelines immediately.
• Default image size is 1080×1920, configurable via --imgsz, with full support for class filtering and custom checkpoints.
• The implementation includes MPS compatibility patches and lazy dependency installation for streamlined deployment.

Frequently Asked Questions

What YOLOX model variants does BoxMOT support?

BoxMOT supports all standard YOLOX variants including yolox_n (nano), yolox_s (small), yolox_m (medium), yolox_l (large), and yolox_x (extra large). The detection routing in boxmot/detectors/__init__.py recognizes these substrings in any filename, including custom-trained checkpoints like yolox_x_MOT17_ablation.pt.

How does BoxMOT handle missing YOLOX weights?

When you specify a YOLOX model that isn't present locally, the YoloXStrategy.__init__ method automatically calls download_file from boxmot.utils.download. This fetches the appropriate pretrained weights from the built-in YOLOX_ZOO URL mappings, downloading them to your working directory before initializing the model.

Can I use YOLOX with BoxMOT on Apple Silicon (MPS)?

Yes, BoxMOT includes specific patches for MPS compatibility. The boxmot/detectors/yolox.py file monkey-patches YOLOXHead.decode_outputs to resolve dtype-string issues that occur when running YOLOX on Apple Silicon devices, ensuring the detection pipeline runs without modification on MPS hardware.

What is the default input size for YOLOX in BoxMOT?

YOLOX models in BoxMOT default to an input size of 1080×1920 (height × width), stored in YoloXStrategy.default_imgsz. You can override this using the --imgsz CLI flag or by modifying the imgsz attribute when using the Python API directly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}