Skip to content

Référence pour ultralytics/trackers/bot_sort.py

Note

Ce fichier est disponible à l'adresse https://github.com/ultralytics/ ultralytics/blob/main/ ultralytics/trackers/bot_sort .py. Si tu repères un problème, aide à le corriger en contribuant à une Pull Request 🛠️. Merci 🙏 !



ultralytics.trackers.bot_sort.BOTrack

Bases : STrack

Une version Ă©tendue de la classe STrack pour YOLOv8, qui ajoute des fonctions de suivi d'objets.

Attributs :

Nom Type Description
shared_kalman KalmanFilterXYWH

Un filtre de Kalman partagé pour toutes les instances de BOTrack.

smooth_feat ndarray

Vecteur de caractéristiques lissé.

curr_feat ndarray

Vecteur de caractéristiques actuel.

features deque

Un deque pour stocker les vecteurs de caractéristiques dont la longueur maximale est définie par feat_history.

alpha float

Facteur de lissage pour la moyenne mobile exponentielle des caractéristiques.

mean ndarray

L'Ă©tat moyen du filtre de Kalman.

covariance ndarray

La matrice de covariance du filtre de Kalman.

MĂ©thodes :

Nom Description
update_features

Mets à jour le vecteur de caractéristiques et lisse-le à l'aide de la moyenne mobile exponentielle.

predict

Prévoit la moyenne et la covariance à l'aide du filtre de Kalman.

re_activate

Réactive une piste avec des caractéristiques mises à jour et éventuellement un nouvel identifiant.

update

Met Ă  jour l'instance YOLOv8 avec la nouvelle piste et l'ID de la trame.

tlwh

Propriété qui permet d'obtenir la position actuelle au format tlwh. (top left x, top left y, width, height).

multi_predict

Prévoit la moyenne et la covariance de plusieurs pistes d'objets à l'aide d'un filtre de Kalman partagé.

convert_coords

Convertit les coordonnées de la boîte de délimitation tlwh au format xywh.

tlwh_to_xywh

Convertir la boîte de délimitation au format xywh (center x, center y, width, height).

Utilisation

bo_track = BOTrack(tlwh, score, cls, feat) bo_track.predict() bo_track.update(new_track, frame_id)

Code source dans ultralytics/trackers/bot_sort.py
class BOTrack(STrack):
    """
    An extended version of the STrack class for YOLOv8, adding object tracking features.

    Attributes:
        shared_kalman (KalmanFilterXYWH): A shared Kalman filter for all instances of BOTrack.
        smooth_feat (np.ndarray): Smoothed feature vector.
        curr_feat (np.ndarray): Current feature vector.
        features (deque): A deque to store feature vectors with a maximum length defined by `feat_history`.
        alpha (float): Smoothing factor for the exponential moving average of features.
        mean (np.ndarray): The mean state of the Kalman filter.
        covariance (np.ndarray): The covariance matrix of the Kalman filter.

    Methods:
        update_features(feat): Update features vector and smooth it using exponential moving average.
        predict(): Predicts the mean and covariance using Kalman filter.
        re_activate(new_track, frame_id, new_id): Reactivates a track with updated features and optionally new ID.
        update(new_track, frame_id): Update the YOLOv8 instance with new track and frame ID.
        tlwh: Property that gets the current position in tlwh format `(top left x, top left y, width, height)`.
        multi_predict(stracks): Predicts the mean and covariance of multiple object tracks using shared Kalman filter.
        convert_coords(tlwh): Converts tlwh bounding box coordinates to xywh format.
        tlwh_to_xywh(tlwh): Convert bounding box to xywh format `(center x, center y, width, height)`.

    Usage:
        bo_track = BOTrack(tlwh, score, cls, feat)
        bo_track.predict()
        bo_track.update(new_track, frame_id)
    """

    shared_kalman = KalmanFilterXYWH()

    def __init__(self, tlwh, score, cls, feat=None, feat_history=50):
        """Initialize YOLOv8 object with temporal parameters, such as feature history, alpha and current features."""
        super().__init__(tlwh, score, cls)

        self.smooth_feat = None
        self.curr_feat = None
        if feat is not None:
            self.update_features(feat)
        self.features = deque([], maxlen=feat_history)
        self.alpha = 0.9

    def update_features(self, feat):
        """Update features vector and smooth it using exponential moving average."""
        feat /= np.linalg.norm(feat)
        self.curr_feat = feat
        if self.smooth_feat is None:
            self.smooth_feat = feat
        else:
            self.smooth_feat = self.alpha * self.smooth_feat + (1 - self.alpha) * feat
        self.features.append(feat)
        self.smooth_feat /= np.linalg.norm(self.smooth_feat)

    def predict(self):
        """Predicts the mean and covariance using Kalman filter."""
        mean_state = self.mean.copy()
        if self.state != TrackState.Tracked:
            mean_state[6] = 0
            mean_state[7] = 0

        self.mean, self.covariance = self.kalman_filter.predict(mean_state, self.covariance)

    def re_activate(self, new_track, frame_id, new_id=False):
        """Reactivates a track with updated features and optionally assigns a new ID."""
        if new_track.curr_feat is not None:
            self.update_features(new_track.curr_feat)
        super().re_activate(new_track, frame_id, new_id)

    def update(self, new_track, frame_id):
        """Update the YOLOv8 instance with new track and frame ID."""
        if new_track.curr_feat is not None:
            self.update_features(new_track.curr_feat)
        super().update(new_track, frame_id)

    @property
    def tlwh(self):
        """Get current position in bounding box format `(top left x, top left y, width, height)`."""
        if self.mean is None:
            return self._tlwh.copy()
        ret = self.mean[:4].copy()
        ret[:2] -= ret[2:] / 2
        return ret

    @staticmethod
    def multi_predict(stracks):
        """Predicts the mean and covariance of multiple object tracks using shared Kalman filter."""
        if len(stracks) <= 0:
            return
        multi_mean = np.asarray([st.mean.copy() for st in stracks])
        multi_covariance = np.asarray([st.covariance for st in stracks])
        for i, st in enumerate(stracks):
            if st.state != TrackState.Tracked:
                multi_mean[i][6] = 0
                multi_mean[i][7] = 0
        multi_mean, multi_covariance = BOTrack.shared_kalman.multi_predict(multi_mean, multi_covariance)
        for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)):
            stracks[i].mean = mean
            stracks[i].covariance = cov

    def convert_coords(self, tlwh):
        """Converts Top-Left-Width-Height bounding box coordinates to X-Y-Width-Height format."""
        return self.tlwh_to_xywh(tlwh)

    @staticmethod
    def tlwh_to_xywh(tlwh):
        """Convert bounding box to format `(center x, center y, width, height)`."""
        ret = np.asarray(tlwh).copy()
        ret[:2] += ret[2:] / 2
        return ret

