refactor: enrich KeyPoints with visibility mask, split confidence fields, and redesign uncertainty annotator

[SkalskiP]

Summary

• Split confidence into two fields: keypoint_confidence (per-keypoint, shape (N, M)) and detection_confidence (per-detection, shape (N,)). The old confidence attribute is preserved as a deprecated property that forwards to keypoint_confidence.
• Add visible mask: A boolean array (N, M) that lets callers mark keypoints as occluded/invisible without dropping data. VertexAnnotator and EdgeAnnotator now skip keypoints (and edges) where visible is False.
• Redesign uncertainty annotator: Replace VertexEllipseAnnotator with VertexUncertaintyAnnotator, which draws concentric filled ellipses at configurable sigma levels with opacity blending and a red-yellow-green color gradient.
• Clean up validators: Remove deprecated shims (validate_keypoint_confidence, validate_keypoints_fields), rename validate_confidence to validate_detection_confidence, and add validate_visible. Improve error messages with dimension-specific diagnostics.

[codecov]

Codecov Report

❌ Patch coverage is 88.76812% with 31 lines in your changes missing coverage. Please review.
✅ Project coverage is 80%. Comparing base (b8ebc14) to head (e6f8827).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2286   +/-   ##
=======================================
  Coverage       80%     80%           
=======================================
  Files           66      66           
  Lines         8787    8879   +92     
=======================================
+ Hits          7046    7126   +80     
- Misses        1741    1753   +12     

🚀 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 updates the KeyPoints container to better represent keypoint- and detection-level confidence while adding a per-keypoint visible mask, and then propagates those semantics through keypoint annotators (including a redesign of the uncertainty visualizer). It also refreshes validators, tests, and documentation to match the new API, and adds explicit API design principles to CONTRIBUTING.

Changes:

• Refactors KeyPoints to add keypoint_confidence, detection_confidence, and optional visible, while keeping confidence as a deprecated forwarder.
• Updates keypoint annotators (VertexAnnotator, EdgeAnnotator, VertexLabelAnnotator) to honor visible, adds multi-skeleton support (per-class edges/labels), and replaces VertexEllipseAnnotator with VertexUncertaintyAnnotator.
• Cleans up validators and adjusts tests/docs to cover and demonstrate the new behavior.

Quality (n/5):

• Code quality: 4/5
• Testing: 4/5
• Docs: 3/5

Reviewed changes

Copilot reviewed 10 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
uv.lock	Bumps dev version metadata and relaxes pydeprecate upper bound.
tests/key_points/test_from_rfdetr.py	Removes RF-DETR conversion tests (conversion path removed).
tests/key_points/test_core.py	Adds coverage for detection_confidence filtering and visible propagation; updates confidence naming.
tests/key_points/test_annotators.py	Adds visibility behavior tests; updates uncertainty annotator tests to new class.
tests/helpers.py	Updates KeyPoints factory helper to support detection_confidence and visible.
src/supervision/validators/__init__.py	Splits detection vs keypoint confidence validation and adds validate_visible.
src/supervision/key_points/core.py	Implements new KeyPoints fields, deprecates .confidence, updates slicing/filtering behavior.
src/supervision/key_points/annotators.py	Honors visible, adds per-class skeleton/labels support, and introduces VertexUncertaintyAnnotator.
src/supervision/__init__.py	Exports VertexUncertaintyAnnotator instead of VertexEllipseAnnotator.
docs/keypoint/annotators.md	Renames the uncertainty annotator section and API references.
.gitignore	Ignores a local test script.
.github/CONTRIBUTING.md	Adds explicit API design principles for integrations/annotators/containers.

[Borda]

I would probably go with just one as default but that is also fine

[Borda]

could be good to have also just palet as input and colours will be sapled based on nb sigmas

[Borda]

To match the colors, can we also have optical for each sigma?

[Copilot]

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

docs/keypoint/annotators.md:96

• The VertexEllipseAnnotator example no longer sets key_points.data['covariance'], but VertexEllipseAnnotator.annotate() raises a ValueError when covariance is missing. As written, this snippet won’t run.

    ```python
    import supervision as sv

    image = ...
    key_points = sv.KeyPoints(...)

    ellipse_annotator = sv.VertexEllipseAnnotator(
        color=sv.Color.GREEN,
        sigma=2.0,
    )
    annotated_frame = ellipse_annotator.annotate(
        scene=image.copy(),
        key_points=key_points,
    )
    ```

[Borda]

seems like your IDE does not follow max docsting length