supervision-0.30.1

0.30.1: Numeric-precision and stability fixes

supervision 0.30.1 is a bug-fix patch release. It corrects numeric-precision issues that only surface on specific inputs — large-coordinate oriented boxes (geospatial data, stitched frames), large integer boxes for box_iou, and rotated tracks in DetectionsSmoother — where prior versions could silently return imprecise or self-inconsistent results instead of erroring. It also fixes a duplicate-libavdevice-load crash risk on macOS when both av and opencv-python are installed, plus smaller fixes to list_files_with_extensions and the cv2-free RGBA fallback. No public API was added or removed, and no signature changed — a drop-in upgrade from 0.30.0 for virtually all users. See Migration guide below for the one narrow exception (box_iou on complex-valued coordinates) and for the precision caveats on the numeric fixes.

✨ Spotlights / highlights

1. Oriented-box area/IoU precision fix for large coordinates

sv.Detections.area and sv.oriented_box_iou_batch now translate OBB coordinates to a local origin before floating-point math. Previously, large-coordinate inputs could lose enough precision that a box's IoU with itself collapsed below 1.0.

pair_origin = np.minimum(origin_i, origin_j)
offset_i = (origin_i - pair_origin).astype(np.float32, copy=False)
offset_j = (origin_j - pair_origin).astype(np.float32, copy=False)

2. sv.box_iou no longer overflows on large integer boxes

Area computation now takes coordinate differences before casting to float, avoiding int32 overflow. For realistic coordinate magnitudes, box_iou's scalar result now matches box_iou_batch.

3. Duplicate libavdevice crash fixed on macOS

import supervision no longer loads PyAV's native libraries when the OpenCV backend is active — PyAV is now imported lazily, only where it's used, preventing a duplicate libavdevice warning (and possible crash) when both av and opencv-python are installed.

4. DetectionsSmoother keeps oriented-box corners consistent

Smoothed OBB corners are now aligned (start index + winding) to a reference before averaging, so rotated tracks smooth correctly instead of averaging mismatched corner orderings.

5. sv.get_polygon_center precision fix for large-coordinate polygons

Centroid calculation now translates to the first vertex and computes in float64 before adding the origin back, preventing integer overflow and precision loss for realistic coordinate magnitudes.

🔄 Migration guide

No public signature changed. One item below (box_iou on complex coordinates) does make one specific previously-succeeding call now raise — narrow and deliberate, not classified as breaking since complex-valued box coordinates were never a documented/supported input. The rest only change output values for inputs that were already edge cases:

• sv.box_iou on complex-valued coordinates: previously silently discarded the imaginary part and returned a real number. Now raises TypeError("box coordinates must be real-valued").
• OBB precision fixes: results for oriented boxes with large coordinates or rotated tracks may differ slightly from 0.30.0 — the new values are the corrected ones. Re-calibrate any hardcoded IoU/area thresholds tuned against the old (imprecise) output.
• sv.box_iou / box_iou_batch agreement: for realistic integer coordinate magnitudes (below 2^53), box_iou's scalar result now matches box_iou_batch. Not a universal guarantee — box_iou subtracts before casting to float, box_iou_batch still casts to float64 before subtracting, so the two can diverge at coordinates ≥ 2^53 (~9 quadrillion), far outside any real use case.

📝 Notable changes

🚀 Added

• RF-DETR example scripts (rfdetr_example.py) added to the count_people_in_zone, heatmap_and_track, speed_estimation, tracking, and traffic_analysis bundled examples. (#2497)

🌱 Changed

• sv.box_iou now raises TypeError for complex-valued box coordinates instead of silently discarding the imaginary part. (#2485)
• Performance: DetectionsSmoother.update_with_detections now checks active tracker IDs via set membership instead of scanning per tracked object. No output changes. (#2496)
• Documentation and API-reference examples now default to RF-DETR instead of Ultralytics YOLO. (#2493, #2494, #2497)

🔧 Fixed

• RF-DETR speed estimation now measures elapsed source-frame intervals, including gaps when tracked detections are temporarily missed. (#2497)
• sv.get_polygon_center now calculates polygon centroids in translated float64 coordinates, preventing integer overflow and precision loss for realistic-magnitude large-coordinate polygons. (#2491)
• sv.Detections.area and sv.oriented_box_iou_batch now translate oriented-box coordinates to local origins before floating-point math, preventing self-IoU collapse for large-coordinate inputs. (#2492)
• DetectionsSmoother now keeps oriented-box corners aligned with smoothed xyxy geometry, including rotated tracks and mixed metadata windows. (#2489)
• sv.box_iou now calculates overlap in float64, preventing int32 area overflow for large boxes; its scalar result now matches sv.box_iou_batch for realistic coordinate magnitudes. (#2485)
• sv.list_files_with_extensions no longer includes directories when listing all files without an extension filter. (#2486)
• sv.pillow_to_cv2 now accepts RGBA images when the cv2-free fallback backend is active, matching OpenCV by dropping alpha and returning BGR channels. (#2488)
• import supervision no longer loads PyAV's native libraries when the OpenCV backend is selected; PyAV is now imported lazily on first use, preventing a duplicate libavdevice warning (and possible crash) on macOS when both av and opencv-python are installed. (#2509)
• Docstring examples converted to executed doctests across annotators/core.py, dataset/formats/coco.py, dataset/formats/createml.py, and Detections.from_vlm; previously wrong documented outputs corrected for several VLM examples. (#2474, #2475, #2479, #2484)

Also in this release: routine dependency bumps (dependabot: astral-sh/setup-uv, wheel, pymdown-extensions x2, pypa/gh-action-pypi-publish, twine, cryptography), CI/docs-workflow maintenance, and test-only additions (geometry contract test, sklearn parity test) — none change installed package behavior. (#2028, #2470, #2472, #2473, #2480, #2481, #2482, #2483, #2499, #2501, #2506, #2507, #2508)

🏆 Contributors

• lawliet (@lawliet206) — oriented-box area/IoU precision fix at large coordinate origins
• Zhewen Tan (@tandede) — polygon centroid overflow/precision fix
• Tamil Adhavan S K (@adhavan18, LinkedIn) — DetectionsSmoother oriented-box corner alignment fix; added geometry contract test
• NIKHIL (@Nikhi00718) — fixed box_iou int32 overflow; added complex-coordinate TypeError guard
• shao (@shaoming11, LinkedIn) — DetectionsSmoother tracker-ID lookup performance improvement
• Tyyyy (@uczltw6) — RGBA image support in the cv2-free fallback conversion
• ZZZZZ (@BruceWae) — fixed list_files_with_extensions to exclude directories
• FootysHands (@ayo0la) — converted docstring examples to doctests; corrected wrong documented VLM example outputs
• Swapnil Gautam (@Swapnil-gautam) — converted docstring examples to doctests in dataset format modules
• Daniiiil1 (@Daniiiil1) — added sklearn parity test for metrics
• Christoph Deil (@cdeil, LinkedIn) — repo maintenance docs

---

Full changelog: 0.30.0...0.30.1