tlwh property

Obtenir la position actuelle dans le format de la boîte de délimitation (top left x, top left y, width, height).

__init__(tlwh, score, cls, feat=None, feat_history=50)

Initialise l'objet YOLOv8 avec des paramètres temporels, tels que l'historique des caractéristiques, l'alpha et les caractéristiques actuelles.

Code source dans ultralytics/trackers/bot_sort.py
def __init__(self, tlwh, score, cls, feat=None, feat_history=50):
    """Initialize YOLOv8 object with temporal parameters, such as feature history, alpha and current features."""
    super().__init__(tlwh, score, cls)

    self.smooth_feat = None
    self.curr_feat = None
    if feat is not None:
        self.update_features(feat)
    self.features = deque([], maxlen=feat_history)
    self.alpha = 0.9

convert_coords(tlwh)

Convertit les coordonnées de la boîte de délimitation haut-gauche-largeur-hauteur au format X-Y-largeur-hauteur.

Code source dans ultralytics/trackers/bot_sort.py
def convert_coords(self, tlwh):
    """Converts Top-Left-Width-Height bounding box coordinates to X-Y-Width-Height format."""
    return self.tlwh_to_xywh(tlwh)

multi_predict(stracks) staticmethod

Prévoit la moyenne et la covariance de plusieurs pistes d'objets à l'aide d'un filtre de Kalman partagé.

Code source dans ultralytics/trackers/bot_sort.py
@staticmethod
def multi_predict(stracks):
    """Predicts the mean and covariance of multiple object tracks using shared Kalman filter."""
    if len(stracks) <= 0:
        return
    multi_mean = np.asarray([st.mean.copy() for st in stracks])
    multi_covariance = np.asarray([st.covariance for st in stracks])
    for i, st in enumerate(stracks):
        if st.state != TrackState.Tracked:
            multi_mean[i][6] = 0
            multi_mean[i][7] = 0
    multi_mean, multi_covariance = BOTrack.shared_kalman.multi_predict(multi_mean, multi_covariance)
    for i, (mean, cov) in enumerate(zip(multi_mean, multi_covariance)):
        stracks[i].mean = mean
        stracks[i].covariance = cov

predict()

Prévoit la moyenne et la covariance à l'aide du filtre de Kalman.

Code source dans ultralytics/trackers/bot_sort.py
def predict(self):
    """Predicts the mean and covariance using Kalman filter."""
    mean_state = self.mean.copy()
    if self.state != TrackState.Tracked:
        mean_state[6] = 0
        mean_state[7] = 0

    self.mean, self.covariance = self.kalman_filter.predict(mean_state, self.covariance)

