refactor(cv2): add optional backend facade

[Borda]

This pull request introduces a new private OpenCV compatibility layer (src/supervision/_cv2/__init__.py) and refactors the codebase to use it. The main goal is to centralize OpenCV imports and provide a fallback mechanism when OpenCV is not installed, improving robustness and portability. All direct cv2 imports throughout the codebase are replaced with imports from this new compatibility module.

Key changes:

OpenCV Compatibility Layer

• Added a new module src/supervision/_cv2/__init__.py that acts as a compatibility layer for OpenCV. It exposes OpenCV constants and functions if cv2 is available, and provides clear error messages or fallbacks if not.

Refactoring Imports

• Replaced all direct import cv2 statements with from supervision import _cv2 as cv2 throughout the codebase, including in docstring examples, to ensure consistent usage of the compatibility layer. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17] [18] [19] [20] [21] [22] [23] [24] [25] [26] [27] [28] [29]

Consistency in Examples

• Updated all code examples in docstrings to use the compatibility import, ensuring documentation matches the new import style. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17]

These changes make the codebase more robust to environments where OpenCV may not be installed and simplify future maintenance by centralizing OpenCV-related logic.

[codecov]

Codecov Report

❌ Patch coverage is 46.08696% with 62 lines in your changes missing coverage. Please review.
✅ Project coverage is 86%. Comparing base (16814ac) to head (8117950).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2430   +/-   ##
=======================================
- Coverage       87%     86%   -0%     
=======================================
  Files           72      73    +1     
  Lines        10679   10774   +95     
=======================================
+ Hits          9264    9297   +33     
- Misses        1415    1477   +62     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR introduces a private OpenCV compatibility facade (supervision._cv2) and refactors Supervision’s internal OpenCV usage to route through that single boundary. This centralizes OpenCV symbol imports and enables clearer failure behavior (or limited constant availability) in environments where cv2 cannot be imported.

Changes:

• Added src/supervision/_cv2/__init__.py as a curated OpenCV surface with a fallback mode that raises BackendUnavailableError for operations without an available backend.
• Replaced direct import cv2 usage across multiple modules/tests/doc examples with from supervision import _cv2 as cv2.
• Added a dedicated test suite (tests/cv2/) to validate the facade’s exported surface, constant alignment, and fallback behavior.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/utils/test_video.py	Switch test OpenCV import to the _cv2 facade.
tests/utils/test_image.py	Switch test OpenCV import to the _cv2 facade.
tests/cv2/test_cv2.py	Add tests asserting _cv2 exports/behavior and fallback import scenarios.
tests/cv2/init.py	Introduce package marker/docstring for cv2-facade tests.
tests/annotators/test_core.py	Switch test OpenCV import to the _cv2 facade.
src/supervision/utils/video.py	Route video utilities’ OpenCV usage through _cv2.
src/supervision/utils/notebook.py	Route notebook rendering conversions through _cv2.
src/supervision/utils/image.py	Route image utilities’ OpenCV usage through _cv2.
src/supervision/utils/conversion.py	Route conversion helpers’ OpenCV usage through _cv2.
src/supervision/metrics/detection.py	Update lazy OpenCV import sites to use _cv2.
src/supervision/key_points/core.py	Update doc examples to import OpenCV via _cv2.
src/supervision/key_points/annotators.py	Route keypoint annotators’ OpenCV usage through _cv2.
src/supervision/draw/utils.py	Route drawing helpers’ OpenCV usage through _cv2.
src/supervision/detection/utils/polygons.py	Route polygon helpers’ OpenCV usage through _cv2.
src/supervision/detection/utils/masks.py	Route mask helpers’ OpenCV usage through _cv2.
src/supervision/detection/utils/iou_and_nms.py	Route IoU/NMS helpers’ OpenCV usage through _cv2.
src/supervision/detection/utils/internal.py	Route internal detection helpers’ OpenCV usage through _cv2.
src/supervision/detection/utils/converters.py	Route converter helpers’ OpenCV usage through _cv2.
src/supervision/detection/tools/polygon_zone.py	Route PolygonZone OpenCV usage through _cv2.
src/supervision/detection/tools/inference_slicer.py	Update doc examples to import OpenCV via _cv2.
src/supervision/detection/line_zone.py	Route LineZone OpenCV usage through _cv2.
src/supervision/detection/core.py	Update doc examples to import OpenCV via _cv2.
src/supervision/detection/compact_mask.py	Route compact mask resize path through _cv2.
src/supervision/dataset/utils.py	Route dataset utilities’ OpenCV usage through _cv2.
src/supervision/dataset/formats/pascal_voc.py	Route Pascal VOC format OpenCV usage through _cv2.
src/supervision/dataset/core.py	Route dataset core OpenCV usage through _cv2.
src/supervision/classification/core.py	Update doc examples to import OpenCV via _cv2.
src/supervision/annotators/core.py	Route annotators’ OpenCV usage (and examples) through _cv2.
src/supervision/_cv2/init.py	New OpenCV facade module with fallback constants + explicit failure for missing backend.