Optimize mask annotation ROI blending

[Borda]

This pull request introduces a significant optimization to the MaskAnnotator class, ensuring that mask blending is limited to only the region of interest (ROI) touched by the mask(s), rather than always blending the full image. This change improves annotation speed, especially for large images with sparse masks, and reduces unnecessary computation. The update includes supporting utility functions, test coverage for the new behavior, and improved documentation and reporting in the benchmark script.

Mask annotation ROI optimization:

• Updated MaskAnnotator.annotate to blend only the minimal bounding rectangle (ROI) covering all true mask pixels, both for dense and compact masks, instead of the entire image. This is achieved by computing the ROI with new helper functions and passing the ROI to the blending operation.
• Refactored the internal _paint_masks_by_area function to support painting into a subregion of the canvas with a new canvas_origin parameter, aligning mask coordinates with the ROI. [1] [2] [3] [4]

Utility functions for ROI calculation:

• Added _mask_to_roi, _compact_masks_to_roi, and _masks_to_roi functions to compute the minimal bounding box for true mask pixels in dense and compact masks.

Testing:

• Added new tests in tests/annotators/test_core.py to verify that blending occurs only within the mask ROI for both dense and compact masks, and that no blending occurs when masks are all-false.

Documentation and reporting:

• Improved docstrings and comments to clarify the new ROI-based blending logic.
• Updated the benchmark script and table output to clarify that annotation speedup is due to ROI-only blending, and improved column naming for clarity. [1] [2] [3] [4]

[codecov]

Codecov Report

❌ Patch coverage is 91.07143% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 83%. Comparing base (934da12) to head (254cb35).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2368   +/-   ##
=======================================
  Coverage       83%     83%           
=======================================
  Files           69      69           
  Lines         9616    9669   +53     
=======================================
+ Hits          7941    7989   +48     
- Misses        1675    1680    +5     

🚀 New features to boost your workflow:

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

[Copilot]

Pull request overview

This pull request optimizes MaskAnnotator.annotate by limiting blending work (cv2.addWeighted) to the minimal region-of-interest (ROI) that actually contains mask pixels, reducing unnecessary full-frame blending for sparse masks. It also extends the shared mask-painting utility to support painting into a sub-canvas with an absolute origin, and adds tests/benchmark wording to validate and explain the new behavior.

Changes:

• Compute a minimal ROI for dense and CompactMask masks and blend only that ROI in MaskAnnotator.annotate.
• Extend _paint_masks_by_area(...) with a canvas_origin parameter so masks can be painted correctly into an ROI-sized canvas.
• Add tests asserting blending happens only on the ROI (and is skipped for all-false masks), and clarify benchmark reporting text/labels.

Review scores (n/5):

• Code quality: 5/5
• Testing: 5/5
• Documentation/clarity: 5/5

Reviewed changes

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

File	Description
src/supervision/annotators/core.py	Adds ROI computation helpers, supports sub-canvas mask painting via canvas_origin, and blends only the ROI in MaskAnnotator.
tests/annotators/test_core.py	Adds regression tests verifying ROI-only blending for dense/compact masks and skipping blending for all-false masks.
examples/compact_mask/benchmark.py	Updates benchmark docstring/table labels to better attribute annotation speedups to ROI-only blending.