re_activate(new_track, frame_id, new_id=False)

Réactive une piste avec des caractéristiques mises à jour et attribue éventuellement un nouvel identifiant.

Code source dans ultralytics/trackers/bot_sort.py
def re_activate(self, new_track, frame_id, new_id=False):
    """Reactivates a track with updated features and optionally assigns a new ID."""
    if new_track.curr_feat is not None:
        self.update_features(new_track.curr_feat)
    super().re_activate(new_track, frame_id, new_id)

tlwh_to_xywh(tlwh) staticmethod

Convertir la boîte de délimitation en format (center x, center y, width, height).

Code source dans ultralytics/trackers/bot_sort.py
@staticmethod
def tlwh_to_xywh(tlwh):
    """Convert bounding box to format `(center x, center y, width, height)`."""
    ret = np.asarray(tlwh).copy()
    ret[:2] += ret[2:] / 2
    return ret

update(new_track, frame_id)

Met Ă  jour l'instance YOLOv8 avec la nouvelle piste et l'ID de la trame.

Code source dans ultralytics/trackers/bot_sort.py
def update(self, new_track, frame_id):
    """Update the YOLOv8 instance with new track and frame ID."""
    if new_track.curr_feat is not None:
        self.update_features(new_track.curr_feat)
    super().update(new_track, frame_id)

update_features(feat)

Mets à jour le vecteur de caractéristiques et lisse-le à l'aide de la moyenne mobile exponentielle.

Code source dans ultralytics/trackers/bot_sort.py
def update_features(self, feat):
    """Update features vector and smooth it using exponential moving average."""
    feat /= np.linalg.norm(feat)
    self.curr_feat = feat
    if self.smooth_feat is None:
        self.smooth_feat = feat
    else:
        self.smooth_feat = self.alpha * self.smooth_feat + (1 - self.alpha) * feat
    self.features.append(feat)
    self.smooth_feat /= np.linalg.norm(self.smooth_feat)



ultralytics.trackers.bot_sort.BOTSORT

Bases : BYTETracker

Une version étendue de la classe BYTETracker pour YOLOv8, conçue pour le suivi d'objets avec ReID et l'algorithme GMC.

Attributs :

Nom Type Description
proximity_thresh float

Seuil de proximité spatiale (IoU) entre les traces et les détections.

appearance_thresh float

Seuil de similarité d'apparence (ReID embeddings) entre les pistes et les détections.

encoder object

Objet permettant de gérer les incorporations ReID, défini à None si ReID n'est pas activé.

gmc GMC

Une instance de l'algorithme GMC pour l'association de données.

args object

Analyse les arguments de la ligne de commande contenant des paramètres de suivi.

MĂ©thodes :

Nom Description
get_kalmanfilter

Renvoie une instance de KalmanFilterXYWH pour le suivi des objets.

init_track

Initialise la piste avec les détections, les scores et les classes.

get_dists

Obtiens les distances entre les traces et les détections à l'aide de l'IoU et (éventuellement) de la ReID.

multi_predict

Prédis et suis plusieurs objets avec le modèle YOLOv8 .

Utilisation

bot_sort = BOTSORT(args, frame_rate) bot_sort.init_track(dets, scores, cls, img) bot_sort.multi_predict(tracks)

Note

La classe est conçue pour fonctionner avec le modèle de détection d'objets YOLOv8 et ne prend en charge ReID que si elle est activée par l'intermédiaire d'args.

