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.

```python
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](https://www.linkedin.com/in/tamiladhavan)) — 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](https://www.linkedin.com/in/shaoming-wu/)) — `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](https://www.linkedin.com/in/christophdeil)) — repo maintenance docs

______________________________________________________________________

**Full changelog**: https://github.com/roboflow/supervision/compare/0.30.0...0.30.1