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	Optional[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

@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 (Optional[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
    class_id: np.ndarray
    confidence: Optional[np.ndarray] = None
    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.class_id, np.ndarray) and self.class_id.shape == (n,)),
            self.confidence is None
            or (
                isinstance(self.confidence, np.ndarray)
                and self.confidence.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 None or 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,
    ) -> Iterator[Tuple[np.ndarray, Optional[float], int, Optional[Union[str, int]]]]:
        """
        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] if self.confidence is not None else None,
                self.class_id[i],
                self.tracker_id[i] if self.tracker_id is not None else None,
            )

    def __eq__(self, other: Detections):
        return all(
            [
                np.array_equal(self.xyxy, other.xyxy),
                any(
                    [
                        self.confidence is None and other.confidence is None,
                        np.array_equal(self.confidence, other.confidence),
                    ]
                ),
                np.array_equal(self.class_id, other.class_id),
                any(
                    [
                        self.tracker_id is None and other.tracker_id is None,
                        np.array_equal(self.tracker_id, other.tracker_id),
                    ]
                ),
            ]
        )

    @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)[0]
            >>> 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),
        )

    @classmethod
    def from_transformers(cls, transformers_results: dict):
        return cls(
            xyxy=transformers_results["boxes"].cpu().numpy(),
            confidence=transformers_results["scores"].cpu().numpy(),
            class_id=transformers_results["labels"].cpu().numpy().astype(int),
        )

    @classmethod
    def from_detectron2(cls, detectron2_results):
        return cls(
            xyxy=detectron2_results["instances"].pred_boxes.tensor.cpu().numpy(),
            confidence=detectron2_results["instances"].scores.cpu().numpy(),
            class_id=detectron2_results["instances"]
            .pred_classes.cpu()
            .numpy()
            .astype(int),
        )

    @classmethod
    def from_coco_annotations(cls, coco_annotation: dict):
        xyxy, class_id = [], []

        for annotation in coco_annotation:
            x_min, y_min, width, height = annotation["bbox"]
            xyxy.append([x_min, y_min, x_min + width, y_min + height])
            class_id.append(annotation["category_id"])

        return cls(xyxy=np.array(xyxy), class_id=np.array(class_id))

    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 == bool or index.dtype == int
        ):
            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)}."
        )

    @property
    def area(self) -> np.ndarray:
        return (self.xyxy[:, 3] - self.xyxy[:, 1]) * (self.xyxy[:, 2] - self.xyxy[:, 0])

    def with_nms(self, threshold: float = 0.5) -> Detections:
        assert (
            self.confidence is not None
        ), f"Detections confidence must be given for NMS to be executed."
        indices = non_max_suppression(self.xyxy, self.confidence, threshold=threshold)
        return self[indices]

__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

def __iter__(
    self,
) -> Iterator[Tuple[np.ndarray, Optional[float], int, Optional[Union[str, int]]]]:
    """
    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] if self.confidence is not None else None,
            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

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

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

@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)[0]
>>> detections = Detections.from_yolov8(results)

Source code in supervision/detection/core.py

@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)[0]
        >>> 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

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.")