🔎 Detections
Detections represent bounding box, segmentation, or classification results.
Overview
The Detections class encapsulates a wide array of detection data. The class can represent bounding box, segmentation, and classification results.
Arguments
Type of detection (DetectionType.BOUNDING_BOX, DetectionType.SEGMENTATION, or DetectionType.CLASSIFICATION).
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 for each detection, indexing into classes.
Array of class names, indexed by class_ids.
Additional custom data related to detections (Default: empty dictionary).
Segmentation masks for each detection, required for segmentation types.
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
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()
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"]
)
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)
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)
Creates an empty Detections object.
Returns:
Detections: An empty bounding box Detections object.
empty_detections = Detections.empty()
Converts the Detections instance to a supervision.Detections instance.
Returns:
sv.Detections: A supervision Detections instance.
sv_detections = detections.to_supervision()
Properties
Returns the list of confidence scores associated with the detections.
scores = detections.confidence_scores
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
Returns a NumPy array containing the area of each bounding box.
box_areas = detections.box_area
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.