Code source dans ultralytics/trackers/bot_sort.py
class BOTSORT(BYTETracker):
    """
    An extended version of the BYTETracker class for YOLOv8, designed for object tracking with ReID and GMC algorithm.

    Attributes:
        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 (object): 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 (object): Parsed command-line arguments containing tracking parameters.

    Methods:
        get_kalmanfilter(): Returns an instance of KalmanFilterXYWH for object tracking.
        init_track(dets, scores, cls, img): Initialize track with detections, scores, and classes.
        get_dists(tracks, detections): Get distances between tracks and detections using IoU and (optionally) ReID.
        multi_predict(tracks): Predict and track multiple objects with YOLOv8 model.

    Usage:
        bot_sort = BOTSORT(args, frame_rate)
        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.
    """

    def __init__(self, args, frame_rate=30):
        """Initialize YOLOv8 object with ReID module and GMC algorithm."""
        super().__init__(args, frame_rate)
        # ReID module
        self.proximity_thresh = args.proximity_thresh
        self.appearance_thresh = args.appearance_thresh

        if args.with_reid:
            # Haven't supported BoT-SORT(reid) yet
            self.encoder = None
        self.gmc = GMC(method=args.gmc_method)

    def get_kalmanfilter(self):
        """Returns an instance of KalmanFilterXYWH for object tracking."""
        return KalmanFilterXYWH()

    def init_track(self, dets, scores, cls, img=None):
        """Initialize track with detections, scores, and classes."""
        if len(dets) == 0:
            return []
        if self.args.with_reid and self.encoder is not None:
            features_keep = self.encoder.inference(img, dets)
            return [BOTrack(xyxy, s, c, f) for (xyxy, s, c, f) in zip(dets, scores, cls, features_keep)]  # detections
        else:
            return [BOTrack(xyxy, s, c) for (xyxy, s, c) in zip(dets, scores, cls)]  # detections

    def get_dists(self, tracks, detections):
        """Get distances between tracks and detections using IoU and (optionally) ReID embeddings."""
        dists = matching.iou_distance(tracks, detections)
        dists_mask = dists > self.proximity_thresh

        # TODO: mot20
        # if not self.args.mot20:
        dists = matching.fuse_score(dists, detections)

        if self.args.with_reid and self.encoder is not None:
            emb_dists = matching.embedding_distance(tracks, detections) / 2.0
            emb_dists[emb_dists > self.appearance_thresh] = 1.0
            emb_dists[dists_mask] = 1.0
            dists = np.minimum(dists, emb_dists)
        return dists

    def multi_predict(self, tracks):
        """Predict and track multiple objects with YOLOv8 model."""
        BOTrack.multi_predict(tracks)

    def reset(self):
        """Reset tracker."""
        super().reset()
        self.gmc.reset_params()

__init__(args, frame_rate=30)

Initialise l'objet YOLOv8 avec le module ReID et l'algorithme GMC.

Code source dans ultralytics/trackers/bot_sort.py
def __init__(self, args, frame_rate=30):
    """Initialize YOLOv8 object with ReID module and GMC algorithm."""
    super().__init__(args, frame_rate)
    # ReID module
    self.proximity_thresh = args.proximity_thresh
    self.appearance_thresh = args.appearance_thresh

    if args.with_reid:
        # Haven't supported BoT-SORT(reid) yet
        self.encoder = None
    self.gmc = GMC(method=args.gmc_method)

get_dists(tracks, detections)

Obtiens les distances entre les traces et les détections en utilisant les données de l'IoU et (optionnellement) les données de ReID.

Code source dans ultralytics/trackers/bot_sort.py
def get_dists(self, tracks, detections):
    """Get distances between tracks and detections using IoU and (optionally) ReID embeddings."""
    dists = matching.iou_distance(tracks, detections)
    dists_mask = dists > self.proximity_thresh

    # TODO: mot20
    # if not self.args.mot20:
    dists = matching.fuse_score(dists, detections)

    if self.args.with_reid and self.encoder is not None:
        emb_dists = matching.embedding_distance(tracks, detections) / 2.0
        emb_dists[emb_dists > self.appearance_thresh] = 1.0
        emb_dists[dists_mask] = 1.0
        dists = np.minimum(dists, emb_dists)
    return dists

get_kalmanfilter()

Renvoie une instance de KalmanFilterXYWH pour le suivi des objets.

Code source dans ultralytics/trackers/bot_sort.py
def get_kalmanfilter(self):
    """Returns an instance of KalmanFilterXYWH for object tracking."""
    return KalmanFilterXYWH()

init_track(dets, scores, cls, img=None)

Initialise la piste avec les détections, les scores et les classes.

Code source dans ultralytics/trackers/bot_sort.py
def init_track(self, dets, scores, cls, img=None):
    """Initialize track with detections, scores, and classes."""
    if len(dets) == 0:
        return []
    if self.args.with_reid and self.encoder is not None:
        features_keep = self.encoder.inference(img, dets)
        return [BOTrack(xyxy, s, c, f) for (xyxy, s, c, f) in zip(dets, scores, cls, features_keep)]  # detections
    else:
        return [BOTrack(xyxy, s, c) for (xyxy, s, c) in zip(dets, scores, cls)]  # detections

multi_predict(tracks)

Prédis et suis plusieurs objets avec le modèle YOLOv8 .

Code source dans ultralytics/trackers/bot_sort.py
def multi_predict(self, tracks):
    """Predict and track multiple objects with YOLOv8 model."""
    BOTrack.multi_predict(tracks)

reset()

Remets le tracker à zéro.

Code source dans ultralytics/trackers/bot_sort.py
def reset(self):
    """Reset tracker."""
    super().reset()
    self.gmc.reset_params()





Created 2023-11-12, Updated 2024-06-02
Authors: glenn-jocher (5), Burhan-Q (1), Laughing-q (1)