How to Add New ReID Backbone Networks to BoxMOT: A Step-by-Step Implementation Guide

To add a new ReID backbone to BoxMOT, implement the architecture in boxmot/reid/backbones/, register the constructor in boxmot/reid/core/factory.py, and update the model registry in boxmot/reid/core/config.py to enable automatic instantiation during multi-object tracking.

BoxMOT, maintained in the mikel-brostrom/boxmot repository, is a widely-used open-source multi-object tracking framework that combines object detection with Re-identification (ReID) for robust tracking across frames. Integrating custom ReID backbone networks allows researchers to optimize feature extraction for specific surveillance domains or deploy lightweight architectures for edge devices. This guide details the exact implementation steps required to add new PyTorch-compatible ReID models to BoxMOT based on the current source code architecture.

Understanding the ReID Factory Architecture

BoxMOT employs a factory pattern to manage ReID model instantiation. The ReIDModelRegistry class in boxmot/reid/core/registry.py provides a build_model() method that dynamically constructs model instances by looking up constructor functions in the MODEL_FACTORY dictionary defined in boxmot/reid/core/factory.py. This design decouples model definitions from the tracking logic, allowing new backbones to be added without modifying the core tracking algorithms.

The architecture also leverages ReidAutoBackend to automatically handle different inference backends (PyTorch, ONNX, TensorRT). As long as your backbone follows the standard PyTorch API—including a get_features() method—it will be compatible with the existing PyTorchBackend without additional modifications.

Step 1: Create the Backbone Implementation

Create a new Python file in boxmot/reid/backbones/ that defines your architecture. Follow the structure of existing implementations like resnet.py or osnet.py, ensuring your function returns a torch.nn.Module.

Your implementation must expose a constructor function that accepts standard parameters: num_classes, loss, pretrained, and optional keyword arguments. If your model supports pretrained weights, implement the loading logic within this function.

Add the function name to the module's __all__ list to maintain a clean public API, following the convention seen in resnet.py where __all__ = ["resnet18", "resnet34", "resnet50", "resnet50_fc512"].

Step 2: Register the Model in the Factory

Edit boxmot/reid/core/factory.py to import your new constructor and add it to the MODEL_FACTORY dictionary. This dictionary maps unique string identifiers to constructor functions.

For example, if you created a backbone named tiny_resnet, add the import statement at the top of the file and insert the mapping "tiny_resnet": tiny_resnet into the MODEL_FACTORY dictionary alongside existing entries like "resnet50" and "osnet_x1_0".

Step 3: Update the Configuration Registry

Modify boxmot/reid/core/config.py to register your model name in two locations. First, append the new name to the MODEL_TYPES list so the auto-backend can recognize and validate the model identifier during configuration parsing.

Second, if you provide pretrained weights, add a download URL to the TRAINED_URLS dictionary using the model name as the key. This enables BoxMOT's automatic weight downloading utilities to fetch your checkpoint when users specify the model in their YAML configurations.

Step 4: Configure Your Tracking Pipeline

Create or modify a YAML configuration file to use your new backbone. Set the reid.model_name parameter to the string identifier you registered in the factory, and specify the path to your trained weights in reid.weights.

BoxMOT will automatically instantiate your model via ReIDModelRegistry.build_model(), load the specified weights, and integrate the backbone into the tracking pipeline without requiring further code changes.

Complete Implementation Example

The following example demonstrates adding a fictional tiny_resnet backbone optimized for fast inference.

First, implement the architecture:

# boxmot/reid/backbones/tiny_resnet.py

import torch.nn as nn
from boxmot.reid.backbones.resnet import ResNet, Bottleneck

def tiny_resnet(num_classes, loss="softmax", pretrained=False, **kwargs):
    """A lightweight ResNet variant for edge deployment."""
    model = ResNet(
        num_classes=num_classes,
        loss=loss,
        block=Bottleneck,
        layers=[1, 1, 1, 1],  # shallow architecture

        last_stride=2,
        fc_dims=None,
        dropout_p=None,
        **kwargs,
    )
    if pretrained:
        # Load custom checkpoint logic here

        pass
    return model

__all__ = ["tiny_resnet"]

Next, register the constructor in the factory:

# boxmot/reid/core/factory.py

from boxmot.reid.backbones.tiny_resnet import tiny_resnet  # Add import

MODEL_FACTORY = {
    # Existing entries...

    "osnet_x1_0": osnet_x1_0,
    "resnet50": resnet50,
    "tiny_resnet": tiny_resnet,  # Add registration

}

Then, update the configuration:

# boxmot/reid/core/config.py

MODEL_TYPES = [
    # Existing types...

    "resnet50",
    "osnet_x1_0",
    "tiny_resnet",  # Add to registry

]

TRAINED_URLS = {
    # Optional: Add pretrained weight URLs

    "tiny_resnet": "https://example.com/tiny_resnet_market1501.pth",
}

Finally, use the model in your tracking configuration:

# config.yaml

reid:
  model_name: tiny_resnet
  weights: path/to/tiny_resnet_market1501.pt
  loss: softmax

Key Technical Considerations

When implementing custom backbones, ensure your model class implements a get_features() method that returns embedding vectors. The ReidAutoBackend inspects the weight file suffix to determine the inference backend, but the model architecture itself must conform to the PyTorch API expectations defined in boxmot/reid/core/registry.py.

The factory pattern in boxmot/reid/core/factory.py centralizes model construction, while boxmot/reid/core/config.py maintains the canonical list of supported architectures. This separation ensures that adding new ReID backbone networks to BoxMOT requires changes only to the model definition and registration files, leaving the core tracking logic untouched.

Summary

• Implement your backbone in boxmot/reid/backbones/ following existing patterns like resnet.py and osnet.py.
• Register the constructor function in boxmot/reid/core/factory.py by adding an entry to the MODEL_FACTORY dictionary.
• Configure the model type in boxmot/reid/core/config.py by appending to MODEL_TYPES and optionally TRAINED_URLS.
• Deploy by referencing the model name in your YAML configuration files; the ReIDModelRegistry handles automatic instantiation.

Frequently Asked Questions

What file should I edit to register a new ReID backbone in BoxMOT?

Edit boxmot/reid/core/factory.py to import your constructor and add it to the MODEL_FACTORY dictionary. You must also update boxmot/reid/core/config.py to include the model name in MODEL_TYPES so the configuration validator recognizes the identifier.

Does BoxMOT support pretrained weights for custom ReID models?

Yes. Add your pretrained weight URLs to the TRAINED_URLS dictionary in boxmot/reid/core/config.py. When users specify your model name in a configuration file, BoxMOT will automatically download the weights if they are not present locally.

Where does the factory pattern instantiate ReID models in BoxMOT?

The ReIDModelRegistry.build_model() method in boxmot/reid/core/registry.py performs the instantiation. It looks up the model name in MODEL_FACTORY from boxmot/reid/core/factory.py and calls the associated constructor with parameters from the YAML configuration.

Can I use ONNX or TensorRT backends with custom ReID backbones?

Yes. The ReidAutoBackend class automatically selects the appropriate backend based on the weight file extension. As long as your custom backbone follows the standard PyTorch API and you export it to ONNX or TensorRT format, the existing backend implementations will handle inference without requiring modifications to your model code.

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