Skip to content

Core

Detections

Data class containing information about the detections in a video frame.

Attributes:

Name Type Description
xyxy ndarray

An array of shape (n, 4) containing the bounding boxes coordinates in format [x1, y1, x2, y2]
confidence ndarray

An array of shape (n,) containing the confidence scores of the detections.
class_id ndarray

An array of shape (n,) containing the class ids of the detections.
tracker_id Optional[ndarray]

An array of shape (n,) containing the tracker ids of the detections.
Source code in supervision/detection/core.py 
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 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
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
@dataclass
class Detections:
    """
    Data class containing information about the detections in a video frame.

    Attributes:
        xyxy (np.ndarray): An array of shape `(n, 4)` containing the bounding boxes coordinates in format `[x1, y1, x2, y2]`
        confidence (np.ndarray): An array of shape `(n,)` containing the confidence scores of the detections.
        class_id (np.ndarray): An array of shape `(n,)` containing the class ids of the detections.
        tracker_id (Optional[np.ndarray]): An array of shape `(n,)` containing the tracker ids of the detections.
    """

    xyxy: np.ndarray
    confidence: np.ndarray
    class_id: np.ndarray
    tracker_id: Optional[np.ndarray] = None

    def __post_init__(self):
        n = len(self.xyxy)
        validators = [
            (isinstance(self.xyxy, np.ndarray) and self.xyxy.shape == (n, 4)),
            (isinstance(self.confidence, np.ndarray) and self.confidence.shape == (n,)),
            (isinstance(self.class_id, np.ndarray) and self.class_id.shape == (n,)),
            self.tracker_id is None
            or (
                isinstance(self.tracker_id, np.ndarray)
                and self.tracker_id.shape == (n,)
            ),
        ]
        if not all(validators):
            raise ValueError(
                "xyxy must be 2d np.ndarray with (n, 4) shape, "
                "confidence must be 1d np.ndarray with (n,) shape, "
                "class_id must be 1d np.ndarray with (n,) shape, "
                "tracker_id must be None or 1d np.ndarray with (n,) shape"
            )

    def __len__(self):
        """
        Returns the number of detections in the Detections object.
        """
        return len(self.xyxy)

    def __iter__(self):
        """
        Iterates over the Detections object and yield a tuple of `(xyxy, confidence, class_id, tracker_id)` for each detection.
        """
        for i in range(len(self.xyxy)):
            yield (
                self.xyxy[i],
                self.confidence[i],
                self.class_id[i],
                self.tracker_id[i] if self.tracker_id is not None else None,
            )

    @classmethod
    def from_yolov5(cls, yolov5_detections):
        """
        Creates a Detections instance from a YOLOv5 output Detections

        Attributes:
            yolov5_detections (yolov5.models.common.Detections): The output Detections instance from YOLOv5

        Returns:

        Example:
            ```python
            >>> import torch
            >>> from supervision import Detections

            >>> model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
            >>> results = model(frame)
            >>> detections = Detections.from_yolov5(results)
            ```
        """
        yolov5_detections_predictions = yolov5_detections.pred[0].cpu().cpu().numpy()
        return cls(
            xyxy=yolov5_detections_predictions[:, :4],
            confidence=yolov5_detections_predictions[:, 4],
            class_id=yolov5_detections_predictions[:, 5].astype(int),
        )

    @classmethod
    def from_yolov8(cls, yolov8_results):
        """
        Creates a Detections instance from a YOLOv8 output Results

        Attributes:
            yolov8_results (ultralytics.yolo.engine.results.Results): The output Results instance from YOLOv8

        Returns:

        Example:
            ```python
            >>> from ultralytics import YOLO
            >>> from supervision import Detections

            >>> model = YOLO('yolov8s.pt')
            >>> results = model(frame)
            >>> detections = Detections.from_yolov8(results)
            ```
        """
        return cls(
            xyxy=yolov8_results.boxes.xyxy.cpu().numpy(),
            confidence=yolov8_results.boxes.conf.cpu().numpy(),
            class_id=yolov8_results.boxes.cls.cpu().numpy().astype(int),
        )

    def filter(self, mask: np.ndarray, inplace: bool = False) -> Optional[Detections]:
        """
        Filter the detections by applying a mask.

        Attributes:
            mask (np.ndarray): A mask of shape `(n,)` containing a boolean value for each detection indicating if it should be included in the filtered detections
            inplace (bool): If True, the original data will be modified and self will be returned.

        Returns:
            Optional[np.ndarray]: A new instance of Detections with the filtered detections, if inplace is set to `False`. `None` otherwise.
        """
        if inplace:
            self.xyxy = self.xyxy[mask]
            self.confidence = self.confidence[mask]
            self.class_id = self.class_id[mask]
            self.tracker_id = (
                self.tracker_id[mask] if self.tracker_id is not None else None
            )
            return self
        else:
            return Detections(
                xyxy=self.xyxy[mask],
                confidence=self.confidence[mask],
                class_id=self.class_id[mask],
                tracker_id=self.tracker_id[mask]
                if self.tracker_id is not None
                else None,
            )

    def get_anchor_coordinates(self, anchor: Position) -> np.ndarray:
        """
        Returns the bounding box coordinates for a specific anchor.

        Properties:
            anchor (Position): Position of bounding box anchor for which to return the coordinates.

        Returns:
            np.ndarray: An array of shape `(n, 2)` containing the bounding box anchor coordinates in format `[x, y]`.
        """
        if anchor == Position.CENTER:
            return np.array(
                [
                    (self.xyxy[:, 0] + self.xyxy[:, 2]) / 2,
                    (self.xyxy[:, 1] + self.xyxy[:, 3]) / 2,
                ]
            ).transpose()
        elif anchor == Position.BOTTOM_CENTER:
            return np.array(
                [(self.xyxy[:, 0] + self.xyxy[:, 2]) / 2, self.xyxy[:, 3]]
            ).transpose()

        raise ValueError(f"{anchor} is not supported.")

    def __getitem__(self, index: np.ndarray) -> Detections:
        if isinstance(index, np.ndarray) and index.dtype == np.bool:
            return Detections(
                xyxy=self.xyxy[index],
                confidence=self.confidence[index],
                class_id=self.class_id[index],
                tracker_id=self.tracker_id[index]
                if self.tracker_id is not None
                else None,
            )
        raise TypeError(
            f"Detections.__getitem__ not supported for index of type {type(index)}."
        )

