- Added an end-to-end cookbook focused on oriented bounding boxes (OBB), demonstrating how OBB detections differ from axis-aligned boxes, why oriented overlap and NMS matter, how to use footprint-based filtering with `Detections.area`, and how to export annotations in YOLO OBB format. - Added visual examples that clearly compare axis-aligned and oriented boxes, including a close-up showing how axis-aligned envelopes can significantly overestimate object footprints for angled objects. - Improved the cookbook narrative to center on the practical consequences of using oriented versus axis-aligned boxes, including tighter localization and more appropriate NMS behavior for densely packed, rotated objects. - Updated cookbook references, naming, dependency versions, image attribution, and changelog links to align with the released 0.29.0 documentation. - Fixed the 0.29.0 changelog by removing a duplicate `Detections.area` entry and keeping the more accurate correctness-fix classification. --------- Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com> Co-authored-by: claude[bot] <209825114+claude[bot]@users.noreply.github.com>
1.8 MiB
Vendored
1.8 MiB
Vendored
In [1]:
%pip install -q "supervision>=0.29.0" ultralyticsIn [2]:
import cv2
import numpy as np
import os
import supervision as sv
from ultralytics import YOLO
print(sv.__version__)0.29.0
In [3]:
import urllib.request
urllib.request.urlretrieve("https://ultralytics.com/images/boats.jpg", "boats.jpg")
image = cv2.imread("boats.jpg")
model = YOLO("yolo11n-obb.pt")
detections = sv.Detections.from_ultralytics(model(image, imgsz=1024, verbose=False)[0])
# the model also tags the piers themselves as `harbor`; keep the boats
detections = detections[detections.data["class_name"] == "ship"]
print(f"Boats: {len(detections)}")
annotated = sv.OrientedBoxAnnotator(thickness=2).annotate(image.copy(), detections)
sv.plot_image(annotated, size=(12, 7))Boats: 172
In [4]:
print("xyxy (axis-aligned):")
print(detections.xyxy[0])
print()
print('data["xyxyxyxy"] (rotated corners):')
print(detections.data["xyxyxyxy"][0])xyxy (axis-aligned): [ 282.67 415.45 363.42 468.92] data["xyxyxyxy"] (rotated corners): [[ 353.33 468.92] [ 363.42 443.53] [ 292.76 415.45] [ 282.67 440.84]]
In [5]:
# zoom into one cluster of berths to compare the two box types on many boats
x1, y1, x2, y2 = 980, 250, 1700, 850
cx = (detections.xyxy[:, 0] + detections.xyxy[:, 2]) / 2
cy = (detections.xyxy[:, 1] + detections.xyxy[:, 3]) / 2
cluster = detections[(cx > x1) & (cx < x2) & (cy > y1) & (cy < y2)]
offset = np.array([x1, y1])
cluster = sv.Detections(
xyxy=cluster.xyxy - np.tile(offset, 2),
class_id=cluster.class_id,
data={"xyxyxyxy": cluster.data["xyxyxyxy"] - offset},
)
crop = image[y1:y2, x1:x2]
index = sv.ColorLookup.INDEX
axis_aligned = sv.BoxAnnotator(color=sv.Color.RED, thickness=2, color_lookup=index).annotate(crop.copy(), cluster)
oriented = sv.OrientedBoxAnnotator(color=sv.Color.GREEN, thickness=2, color_lookup=index).annotate(crop.copy(), cluster)
separator = np.full((crop.shape[0], 8, 3), 255, dtype=np.uint8)
sv.plot_image(np.hstack([axis_aligned, separator, oriented]), size=(14, 6))In [6]:
# axis-aligned NMS compares envelopes; oriented NMS compares the rotated bodies
axis_aligned = sv.Detections(
xyxy=detections.xyxy.copy(),
confidence=detections.confidence.copy(),
class_id=detections.class_id.copy(),
)
print(f"axis-aligned NMS keeps: {len(axis_aligned.with_nms(threshold=0.3))} boats")
print(f"oriented NMS keeps: {len(detections.with_nms(threshold=0.3))} boats")
envelope = (detections.xyxy[:, 2] - detections.xyxy[:, 0]) * (detections.xyxy[:, 3] - detections.xyxy[:, 1])
print(f"\nmedian oriented footprint: {np.median(detections.area):.0f} px^2")
print(f"median axis-aligned box: {np.median(envelope):.0f} px^2")axis-aligned NMS keeps: 147 boats oriented NMS keeps: 172 boats median oriented footprint: 2542 px^2 median axis-aligned box: 5424 px^2
In [7]:
os.makedirs("dataset/images", exist_ok=True)
cv2.imwrite("dataset/images/boats.jpg", image)
classes = sorted(set(detections.data["class_name"].tolist()))
name_to_id = {name: idx for idx, name in enumerate(classes)}
export = sv.Detections(
xyxy=detections.xyxy,
confidence=detections.confidence,
class_id=np.array([name_to_id[name] for name in detections.data["class_name"]]),
data=dict(detections.data),
)
dataset = sv.DetectionDataset(
classes=classes,
images=["dataset/images/boats.jpg"],
annotations={"dataset/images/boats.jpg": export},
)
dataset.as_yolo(annotations_directory_path="dataset/labels", is_obb=True)
lines = open("dataset/labels/boats.txt").read().splitlines()
print(f"{len(lines)} annotations written")
print(f"first line ({len(lines[0].split())} tokens): {lines[0][:80]}...")172 annotations written first line (9 tokens): 0 0.18402 0.43419 0.18928 0.41068 0.15248 0.38468 0.14722 0.40819...