Reference for ultralytics/trackers/bot_sort.py
Note
This file is available at https://github.com/ultralytics/ultralytics/blob/main/ultralytics/trackers/bot_sort.py. If you spot a problem please help fix it by contributing a Pull Request 🛠️. Thank you 🙏!
ultralytics.trackers.bot_sort.BOTrack
BOTrack(tlwh, score, cls, feat=None, feat_history=50)
Bases: STrack
An extended version of the STrack class for YOLOv8, adding object tracking features.
This class extends the STrack class to include additional functionalities for object tracking, such as feature smoothing, Kalman filter prediction, and reactivation of tracks.
Attributes:
Name | Type | Description |
---|---|---|
shared_kalman |
KalmanFilterXYWH
|
A shared Kalman filter for all instances of BOTrack. |
smooth_feat |
ndarray
|
Smoothed feature vector. |
curr_feat |
ndarray
|
Current feature vector. |
features |
deque
|
A deque to store feature vectors with a maximum length defined by |
alpha |
float
|
Smoothing factor for the exponential moving average of features. |
mean |
ndarray
|
The mean state of the Kalman filter. |
covariance |
ndarray
|
The covariance matrix of the Kalman filter. |
Methods:
Name | Description |
---|---|
update_features |
Update features vector and smooth it using exponential moving average. |
predict |
Predict the mean and covariance using Kalman filter. |
re_activate |
Reactivate a track with updated features and optionally new ID. |
update |
Update the track with new detection and frame ID. |
tlwh |
Property that gets the current position in tlwh format |
multi_predict |
Predict the mean and covariance of multiple object tracks using shared Kalman filter. |
convert_coords |
Convert tlwh bounding box coordinates to xywh format. |
tlwh_to_xywh |
Convert bounding box to xywh format |
Examples:
Create a BOTrack instance and update its features
>>> bo_track = BOTrack(tlwh=[100, 50, 80, 40], score=0.9, cls=1, feat=np.random.rand(128))
>>> bo_track.predict()
>>> new_track = BOTrack(tlwh=[110, 60, 80, 40], score=0.85, cls=1, feat=np.random.rand(128))
>>> bo_track.update(new_track, frame_id=2)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tlwh
|
ndarray
|
Bounding box coordinates in tlwh format (top left x, top left y, width, height). |
required |
score
|
float
|
Confidence score of the detection. |
required |
cls
|
int
|
Class ID of the detected object. |
required |
feat
|
ndarray | None
|
Feature vector associated with the detection. |
None
|
feat_history
|
int
|
Maximum length of the feature history deque. |
50
|
Examples:
Initialize a BOTrack object with bounding box, score, class ID, and feature vector
>>> tlwh = np.array([100, 50, 80, 120])
>>> score = 0.9
>>> cls = 1
>>> feat = np.random.rand(128)
>>> bo_track = BOTrack(tlwh, score, cls, feat)
Source code in ultralytics/trackers/bot_sort.py
54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 |
|
tlwh
property
tlwh
Return the current bounding box position in (top left x, top left y, width, height)
format.
convert_coords
convert_coords(tlwh)
Convert tlwh bounding box coordinates to xywh format.
Source code in ultralytics/trackers/bot_sort.py
139 140 141 |
|
multi_predict
staticmethod
multi_predict(stracks)
Predict the mean and covariance for multiple object tracks using a shared Kalman filter.
Source code in ultralytics/trackers/bot_sort.py
123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 |
|
predict
predict()
Predict the object's future state using the Kalman filter to update its mean and covariance.
Source code in ultralytics/trackers/bot_sort.py
93 94 95 96 97 98 99 100 |
|
re_activate
re_activate(new_track, frame_id, new_id=False)
Reactivate a track with updated features and optionally assign a new ID.
Source code in ultralytics/trackers/bot_sort.py
102 103 104 105 106 |
|
tlwh_to_xywh
staticmethod
tlwh_to_xywh(tlwh)
Convert bounding box from tlwh (top-left-width-height) to xywh (center-x-center-y-width-height) format.
Source code in ultralytics/trackers/bot_sort.py
143 144 145 146 147 148 |
|
update
update(new_track, frame_id)
Update the track with new detection information and the current frame ID.
Source code in ultralytics/trackers/bot_sort.py
108 109 110 111 112 |
|
update_features
update_features(feat)
Update the feature vector and apply exponential moving average smoothing.
Source code in ultralytics/trackers/bot_sort.py
82 83 84 85 86 87 88 89 90 91 |
|
ultralytics.trackers.bot_sort.BOTSORT
BOTSORT(args, frame_rate=30)
Bases: BYTETracker
An extended version of the BYTETracker class for YOLOv8, designed for object tracking with ReID and GMC algorithm.
Attributes:
Name | Type | Description |
---|---|---|
proximity_thresh |
float
|
Threshold for spatial proximity (IoU) between tracks and detections. |
appearance_thresh |
float
|
Threshold for appearance similarity (ReID embeddings) between tracks and detections. |
encoder |
Any
|
Object to handle ReID embeddings, set to None if ReID is not enabled. |
gmc |
GMC
|
An instance of the GMC algorithm for data association. |
args |
Any
|
Parsed command-line arguments containing tracking parameters. |
Methods:
Name | Description |
---|---|
get_kalmanfilter |
Return an instance of KalmanFilterXYWH for object tracking. |
init_track |
Initialize track with detections, scores, and classes. |
get_dists |
Get distances between tracks and detections using IoU and (optionally) ReID. |
multi_predict |
Predict and track multiple objects with YOLOv8 model. |
reset |
Reset the BOTSORT tracker to its initial state. |
Examples:
Initialize BOTSORT and process detections
>>> bot_sort = BOTSORT(args, frame_rate=30)
>>> bot_sort.init_track(dets, scores, cls, img)
>>> bot_sort.multi_predict(tracks)
Note
The class is designed to work with the YOLOv8 object detection model and supports ReID only if enabled via args.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
args
|
object
|
Parsed command-line arguments containing tracking parameters. |
required |
frame_rate
|
int
|
Frame rate of the video being processed. |
30
|
Examples:
Initialize BOTSORT with command-line arguments and a specified frame rate:
>>> args = parse_args()
>>> bot_sort = BOTSORT(args, frame_rate=30)
Source code in ultralytics/trackers/bot_sort.py
179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 |
|
get_dists
get_dists(tracks, detections)
Calculate distances between tracks and detections using IoU and optionally ReID embeddings.
Source code in ultralytics/trackers/bot_sort.py
220 221 222 223 224 225 226 227 228 229 230 231 232 233 |
|
get_kalmanfilter
get_kalmanfilter()
Return an instance of KalmanFilterXYWH for predicting and updating object states in the tracking process.
Source code in ultralytics/trackers/bot_sort.py
206 207 208 |
|
init_track
init_track(dets, scores, cls, img=None)
Initialize object tracks using detection bounding boxes, scores, class labels, and optional ReID features.
Source code in ultralytics/trackers/bot_sort.py
210 211 212 213 214 215 216 217 218 |
|
multi_predict
multi_predict(tracks)
Predict the mean and covariance of multiple object tracks using a shared Kalman filter.
Source code in ultralytics/trackers/bot_sort.py
235 236 237 |
|
reset
reset()
Reset the BOTSORT tracker to its initial state, clearing all tracked objects and internal states.
Source code in ultralytics/trackers/bot_sort.py
239 240 241 242 |
|
ultralytics.trackers.bot_sort.ReID
ReID(model)
YOLO model as encoder for re-identification.
Source code in ultralytics/trackers/bot_sort.py
248 249 250 251 252 253 |
|
__call__
__call__(img, dets)
Extract embeddings for detected objects.
Source code in ultralytics/trackers/bot_sort.py
255 256 257 258 |
|