supervision

v0.31.4 — Stricter dataset export, COCO-exact recall buckets, and a closer NumPy fallback

Fourteen bug fixes: stricter dataset export, COCO-exact recall buckets, sturdier VLM parsing, and a NumPy fallback closer to OpenCV.

• CreateML and Pascal VOC export raise a clear ValueError for a class_id outside classes.
• DetectionDataset.merge keeps annotations that have no class IDs instead of raising.
• MeanAverageRecall counts boundary-area objects in both COCO size buckets, like MeanAveragePrecision.
• Qwen and PaliGemma parsing keep valid boxes and class labels beside malformed ones.
• Without OpenCV, image reads, gray conversion, drawing colors and keyword parameters match OpenCV.

Drop-in upgrade; see the Migration guide if you export out-of-range class IDs or compare mAR values or fallback pixels against stored references.

✨ Spotlights / highlights

Dataset export rejects out-of-range class IDs

detections_to_createml_annotations and detections_to_pascal_voc now raise ValueError for a class_id outside classes, as detections_to_labelme_shapes already does. A negative id was exported under the last class name, and an id past the end raised IndexError. (#2859)

import numpy as np
import supervision as sv
from supervision.dataset.formats.createml import detections_to_createml_annotations

detections = sv.Detections(
    xyxy=np.array([[10.0, 10.0, 50.0, 50.0]]), class_id=np.array([-1])
)
detections_to_createml_annotations(detections, classes=["cat", "dog"])
# ValueError: class_id -1 at detection index 0 is out of range for classes list of length 2.
# 0.31.3: exported with the label "dog"

DetectionDataset.merge keeps annotations without class IDs

Merging datasets used to raise ValueError when some annotations had no class_id. They are now kept as they are while labeled annotations are remapped. (#2858)

import numpy as np
import supervision as sv

labeled = sv.DetectionDataset(
    classes=["a"],
    images=["x.jpg"],
    annotations={
        "x.jpg": sv.Detections(xyxy=np.array([[0.0, 0, 5, 5]]), class_id=np.array([0]))
    },
)
unlabeled = sv.DetectionDataset(
    classes=["b"],
    images=["y.jpg"],
    annotations={"y.jpg": sv.Detections(xyxy=np.array([[0.0, 0, 5, 5]]))},
)
merged = sv.DetectionDataset.merge([labeled, unlabeled])
merged.classes
# ['a', 'b']  (0.31.3: ValueError)

MeanAverageRecall size buckets match COCO

An object whose area is exactly 32² or 96² now counts in both neighbouring size buckets, the inclusive ranges pycocotools and MeanAveragePrecision use. It used to land in only one, so mAR and mAP disagreed on the small, medium and large results. (#2848)

import numpy as np
import supervision as sv
from supervision.metrics import MeanAverageRecall

box = np.array([[0.0, 0.0, 32.0, 32.0]])  # area is exactly 32²
target = sv.Detections(xyxy=box, class_id=np.array([0]))
prediction = sv.Detections(xyxy=box, class_id=np.array([0]), confidence=np.array([0.9]))

result = MeanAverageRecall().update([prediction], [target]).compute()
result.small_objects.mAR_at_100, result.medium_objects.mAR_at_100
# (1.0, 1.0)  (0.31.3: (0.0, 1.0))

🔄 Migration guide

No public symbol was removed or renamed, and nothing is deprecated. A few fixes change what existing code returns or raises:

• New error: CreateML and Pascal VOC export raise ValueError for a class_id outside classes. Make sure every exported id indexes into your classes list; filter or remap ids such as -1 first. (#2859)
• Different numbers: MeanAverageRecall small, medium and large results can change for datasets with objects of area exactly 32² or 96². (#2848)
• Different pixels without OpenCV: drawing colors saturate instead of wrapping, uint16 gray conversion and 16-bit grayscale reads follow OpenCV, and IMREAD_GRAYSCALE returns a two-dimension

v0.31.3 — Grayscale annotators, OpenCV-exact fallbacks, and merged YOLO polygons

Grayscale scenes work with more annotators, the pure NumPy fallback matches OpenCV pixel for pixel, and YOLO export handles multi-part masks.

• YOLO export merges multi-part masks into one polygon and skips crowd annotations, with flags for the old output.
• Background overlay and comparison annotators draw on grayscale scenes.
• Without OpenCV, resize, blur, blending, drawing and connected components give the same pixels as OpenCV.
• Invalid input fails early: ImageSink, the video frame generator and depth arrays now raise clear errors.
• Short hex colors such as "#f0f" work in annotators.

Drop-in upgrade unless you export YOLO labels: the default output changes, see the Migration guide.

✨ Spotlights / highlights

YOLO export merges multi-part masks and skips crowd annotations

DetectionDataset.as_yolo now omits detections whose iscrowd flag is set and writes a mask with several disconnected parts as one merged polygon line instead of one line per part. Both are on by default. The merge is done by the new sv.merge_multi_segment, which joins the parts through zero-width seams at their nearest vertices. (#2786)

import supervision as sv

dataset = sv.DetectionDataset(...)
dataset.as_yolo(
    images_directory_path="images",
    annotations_directory_path="labels",
    data_yaml_path="data.yaml",
)  # 0.31.3: crowd skipped, one merged polygon line per mask

dataset.as_yolo(
    images_directory_path="images",
    annotations_directory_path="labels",
    data_yaml_path="data.yaml",
    ignore_crowd=False,
    merge_segments=False,
)  # the 0.31.2 output

sv.merge_multi_segment

New public function. Pass it the polygon parts of one mask and get back a single polygon. (#2786)

import numpy as np
import supervision as sv

a = np.array([[0, 0], [10, 0], [10, 10], [0, 10]])
b = np.array([[30, 30], [40, 30], [40, 40], [30, 40]])
sv.merge_multi_segment([a, b]).shape
# (10, 2)

Annotators on grayscale scenes

BackgroundOverlayAnnotator and ComparisonAnnotator now draw on scenes shaped (H, W) or (H, W, 1), or given as a Pillow "L" image, instead of raising ValueError. Short hex colors such as "#f0f" now work in annotators and sv.hex_to_rgba. (#2832, #2803, #2801)

import numpy as np
import supervision as sv

scene = np.zeros((100, 100), dtype=np.uint8)
detections = sv.Detections(
    xyxy=np.array([[20, 20, 60, 60]], dtype=float), class_id=np.array([0])
)
sv.BackgroundOverlayAnnotator().annotate(scene.copy(), detections).shape
# (100, 100)  (0.31.2: ValueError)

The NumPy fallback matches OpenCV pixel for pixel

Without OpenCV installed, resize (INTER_LINEAR on uint8), blur, addWeighted, thin lines, circles, filled polygons that leave the canvas, connectedComponents and mean now give the same pixels as OpenCV. BlurAnnotator, HaloAnnotator, HeatMapAnnotator, PixelateAnnotator, the blending annotators, sv.resize_image, sv.letterbox_image and PolygonZone masks are affected. (#2833, #2836, #2811, #2808, #2810, #2812, #2820)

Bad input fails early

sv.ImageSink(overwrite=False) raises FileExistsError instead of replacing an existing image, sv.get_video_frames_generator rejects a stride below 1, and DepthMap.from_ultralytics rejects unwrapped integer arrays. (#2800, #2819, #2795)

import supervision as sv

for frame in sv.get_video_frames_generator("video.mp4", stride=0):
    ...
# ValueError: stride must be >= 1, got 0

🔄 Migration guide

One default behavior changes: YOLO export. No public symbol was removed or renamed in this release, and nothing is deprecated.

YOLO export defaults affect sv.DetectionDataset.as_yolo, and save_yolo_annotations and detections_to_yolo_annotations in `supervision.dataset.formats.yol

v0.31.2 — Pascal VOC boxes that match the devkit

A bug-fix release: Pascal VOC boxes now follow the devkit convention, and a batch of crashes on edge-case inputs is gone.

• Pascal VOC export and import use the devkit's box indices, so Detectron2 and other readers see the boxes you wrote.
• Gemini 2.5 and 3.5 masks survive boxes that leave the 0-1000 range instead of failing the whole response.
• Crop and icon annotators draw on grayscale scenes.
• Half-precision box centers stay finite instead of turning into inf.
• JSON sinks, dataset exports and the video reader stop losing data when something goes wrong.

Drop-in upgrade, with one catch: box-only Pascal VOC objects written by earlier versions now load one pixel larger on the right and bottom edges. The migration guide below shows how to fix them.

✨ Spotlights / highlights

Pascal VOC boxes follow the devkit

DetectionDataset.as_pascal_voc and from_pascal_voc now treat <bndbox> indices as 1-based and inclusive, shifting only xmin and ymin by one, which is what Detectron2 and other devkit readers expect. Export also rounds corners to the nearest pixel instead of truncating them, so a YOLO box that from_yolo loads with float noise no longer grows a pixel. Box-only objects written by 0.31.1 and earlier carry an extra +1 in xmax and ymax; objects exported from masks already used the devkit maxima. (#2748, #2780)

# `dataset` holds one box [10, 20, 40, 60]
dataset.as_pascal_voc(
    images_directory_path="images", annotations_directory_path="annotations"
)
# <bndbox>: xmin=11 ymin=21 xmax=40 ymax=60  (0.31.1: xmax=41 ymax=61)
# a YOLO box loaded as [0, 0, 37.0000001, 29.0000001]: 1 1 37 29  (0.31.1: 1 1 38 30)

Gemini masks survive boxes outside the 0-1000 range

Detections.from_vlm with VLM.GOOGLE_GEMINI_2_5 or VLM.GOOGLE_GEMINI_3_5 raised ValueError as soon as a box_2d coordinate went above 1000 or below 0, even by one, and you lost every detection in the response. The mask is now cropped to the part of its box inside the image, a box wholly outside gets an all-false mask, and boxes inside the image produce the same masks as before. (#2793)

import supervision as sv

# one item: {"box_2d": [500, 500, 1001, 1001], "label": "cat", "mask": "data:image/png;base64,..."}
detections = sv.Detections.from_vlm(
    sv.VLM.GOOGLE_GEMINI_3_5, result, resolution_wh=(1000, 800)
)
detections.mask.shape, int(detections.mask.sum())
# ((1, 800, 1000), 200000)
# 0.31.1: ValueError: could not broadcast input array from shape (400,501) into shape (400,500)

Crop and icon annotators on grayscale scenes

CropAnnotator and IconAnnotator used to raise IndexError or ValueError on scenes shaped (H, W) or (H, W, 1), or given as a Pillow "L" image. Crops now keep the scene's channel layout, and icons are drawn as their gray luminance, blended by their alpha channel. (#2788)

import numpy as np
import supervision as sv

scene = np.zeros((100, 100), dtype=np.uint8)
scene[20:60, 20:60] = 200
detections = sv.Detections(
    xyxy=np.array([[20, 20, 60, 60]], dtype=float), class_id=np.array([0])
)
sv.CropAnnotator().annotate(scene.copy(), detections).shape
# (100, 100)  (0.31.1: IndexError: tuple index out of range)

Half-precision boxes that stay finite

sv.scale_boxes and Detections.get_anchors_coordinates now compute box centers without overflowing float16: a box from 40000 to 60000 used to report an inf center. DetectionsSmoother also compares oriented-box corner distances in float64, which stops float16 and narrow integer coordinates from overflowing; integer coordinates beyond 2**53 still lose low-order pixels in the float64 average. (#2787, #2785)

import numpy as np
import supervision as sv

detections = sv.Detections(
    xyxy=np.array([[40000, 40000, 60000, 60000]], dtype=np.float16)
)
detection

v0.31.1 — Recall that matches COCO, boxes that don't overflow

A bug-fix release: recall scores now agree with COCO, and half-precision boxes stop overflowing.

• MeanAverageRecall skips crowd regions and matches predictions in confidence order, like pycocotools.
• COCO segmentations loaded without an area field no longer make mAP return -1.
• float16 boxes keep finite areas, and mAP and with_nmm stop overflowing on narrow coordinate types.
• Mask and halo annotators draw on grayscale scenes, and vertex annotators accept (x, y, z) points.
• Without OpenCV, ellipses and thick circles render like OpenCV 5, and grayscale images save correctly.

Drop-in upgrade, no code changes. mAR values can move: up on COCO data with crowd annotations, and in either direction where confidence order now decides which prediction claims a target.

✨ Spotlights / highlights

Recall that matches COCO

sv.metrics.MeanAverageRecall used to count COCO crowd regions as missed objects and to pair predictions with the highest-IoU target first. It now leaves out targets with data["iscrowd"] or data["ignore"] set, the same rule MeanAveragePrecision uses. It also matches predictions in descending confidence order with COCO's tie rule, and counts an oriented-box IoU of exactly 0.55, 0.6, 0.8 or 0.85 as a match at that threshold. One target, one crowd target and a perfect prediction now score 1.0 instead of 0.5. (#2750, #2758, #2752)

import numpy as np
import supervision as sv
from supervision.metrics import MeanAverageRecall

targets = sv.Detections(
    xyxy=np.array([[0, 0, 10, 10], [20, 20, 30, 30]], dtype=float),
    class_id=np.array([0, 0]),
    data={"iscrowd": np.array([0, 1])},
)
predictions = sv.Detections(
    xyxy=np.array([[0, 0, 10, 10]], dtype=float),
    class_id=np.array([0]),
    confidence=np.array([0.9]),
)
MeanAverageRecall().update(predictions, targets).compute().mAR_at_100  # 1.0

Half-precision boxes that stay finite

A 256×256 box in float16 has an area of 65,536, which is past float16's maximum, so Detections.box_area returned inf and area filters dropped it. Box areas of float16 detections are now computed and returned in float32, and MeanAveragePrecision and with_nmm no longer overflow on float16 or narrow integer coordinates either. COCO segmentations loaded with masks but without an area field now get it from the decoded mask, so those targets stay in their size bucket instead of turning mAP into -1. (#2764, #2743, #2753, #2763)

import numpy as np
import supervision as sv

detections = sv.Detections(
    xyxy=np.array([[0, 0, 256, 256], [0, 0, 0.01, 0.01]], dtype=np.float16)
)
detections.box_area  # array([6.5536000e+04, 1.0004273e-04], dtype=float32)

Grayscale scenes and 3D keypoints in annotators

sv.MaskAnnotator and sv.HaloAnnotator raised ValueError on single-channel images. They now accept (H, W), (H, W, 1) and Pillow "L" scenes, painting the gray value OpenCV would write for the same color. VertexAnnotator and the vertex-ellipse annotators draw (x, y, z) keypoints from their x and y, where they used to fail on tuple unpacking. (#2755, #2759)

import numpy as np
import supervision as sv

scene = np.zeros((100, 100), dtype=np.uint8)
mask = np.zeros((1, 100, 100), dtype=bool)
mask[0, 20:60, 20:60] = True
detections = sv.Detections(
    xyxy=np.array([[20, 20, 60, 60]], dtype=float), mask=mask, class_id=np.array([0])
)
sv.MaskAnnotator().annotate(scene.copy(), detections).shape  # (100, 100)

key_points = sv.KeyPoints(xy=np.array([[[10, 10, 0.5], [50, 50, 1.0]]], dtype=np.float32))
sv.VertexAnnotator().annotate(np.zeros((64, 64, 3), dtype=np.uint8), key_points)

Drawing without OpenCV, closer to OpenCV

The NumPy fallback used when OpenCV is not installed now ports OpenCV's ellipse rasterization, and thick circle outlines are ce