__iter__()

Iterates over the Detections object and yield a tuple of (xyxy, confidence, class_id, tracker_id) for each detection.

Source code in supervision/detection/core.py 
56
57
58
59
60
61
62
63
64
65
66
def __iter__(self):
    """
    Iterates over the Detections object and yield a tuple of `(xyxy, confidence, class_id, tracker_id)` for each detection.
    """
    for i in range(len(self.xyxy)):
        yield (
            self.xyxy[i],
            self.confidence[i],
            self.class_id[i],
            self.tracker_id[i] if self.tracker_id is not None else None,
        )

__len__()

Returns the number of detections in the Detections object.

Source code in supervision/detection/core.py 
50
51
52
53
54
def __len__(self):
    """
    Returns the number of detections in the Detections object.
    """
    return len(self.xyxy)

filter(mask, inplace=False)

Filter the detections by applying a mask.

Attributes:

Name Type Description
mask ndarray

A mask of shape (n,) containing a boolean value for each detection indicating if it should be included in the filtered detections
inplace bool

If True, the original data will be modified and self will be returned.

Returns:

Type Description
Optional[Detections]

Optional[np.ndarray]: A new instance of Detections with the filtered detections, if inplace is set to False. None otherwise.
Source code in supervision/detection/core.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def filter(self, mask: np.ndarray, inplace: bool = False) -> Optional[Detections]:
    """
    Filter the detections by applying a mask.

    Attributes:
        mask (np.ndarray): A mask of shape `(n,)` containing a boolean value for each detection indicating if it should be included in the filtered detections
        inplace (bool): If True, the original data will be modified and self will be returned.

    Returns:
        Optional[np.ndarray]: A new instance of Detections with the filtered detections, if inplace is set to `False`. `None` otherwise.
    """
    if inplace:
        self.xyxy = self.xyxy[mask]
        self.confidence = self.confidence[mask]
        self.class_id = self.class_id[mask]
        self.tracker_id = (
            self.tracker_id[mask] if self.tracker_id is not None else None
        )
        return self
    else:
        return Detections(
            xyxy=self.xyxy[mask],
            confidence=self.confidence[mask],
            class_id=self.class_id[mask],
            tracker_id=self.tracker_id[mask]
            if self.tracker_id is not None
            else None,
        )

