​
Overview

The Detections class encapsulates a wide array of detection data. The class can represent bounding box, segmentation, and classification results.

​
Arguments

​
detection_type
DetectionType
required

Type of detection (DetectionType.BOUNDING_BOX, DetectionType.SEGMENTATION, or DetectionType.CLASSIFICATION).

​
xyxy
np.ndarray[np.float32]
required

Coordinates of bounding boxes [x1, y1, x2, y2] for each detection, where (x1, y1) refers to the top left coordinate and (x2, y2) refers to the bottom right coordinate.

​
class_ids
np.ndarray[np.int32]]
required

Class IDs for each detection, indexing into classes.

​
classes
np.ndarray[np.object_]
required

Array of class names, indexed by class_ids.

​
data
Dict[str, Union[np.ndarray, List]]

Additional custom data related to detections (Default: empty dictionary).

​
masks
np.ndarray[np.float32]

Segmentation masks for each detection, required for segmentation types.

​
confidence
np.ndarray[np.float32]

Confidence scores for each detection.

​
Examples

​
Bounding Box Detections

bounding_box_detections = Detections(
    xyxy=np.array([[50, 50, 100, 100], [150, 150, 200, 200]]),
    detection_type=DetectionType.BOUNDING_BOX,
    class_ids=np.array([0, 1]),
    classes=np.array(["cat", "dog"]),
    confidence=np.array([0.9, 0.8])
)

There are two bounding boxes in this bounding box Detections object: the box with coordinates (50, 50) and (100, 100) is of class “cat” with 90% confidence, and the box with coordinates (150, 150) and (200, 200) is of class “dog” with 80% confidence.

​
Classification Detections

classification_detections = Detections.from_classification(
    assigned_classes=["apple", "fruit"]
    all_classes=["apple", "orange", "banana", "fruit", "vegetable"]
)

A classification detection is created with multiple classifications: “apple” and “fruit”.

The resulting Detections object looks like this:

Detections(
      xyxy=np.zeros((len(assigned_classes), 4)),
      class_ids=np.array([all_classes.index(c) for c in assigned_classes]),
      classes=np.array(all_classes),
      detection_type=DetectionType.CLASSIFICATION
)

​
Segmentation Detections

We will support Segmentation detections shortly.

​
Methods

​
Detections.split()

Splits the Detections object into a list of Detections objects, each containing a single detection.

Returns:

  • List['Detections']: A list of Detections objects, each containing a single detection.
splits = detections.split()
​
Detections.from_classification(assigned_classes)

Creates a Detections instance from a list of class names

Parameters:

  • assigned_classes (List[str]): The class name(s) that have been assigned to the classification detection.
  • all_classes (Optional[List[str]]): List of strings representing all possible class names that can be assigned in the classification detection.

Returns:

  • Detections: A classification Detections object.
classification_detections = Detections.from_classification(
   assigned_classes=["cat"],
   all_classes=["cat", "dog", "mouse"]
)
​
Detections.from_yolov5(yolov5_results)

Creates a Detections instance from a YOLOv5 inference result.

Parameters:

  • yolov5_results (yolov5.models.common.Detections): The output Detections instance from YOLOv5.

Returns:

  • Detections: A bounding box Detections object.
import torch

model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
result = model("path/to/image.jpg")
detections = Detections.from_yolov5(result)
​
Detections.from_ultralytics(ultralytics_results)

Creates a Detections instance from an Ultralytics YOLOv8 inference result.

Parameters:

  • ultralytics_results (ultralytics.yolo.engine.results.Results): The output Results instance from YOLOv8.

Returns:

  • Detections: A bounding box or segmentation Detections object.
from ultralytics import YOLO

model = YOLO('yolov8s.pt')
result = model("path/to/image.jpg")[0]
detections = Detections.from_ultralytics(result)
​
Detections.empty()

Creates an empty Detections object.

Returns:

  • Detections: An empty bounding box Detections object.
empty_detections = Detections.empty()
​
Detections.to_supervision()

Converts the Detections instance to a supervision.Detections instance.

Returns:

  • sv.Detections: A supervision Detections instance.
sv_detections = detections.to_supervision()

​
Properties

​
confidence_scores

Returns the list of confidence scores associated with the detections.

scores = detections.confidence_scores
​
area

Returns a NumPy array containing the area of each detection.

Specifically, if segmentation masks are available, a NumPy array containing the area of each mask is returned. Otherwise, a NumPy array containing the area of each bounding box is returned.

areas = detections.area
​
box_area

Returns a NumPy array containing the area of each bounding box.

box_areas = detections.box_area
​
class_names

Return the list of class names associated with the detections.

names = detections.class_names

​
Example

​
Creating a Detection from YOLOv5

import cv2
import torch

image = cv2.imread("path/to/image.jpg")
model = torch.hub.load('ultralytics/yolov5', 'yolov5s')
result = model(image)
detections = Detections.from_yolov5(result)

​
Converting to Supervision

sv_detections = detections.to_supervision()

This documentation covers the essential usage of the Detections class, including creation, manipulation, and conversion of detection data.