feat: declare annotator mask requirements#2370
Open
Borda wants to merge 3 commits into
Open
Conversation
Add a BaseAnnotator.requires_mask flag so integrations can avoid materializing masks for mask-optional visualizations. Mark mask-only annotators as requiring masks and cover mask-required versus mask-optional annotators in tests. Co-authored-by: Codex <codex@openai.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## develop #2370 +/- ##
=======================================
Coverage 83% 83%
=======================================
Files 69 69
Lines 9616 9621 +5
=======================================
+ Hits 7941 7946 +5
Misses 1675 1675 🚀 New features to boost your workflow:
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a small piece of annotator “capability metadata” (requires_mask) so integrations can decide whether they need to materialize Detections.mask (often expensive) before running a given annotator.
Changes:
- Added
requires_masktoBaseAnnotatoras a standardized policy flag. - Set
requires_mask = Truefor mask-dependent annotators (MaskAnnotator,PolygonAnnotator,HaloAnnotator) andrequires_mask = FalseforComparisonAnnotator. - Added tests validating the declared mask policy for a representative set of annotators.
Quality scores (n/5):
- Code quality: 4/5
- Testing: 4/5
- Docs: 4/5
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/supervision/annotators/base.py |
Introduces the requires_mask policy flag on the base annotator interface. |
src/supervision/annotators/core.py |
Declares requires_mask on mask-dependent annotators (and explicitly False for ComparisonAnnotator). |
tests/annotators/test_core.py |
Adds tests asserting the expected requires_mask policy for key annotators. |
Comment on lines
+2
to
+15
| from typing import Any, ClassVar | ||
|
|
||
| from supervision.detection.core import Detections | ||
|
|
||
|
|
||
| class BaseAnnotator(ABC): | ||
| """Base class for annotators that consume :class:`Detections`. | ||
|
|
||
| Attributes: | ||
| requires_mask: Whether integrations must provide ``Detections.mask`` for | ||
| this annotator. Check this before materializing expensive mask payloads. | ||
| """ | ||
|
|
||
| requires_mask: ClassVar[bool] = False |
Comment on lines
+56
to
+59
| def test_mask_required_annotators_declare_mask_requirement(self, annotator): | ||
| """Annotators that require detections.mask expose the requirement.""" | ||
| assert annotator.requires_mask is True | ||
|
|
Comment on lines
+73
to
+75
| def test_mask_optional_annotators_declare_no_mask_requirement(self, annotator): | ||
| """Mask-optional annotators do not require mask materialization.""" | ||
| assert annotator.requires_mask is False |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a standardized way for annotator classes to declare whether they require the
Detections.maskattribute, which helps integrations avoid unnecessary computation when mask data is not needed. It does this by adding arequires_maskclass variable to the base annotator class and setting it appropriately in each annotator. Comprehensive tests are also included to ensure the correct policy is declared by all annotators.Annotator mask requirement policy:
requires_maskclass variable toBaseAnnotatorto indicate whether an annotator requiresDetections.mask. This allows integrations to check mask requirements before materializing mask payloads.requires_mask = TrueforMaskAnnotator,PolygonAnnotator, andHaloAnnotator, indicating these annotators require mask data. [1] [2] [3]requires_mask = FalseforComparisonAnnotatorto explicitly indicate it does not require mask data.Testing:
TestAnnotatorMaskPolicytests to verify that all annotators correctly declare their mask requirement policy via therequires_maskattribute.