from_yolov5(yolov5_detections) classmethod

Creates a Detections instance from a YOLOv5 output Detections

Attributes:

Name Type Description
yolov5_detections Detections

The output Detections instance from YOLOv5

Returns:

Example 
>>> import torch
>>> from supervision import Detections

>>> model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
>>> results = model(frame)
>>> detections = Detections.from_yolov5(results)
Source code in supervision/detection/core.py 
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
@classmethod
def from_yolov5(cls, yolov5_detections):
    """
    Creates a Detections instance from a YOLOv5 output Detections

    Attributes:
        yolov5_detections (yolov5.models.common.Detections): The output Detections instance from YOLOv5

    Returns:

    Example:
        ```python
        >>> import torch
        >>> from supervision import Detections

        >>> model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
        >>> results = model(frame)
        >>> detections = Detections.from_yolov5(results)
        ```
    """
    yolov5_detections_predictions = yolov5_detections.pred[0].cpu().cpu().numpy()
    return cls(
        xyxy=yolov5_detections_predictions[:, :4],
        confidence=yolov5_detections_predictions[:, 4],
        class_id=yolov5_detections_predictions[:, 5].astype(int),
    )

from_yolov8(yolov8_results) classmethod

Creates a Detections instance from a YOLOv8 output Results

Attributes:

Name Type Description
yolov8_results Results

The output Results instance from YOLOv8

Returns:

Example 
>>> from ultralytics import YOLO
>>> from supervision import Detections

>>> model = YOLO('yolov8s.pt')
>>> results = model(frame)
>>> detections = Detections.from_yolov8(results)
Source code in supervision/detection/core.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
@classmethod
def from_yolov8(cls, yolov8_results):
    """
    Creates a Detections instance from a YOLOv8 output Results

    Attributes:
        yolov8_results (ultralytics.yolo.engine.results.Results): The output Results instance from YOLOv8

    Returns:

    Example:
        ```python
        >>> from ultralytics import YOLO
        >>> from supervision import Detections

        >>> model = YOLO('yolov8s.pt')
        >>> results = model(frame)
        >>> detections = Detections.from_yolov8(results)
        ```
    """
    return cls(
        xyxy=yolov8_results.boxes.xyxy.cpu().numpy(),
        confidence=yolov8_results.boxes.conf.cpu().numpy(),
        class_id=yolov8_results.boxes.cls.cpu().numpy().astype(int),
    )

get_anchor_coordinates(anchor)

Returns the bounding box coordinates for a specific anchor.

Properties

anchor (Position): Position of bounding box anchor for which to return the coordinates.

Returns:

Type Description
ndarray

np.ndarray: An array of shape (n, 2) containing the bounding box anchor coordinates in format [x, y].
Source code in supervision/detection/core.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
def get_anchor_coordinates(self, anchor: Position) -> np.ndarray:
    """
    Returns the bounding box coordinates for a specific anchor.

    Properties:
        anchor (Position): Position of bounding box anchor for which to return the coordinates.

    Returns:
        np.ndarray: An array of shape `(n, 2)` containing the bounding box anchor coordinates in format `[x, y]`.
    """
    if anchor == Position.CENTER:
        return np.array(
            [
                (self.xyxy[:, 0] + self.xyxy[:, 2]) / 2,
                (self.xyxy[:, 1] + self.xyxy[:, 3]) / 2,
            ]
        ).transpose()
    elif anchor == Position.BOTTOM_CENTER:
        return np.array(
            [(self.xyxy[:, 0] + self.xyxy[:, 2]) / 2, self.xyxy[:, 3]]
        ).transpose()

    raise ValueError(f"{anchor} is not supported.")