Files
supervision/tests/key_points/test_annotators.py
T
918b6139ef feat(keypoints): add keypoint conversion bridge (#2277)
* feat(keypoints): add RF-DETR keypoint conversion bridge
* feat: add RF-DETR keypoint uncertainty visualization
* refactor(keypoints): remove deprecated RF-DETR keypoint conversion logic
* refactor: improve internal handling of keypoint data and detection utilities
* fix(keypoints): handle non-finite confidence values and empty keypoint arrays
* docs(keypoint): add VertexEllipseAnnotator to annotators docs
* docs(keypoints): add Example block to KeyPoints.from_rfdetr docstring
* docs(keypoints): document source_shape HW ordering in from_rfdetr
* feat(keypoints): validate precision_cholesky shape in from_rfdetr
* refine(keypoints): add warning log for silent precision matrix failures
* fix(keypoints): fix mypy type errors in VertexEllipseAnnotator
* test(keypoints): add confidence_threshold filter test for VertexEllipseAnnotator
* test(keypoints): add max_axis_length cap and constructor validator tests
* docs(keypoints): document max_axis_length=None risk in VertexEllipseAnnotator
* docs(keypoints): add Raises section to VertexEllipseAnnotator.annotate docstring
* docs(keypoints): document confidence scale convention in from_rfdetr
* docs(keypoints): note from_rfdetr input convention in KeyPoints class docstring
* fix(types): improve type hinting for internal and keypoints modules
* fix(keypoints): handle None class_id in from_rfdetr conversion

---------

Co-authored-by: Codex <codex@openai.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
2026-05-28 10:36:41 +02:00

304 lines
12 KiB
Python

import numpy as np
import pytest
import supervision as sv
from tests.helpers import assert_image_mostly_same
class TestVertexAnnotator:
"""
Verify that VertexAnnotator correctly draws keypoints on an image.
Ensures that `VertexAnnotator` correctly draws keypoints (vertices) on an image,
which is essential for human pose estimation or similar tasks.
"""
def test_annotate_with_default_parameters(self, scene, sample_key_points):
"""
Verify that VertexAnnotator correctly draws keypoints with default parameters.
Scenario: Annotating a scene using default vertex parameters.
Expected: Scene is modified, showing keypoints at their detected locations.
"""
annotator = sv.VertexAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
# Check that the scene has been modified
assert_image_mostly_same(
original=scene, annotated=result, similarity_threshold=0.8
)
def test_annotate_with_custom_color_and_radius(self, scene, sample_key_points):
"""
Verify that VertexAnnotator respects custom color and radius settings.
Scenario: Annotating a scene with user-specified color and radius.
Expected: Scene is modified according to custom style, allowing users to
distinguish keypoints more clearly or match specific branding.
"""
color = sv.Color.RED
radius = 5
annotator = sv.VertexAnnotator(color=color, radius=radius)
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
# Check that the scene has been modified
assert_image_mostly_same(
original=scene, annotated=result, similarity_threshold=0.7
)
def test_annotate_empty_key_points(self, scene, empty_key_points):
"""
Verify that VertexAnnotator handles empty keypoints without modifying the scene.
Scenario: Annotating a scene with no key points detected.
Expected: Original scene is returned untouched, preventing phantom annotations.
"""
annotator = sv.VertexAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=empty_key_points)
# Should return the original scene unchanged
assert np.array_equal(result, scene)
class TestEdgeAnnotator:
"""
Verify that EdgeAnnotator correctly draws skeleton edges between keypoints.
Ensures that `EdgeAnnotator` correctly draws connections (edges) between keypoints,
forming skeletons that help users interpret spatial relationships.
"""
def test_annotate_with_default_parameters(self, scene, sample_key_points):
"""
Verify correctly draw skeleton edges with default parameters.
Scenario: Annotating a scene with default skeleton (e.g., COCO).
Expected: Skeleton edges are drawn between corresponding keypoints.
"""
annotator = sv.EdgeAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
# Check that the scene has been modified
assert_image_mostly_same(
original=scene, annotated=result, similarity_threshold=0.7
)
def test_annotate_with_custom_edges(self, scene, sample_key_points):
"""
Verify that EdgeAnnotator respects custom-defined skeleton structures.
Scenario: Annotating a scene with a custom-defined skeleton structure.
Expected: Only the specified connections are drawn, giving users flexibility
for non-standard keypoint models.
"""
edges = [(1, 2), (2, 3)]
annotator = sv.EdgeAnnotator(edges=edges)
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
# Check that the scene has been modified
assert_image_mostly_same(
original=scene, annotated=result, similarity_threshold=0.8
)
def test_annotate_empty_key_points(self, scene, empty_key_points):
"""
Verify that EdgeAnnotator handles empty keypoints without modifying the scene.
Scenario: Annotating a scene with no key points for edge drawing.
Expected: Original scene is returned untouched.
"""
annotator = sv.EdgeAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=empty_key_points)
# Should return the original scene unchanged
assert np.array_equal(result, scene)
def test_annotate_no_edges_found(self, scene):
"""
Verify returning unmodified scene when no known skeleton matches.
Scenario: Key points provided don't match any known or provided skeleton.
Expected: No edges are drawn, and the original scene is returned, avoiding
incorrect or nonsensical connections.
"""
# Key points with more vertices than any skeleton
large_key_points = sv.KeyPoints(
xy=np.array([[[i * 10, i * 10] for i in range(100)]], dtype=np.float32),
confidence=np.array([[0.8] * 100], dtype=np.float32),
class_id=np.array([0], dtype=int),
)
annotator = sv.EdgeAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=large_key_points)
# Should return the original scene unchanged (no edges found)
assert np.array_equal(result, scene)
class TestVertexEllipseAnnotator:
"""
Verify that VertexEllipseAnnotator draws covariance ellipses around keypoints.
"""
def test_annotate_with_covariance_data(self, scene, sample_key_points):
"""
Scenario: Annotating keypoints with per-point covariance matrices.
Expected: Scene is modified with ellipses at keypoint locations.
"""
covariance = np.tile(
np.eye(2, dtype=np.float32),
(*sample_key_points.xy.shape[:2], 1, 1),
)
covariance[..., 0, 0] = 25.0
covariance[..., 1, 1] = 9.0
sample_key_points.data["covariance"] = covariance
annotator = sv.VertexEllipseAnnotator(color=sv.Color.RED, sigma=2.0)
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
assert result.shape == scene.shape
assert not np.array_equal(result, scene)
def test_annotate_with_dashed_line_style(self, scene, sample_key_points):
"""
Scenario: Annotating keypoints with dashed covariance ellipses.
Expected: Scene is modified with a low-interference dashed overlay.
"""
covariance = np.tile(
np.eye(2, dtype=np.float32),
(*sample_key_points.xy.shape[:2], 1, 1),
)
covariance[..., 0, 0] = 25.0
covariance[..., 1, 1] = 9.0
sample_key_points.data["covariance"] = covariance
annotator = sv.VertexEllipseAnnotator(
color=sv.Color.RED,
thickness=1,
sigma=2.0,
line_style="dashed",
dash_length=12,
)
result = annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
assert result.shape == scene.shape
assert not np.array_equal(result, scene)
def test_invalid_line_style_raises(self):
"""
Scenario: Invalid line style is requested.
Expected: Clear validation error.
"""
with pytest.raises(ValueError, match="line_style"):
sv.VertexEllipseAnnotator(line_style="dotted")
def test_annotate_empty_key_points(self, scene, empty_key_points):
"""
Scenario: Annotating a scene with no keypoints.
Expected: Original scene is returned untouched.
"""
annotator = sv.VertexEllipseAnnotator()
result = annotator.annotate(scene=scene.copy(), key_points=empty_key_points)
assert np.array_equal(result, scene)
@pytest.mark.parametrize("confidence", [np.nan, np.inf, -np.inf])
def test_annotate_skips_non_finite_confidence(self, scene, confidence):
"""
Scenario: Keypoint confidence is not finite.
Expected: Ellipse is not rendered for invalid confidence values.
"""
key_points = sv.KeyPoints(
xy=np.array([[[40.0, 40.0]]], dtype=np.float32),
confidence=np.array([[confidence]], dtype=np.float32),
data={
"covariance": np.array([[[[25.0, 0.0], [0.0, 9.0]]]], dtype=np.float32)
},
)
annotator = sv.VertexEllipseAnnotator(confidence_threshold=0.0)
result = annotator.annotate(scene=scene.copy(), key_points=key_points)
assert np.array_equal(result, scene)
def test_annotate_missing_covariance_data_raises(self, scene, sample_key_points):
"""
Scenario: Annotating non-empty keypoints without covariance data.
Expected: Clear error explaining the expected data field.
"""
annotator = sv.VertexEllipseAnnotator()
with pytest.raises(ValueError, match="covariance"):
annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
def test_annotate_invalid_covariance_shape_raises(self, scene, sample_key_points):
"""
Scenario: Covariance data does not match keypoint dimensions.
Expected: Clear shape validation error.
"""
sample_key_points.data["covariance"] = np.zeros((1, 1, 2, 2), dtype=np.float32)
annotator = sv.VertexEllipseAnnotator()
with pytest.raises(ValueError, match="Expected covariance shape"):
annotator.annotate(scene=scene.copy(), key_points=sample_key_points)
def test_confidence_threshold_filters_low_confidence_keypoints(self, scene):
"""
Scenario: Two keypoints with confidences 0.3 and 0.7; threshold=0.5.
Expected: Only the high-confidence keypoint is drawn.
"""
cov = np.array([[[[25.0, 0.0], [0.0, 9.0]]]], dtype=np.float32)
key_points_low = sv.KeyPoints(
xy=np.array([[[20.0, 20.0]]], dtype=np.float32),
confidence=np.array([[0.3]], dtype=np.float32),
data={"covariance": cov},
)
key_points_high = sv.KeyPoints(
xy=np.array([[[20.0, 20.0]]], dtype=np.float32),
confidence=np.array([[0.7]], dtype=np.float32),
data={"covariance": cov},
)
annotator = sv.VertexEllipseAnnotator(confidence_threshold=0.5)
result_low = annotator.annotate(scene=scene.copy(), key_points=key_points_low)
result_high = annotator.annotate(scene=scene.copy(), key_points=key_points_high)
assert np.array_equal(result_low, scene), (
"low-confidence keypoint must be skipped"
)
assert not np.array_equal(result_high, scene), (
"high-confidence keypoint must be drawn"
)
def test_max_axis_length_caps_large_eigenvalue(self, scene):
"""
Scenario: Covariance produces eigenvalue much larger than scene; cap applied.
Expected: Scene is modified (ellipse drawn) and axis is clamped to max.
"""
large_cov = np.array([[[[1e6, 0.0], [0.0, 1e6]]]], dtype=np.float32)
key_points = sv.KeyPoints(
xy=np.array([[[50.0, 50.0]]], dtype=np.float32),
data={"covariance": large_cov},
)
annotator = sv.VertexEllipseAnnotator(max_axis_length=10.0)
result = annotator.annotate(scene=scene.copy(), key_points=key_points)
assert result.shape == scene.shape
assert not np.array_equal(result, scene)
@pytest.mark.parametrize(
("kwargs", "match"),
[
({"max_axis_length": 0}, "max_axis_length"),
({"max_axis_length": -1}, "max_axis_length"),
({"sigma": 0}, "sigma"),
({"sigma": -1.0}, "sigma"),
({"thickness": 0}, "thickness"),
({"dash_length": 0}, "dash_length"),
],
)
def test_constructor_raises_on_invalid_params(self, kwargs, match):
"""Scenario: Invalid constructor parameters. Expected: ValueError."""
with pytest.raises(ValueError, match=match):
sv.VertexEllipseAnnotator(**kwargs)