[dependabot]

Bumps supervision from 0.31.2 to 0.31.3.

Release notes

Sourced from supervision's releases.

supervision-0.31.3

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)
</tr></table>

... (truncated)

Changelog

Sourced from supervision's changelog.

0.31.3 Oct 28, 2026

• sv.BackgroundOverlayAnnotator now annotates grayscale scenes, shaped (H, W) or (H, W, 1) or given as a Pillow "L" image, instead of raising ValueError. The background is blended with the first (blue) channel of the overlay color, the value OpenCV draws on a single-channel image, so a grayscale result equals the first channel of the same annotation on a BGR copy. (#2832)
• The NumPy cv2.mean fallback now accumulates float32 pixels in float64, preserving small values when large positive and negative pixels cancel. For example, [1e8, 1, -1e8] now averages to 1/3 instead of 0. (#2820)
• sv.get_video_frames_generator now rejects stride=0 and negative strides with ValueError on first iteration, before opening the video or starting a prefetch thread. Previously these values could yield frames past end. (#2819)
• sv.KeyPoints.as_detections and sv.KeyPoints.with_nms now use x/y for missing-point and finiteness checks when building image-space boxes. An extra coordinate no longer changes the boxes or suppression result; original keypoint data is preserved. (#2817)
• Added the examples/depth_showcase example, which runs Depth Anything V2 Large, Apple Depth Pro and a YOLO depth model through sv.DepthAnnotator on video files, webcams and streams. It reads video files to EOF by default even when frame-count metadata is missing or inaccurate, validates frame limits, skips unusable depth maps during colour-range calibration, selects only devices supported by installed PyTorch, and keeps inference timing memory bounded. (#2804, #2818)
• sv.assets.download_assets(VideoAssets.GROCERY_STORE) no longer fails with Downloaded asset 'grocery-store.mp4' failed MD5 verification: the catalog now holds the checksum of the hosted file. (#2804)
• Annotators and sv.hex_to_rgba now accept 3- and 4-digit short hex colors such as "#f0f" and "#f0f8", matching sv.Color.from_hex. Previously sv.BoxAnnotator(color="#f0f") raised ValueError. (#2801)
• sv.ImageSink(overwrite=False) now raises FileExistsError instead of silently replacing an existing image with the same filename, including dangling symlink destinations. Paths containing embedded null characters raise ValueError before writing, preventing native path truncation from bypassing the overwrite guard. (#2800)
• Added sv.merge_multi_segment, which joins the disconnected polygon segments of one mask into a single polygon through zero-width seams at the nearest vertices. It preserves nearest-vertex ordering for large integer origins by translating before distance calculations, and raises ValueError when an adjacent integer segment pair spans more than 2**25 on either axis. Adjacent pairs mixing integer and floating segments reject integer coordinates outside [-2**53, 2**53] before lossy float64 conversion. (#2786)
• sv.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; pass ignore_crowd=False and merge_segments=False to keep the previous output. The same parameters were added to save_yolo_annotations and detections_to_yolo_annotations in supervision.dataset.formats.yolo. (#2786)
• Depth input validation now rejects unwrapped integer arrays instead of treating them as valid depth values. (#2795)
• sv.metrics.MeanAverageRecall.compute() now preserves shared scalar metadata when filtering targets by object size, instead of raising IndexError. (#2791)
• sv.ComparisonAnnotator now annotates grayscale scenes, shaped (H, W) or (H, W, 1) or given as a Pillow "L" image, instead of raising ValueError. Each region is blended with the first (blue) channel of its color, the value OpenCV draws on a single-channel image, so a grayscale result equals the first channel of the same annotation on a BGR copy. (#2803)
• The NumPy fallback for line, polylines and drawContours at thickness 1, and for circle outlines of thickness 1 and filled circles, now matches OpenCV pixel for pixel. These paths still used Pillow: on 2,000 random shapes, 66% of thin lines, 80% of thin circles and 82% of filled circles differed from cv2, and a filled radius-10 circle painted 349 pixels instead of 317. Thin segments now follow OpenCV's clipLine and LineIterator, and circles port the midpoint stepping of OpenCV's Circle. A negative circle radius now raises ValueError, as in OpenCV. (#2808)
• The NumPy fallback for fillPoly and filled drawContours now matches OpenCV for polygons whose edges leave the canvas, extending the in-bounds parity of #2730. OpenCV takes an off-canvas edge's slope from its integer-clipped endpoints; the fallback used the original vertices, so 61% of random polygons leaving the canvas differed by a few boundary pixels (up to 52). polygon_to_mask, sv.draw_filled_polygon and PolygonZone masks are affected without OpenCV. (#2810)
• The NumPy fallback for blur now rounds 8-bit results like OpenCV. It averaged in float64 and rounded exact halves to even, while OpenCV divides exact window sums with a fixed-point reciprocal that rounds them up, so kernels with an even area, such as (2, 1) or (4, 4), were one gray level off on many pixels. Kernels of up to 256 pixels use OpenCV's fixed-point rounding, with saturation for maximum-valued two-pixel windows; larger ones use OpenCV's float32 reciprocal. BlurAnnotator, HaloAnnotator and HeatMapAnnotator are affected without OpenCV. (#2811)
• The NumPy fallback for connectedComponents and connectedComponentsWithStats now numbers 8-connected components like OpenCV, by their first 2x2 block in raster order instead of their first pixel. Labels, stats rows and centroids rows were permuted relative to OpenCV whenever a component started on the lower row of a block pair before another started further right on the upper row; 131 of 282 random 8-connected masks were affected. (#2812)
• The NumPy fallback for addWeighted now rounds 8-bit, 16-bit and float32 blends like OpenCV. It blended in float64, while OpenCV casts the weights to float32 and adds with two fused multiply-adds, so sums that land on or next to a half rounded the other way: with alpha=0.3 and beta=0.7, 820 of the 65,536 pairs of 8-bit values were one level off. Opacities such as 0.3, 0.7 or 0.9 in sv.ColorAnnotator, sv.MaskAnnotator, sv.draw_filled_polygon and the other blending annotators are affected without OpenCV. 32-bit integer and float64 inputs keep the float64 path. (#2836)
• The NumPy fallback for resize with INTER_LINEAR now matches OpenCV pixel for pixel on uint8 images. It went through Pillow (or float64 math for RGBA and fx/fy resizes), which rounded differently from OpenCV's 11-bit fixed-point weights: on 996 random grayscale, BGR and RGBA resizes every result differed from cv2.resize by one level somewhere. Exact halvings (fx=fy=0.5) follow OpenCV's fast area path, and an unchanged size returns a copy. The reference is OpenCV's generic kernel; arm64 builds hand some grayscale and RGBA resizes to the Carotene HAL, which can differ by up to two levels. sv.resize_image, sv.letterbox_image, sv.scale_image, sv.PixelateAnnotator and sv.draw_image are affected without OpenCV. Other dtypes keep the float path. (#2833)

Commits

• 7bec765 releasing 0.31.3
• 7fafe92 fix(cv2): blend addWeighted in float32 like OpenCV (#2836)
• 96303f7 fix(cv2): resize uint8 images bit-exactly like OpenCV INTER_LINEAR (#2833)
• a5b6503 fix(annotators): draw background overlays on grayscale scenes (#2832)
• b6e0623 docs(detection): fix docstring examples that are not valid Python (#2831)
• f003bea fix(cv2): preserve float32 precision in mean fallback (#2820)
• 43d3443 fix(video): reject nonpositive frame stride (#2819)
• 09a56d7 fix(key_points): Build image-space boxes from x/y coordinates (#2817)
• d2fee14 fix(cv2): number 8-connected components in OpenCV's block order (#2812)
• f6ef163 fix(cv2): blur 8-bit images with OpenCV's integer rounding (#2811)
• Additional commits viewable in compare view

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.

---

Dependabot commands and options

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot show <dependency name> ignore conditions will show all of the ignore conditions of the specified dependency
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)