How to Configure ReID Appearance Embeddings for Identity Persistence in BoxMOT

To configure ReID appearance embeddings for identity persistence in BoxMOT, select a ReID-capable tracker (such as StrongSort, HybridSort, DeepOcSort, BotSort, or BoostTrack), provide a pretrained .pt weight file via the reid_weights argument in create_tracker, and tune appearance-related parameters in the tracker's YAML configuration file.

BoxMOT maintains object identities across video frames by fusing motion cues with appearance embeddings extracted from a Re-ID (re-identification) neural network. Proper configuration of these embeddings prevents ID switches during occlusions, camera movement, or when objects re-enter the scene after disappearing.

Select a ReID-Capable Tracker from the Tracker Zoo

Not all trackers in BoxMOT utilize appearance features. The repository defines REID_TRACKERS inside boxmot/trackers/tracker_zoo.py to distinguish models that support appearance embeddings.

Choose from the following trackers to enable ReID functionality:

• StrongSort – Uses cosine distance on appearance vectors for nearest-neighbor matching
• HybridSort – Implements long-term ReID memory for persistent identities across gaps
• DeepOcSort – Fuses embedding costs with motion Association
• BotSort – Applies appearance thresholds with global motion compensation
• BoostTrack – Supports appearance features via the standard reid_weights interface

Load Pretrained ReID Weights via create_tracker

The create_tracker factory function in boxmot/trackers/tracker_zoo.py (lines 75-80) accepts a reid_weights parameter that injects the model path into compatible trackers.

from pathlib import Path
from boxmot.trackers.tracker_zoo import create_tracker

tracker = create_tracker(
    tracker_type="strongsort",
    tracker_config=Path("boxmot/configs/trackers/strongsort.yaml"),
    reid_weights=Path("/data/reid_weights/osnet_x0_25_msmt17.pt"),
    device="cuda",
    half=True,  # FP16 for speed

)

When reid_weights is provided, trackers like StrongSort automatically load the model and call self.model.get_features (implemented in boxmot/trackers/strongsort/strongsort.py, lines 73-80) during the update() cycle to extract embeddings from detection crops.

Configure Tracker-Specific Appearance Parameters

Each tracker exposes YAML configuration options that control how appearance embeddings influence the data association step.

HybridSort Long-Term ReID Memory

HybridSort provides advanced long-term appearance modeling through keys defined in boxmot/configs/trackers/hybridsort.yaml:

• with_longterm_reid (lines 76-80) – Enables a memory bank that stores appearance vectors across many frames. Default is True.
• longterm_reid_weight (lines 81-84) – Controls the fusion weight between long-term appearance distance and motion cost. Default is 0.0; increase to 0.5 or higher to prioritize appearance over motion.
• with_longterm_reid_correction (lines 86-90) – Applies thresholding to reject spurious long-term matches. Keep True for robust filtering.

DeepOcSort Embedding Controls

DeepOcSort manages appearance features through boxmot/configs/trackers/deepocsort.yaml:

• embedding_off (lines 51-55) – Set to false (default) to enable embeddings, or true for pure motion tracking.
• w_association_emb (lines 36-40) – Weighting factor for the embedding cost component in the final association score.

StrongSort and BotSort Distance Thresholds

Distance thresholds determine when two appearance vectors represent the same identity:

• StrongSort: max_cos_dist in boxmot/configs/trackers/strongsort.yaml (lines 11-14) sets the maximum cosine distance for the nearest-neighbor metric.
• BotSort: appearance_thresh in boxmot/trackers/botsort/botsort.py (lines 46-50) defines the hard cap (maximum 1.0) beyond which embeddings are treated as mismatched.

Practical Implementation Examples

StrongSort with Custom ReID Model

from pathlib import Path
from boxmot.trackers.tracker_zoo import create_tracker
import numpy as np
import cv2

tracker = create_tracker(
    tracker_type="strongsort",
    tracker_config=Path("boxmot/configs/trackers/strongsort.yaml"),
    reid_weights=Path("/data/reid_weights/osnet_x0_25_msmt17.pt"),
    device="cuda",
    half=True,
)

# Detection format: [x1, y1, x2, y2, conf, class]

detections = np.array([...])
frame = cv2.imread("frame.jpg")

# Embeddings extracted automatically via self.model.get_features()

track_outputs = tracker.update(detections, frame)

HybridSort with Enhanced Long-Term Appearance Weight

from boxmot.trackers.tracker_zoo import create_tracker
import yaml
from pathlib import Path

cfg_path = Path("boxmot/configs/trackers/hybridsort.yaml")
with cfg_path.open() as f:
    cfg = yaml.safe_load(f)

# Increase appearance influence for persistent identities

cfg["longterm_reid_weight"]["default"] = 0.7

tmp_cfg = Path("tmp_hybridsort.yaml")
tmp_cfg.write_text(yaml.dump(cfg))

tracker = create_tracker(
    tracker_type="hybridsort",
    tracker_config=tmp_cfg,
    reid_weights=Path("/data/reid_weights/osnet_x0_25_msmt17.pt"),
    device="cpu",
    half=False,
)

outputs = tracker.update(dets, img)

DeepOcSort: Ensuring Embeddings Are Active

tracker = create_tracker(
    tracker_type="deepocsort",
    reid_weights=Path("/data/reid_weights/osnet_x0_25_msmt17.pt"),
    device="cuda",
    half=False,
)

# Verify embedding_off is false in deepocsort.yaml to ensure appearance features are used

Summary

• Select ReID-capable trackers defined in REID_TRACKERS (StrongSort, HybridSort, DeepOcSort, BotSort, BoostTrack) from boxmot/trackers/tracker_zoo.py.
• Supply model weights via the reid_weights argument in create_tracker to load the ReID network.
• Enable long-term memory in HybridSort using with_longterm_reid and tune longterm_reid_weight to balance appearance against motion.
• Control embedding usage in DeepOcSort via the embedding_off flag and w_association_emb weight.
• Set distance thresholds appropriately: max_cos_dist for StrongSort and appearance_thresh for BotSort to determine matching tolerance.

Frequently Asked Questions

Which BoxMOT trackers support ReID appearance embeddings?

The trackers supporting ReID are StrongSort, HybridSort, DeepOcSort, BotSort, and BoostTrack, as enumerated in the REID_TRACKERS list within boxmot/trackers/tracker_zoo.py. These trackers load a ReID model when reid_weights is provided and fuse appearance distances with motion costs during the association step.

What file format should ReID weights use?

BoxMOT accepts pretrained ReID weights as PyTorch .pt checkpoint files. Pass the path to your .pt file (e.g., osnet_x0_25_msmt17.pt) to the reid_weights parameter in create_tracker. The tracker internally loads these weights using the model architecture defined in the tracker's ReID wrapper.

How do I disable appearance features for pure motion tracking?

Set embedding_off to true in boxmot/configs/trackers/deepocsort.yaml (lines 51-55) for DeepOcSort, or simply omit the reid_weights argument when creating trackers that require explicit weight files. For HybridSort, set with_longterm_reid to False and longterm_reid_weight to 0.0 to rely solely on motion cues.

Why do identities still switch despite enabling ReID?

Identity switches persist when the max_cos_dist (StrongSort) or appearance_thresh (BotSort) values are too permissive, allowing visually distinct objects to match. Conversely, overly strict thresholds prevent correct re-identification after occlusion. Tune these thresholds based on your ReID model's training domain and scene complexity, and ensure longterm_reid_weight in HybridSort adequately balances appearance with motion costs.

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