# How to Configure ReID Appearance Embeddings for Identity Persistence in BoxMOT

> Configure ReID appearance embeddings for identity persistence in BoxMOT. Learn to select ReID trackers, use pretrained weights, and tune parameters for accurate tracking.

- Repository: [Mike/boxmot](https://github.com/mikel-brostrom/boxmot)
- Tags: how-to-guide
- Published: 2026-03-07

---

**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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/boxmot/trackers/tracker_zoo.py) (lines 75-80) accepts a `reid_weights` parameter that injects the model path into compatible trackers.

```python
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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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

```python
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

```python
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

```python
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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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`](https://github.com/mikel-brostrom/boxmot/blob/main/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.