feat(keypoints): add RF-DETR keypoint conversion bridge

Co-authored-by: Codex <codex@openai.com>

Author: Borda

src/supervision/key_points/core.py

@@ -670,6 +670,66 @@ def from_transformers(cls, transformers_results: Any) -> KeyPoints:
         else:
             return cls.empty()
 
+    @classmethod
+    def from_rfdetr(cls, detections: Detections) -> KeyPoints:
+        """
+        Create a `sv.KeyPoints` object from RF-DETR keypoint predictions.
+
+        RF-DETR stores keypoints under `sv.Detections.data["keypoints"]` with shape
+        `(N, K, 3)`, where each keypoint is `(x, y, confidence)`.
+
+        Args:
+            detections: RF-DETR detections containing keypoints in
+                `detections.data["keypoints"]`.
+
+        Returns:
+            A `sv.KeyPoints` object containing xy coordinates, confidence, and class IDs.
+
+        Raises:
+            ValueError: If keypoints are missing or have invalid shape.
+
+        Examples:
+            ```pycon
+            >>> import numpy as np
+            >>> import supervision as sv
+            >>> detections = sv.Detections(
+            ...     xyxy=np.array([[0, 0, 10, 10]], dtype=np.float32),
+            ...     class_id=np.array([0], dtype=int),
+            ...     data={"keypoints": np.array([[[1, 2, 0.9], [3, 4, 0.8]]], dtype=np.float32)},
+            ... )
+            >>> key_points = sv.KeyPoints.from_rfdetr(detections)
+            >>> key_points.xy.shape
+            (1, 2, 2)
+            >>> key_points.confidence.shape
+            (1, 2)
+
+            ```
+        """
+        if "keypoints" not in detections.data:
+            raise ValueError(
+                "RF-DETR keypoints are missing. Expected detections.data['keypoints'] with shape (N, K, 3)."
+            )
+
+        keypoints = np.asarray(detections.data["keypoints"], dtype=np.float32)
+        if keypoints.ndim != 3 or keypoints.shape[-1] != 3:
+            raise ValueError(
+                "RF-DETR keypoints must have shape (N, K, 3) with (x, y, confidence) values."
+            )
+
+        xy = keypoints[..., :2].astype(np.float32, copy=False)
+        confidence = keypoints[..., 2].astype(np.float32, copy=False)
+        class_id = (
+            detections.class_id.astype(int, copy=False)
+            if detections.class_id is not None
+            else None
+        )
+
+        return cls(
+            xy=xy,
+            confidence=confidence,
+            class_id=class_id,
+        )
+
     def _get_by_2d_bool_mask(self, mask: npt.NDArray[np.bool_]) -> KeyPoints:
         """Filter keypoints using a 2D boolean mask of shape `(n, m)`.
 

tests/key_points/test_from_rfdetr.py

@@ -0,0 +1,67 @@
+import numpy as np
+import pytest
+
+import supervision as sv
+
+
+def test_keypoints_from_rfdetr_detections() -> None:
+    """Converts RF-DETR detections.data['keypoints'] into a KeyPoints object."""
+    detections = sv.Detections(
+        xyxy=np.array([[0, 0, 10, 10], [10, 10, 20, 20]], dtype=np.float32),
+        class_id=np.array([1, 3], dtype=int),
+        data={
+            "keypoints": np.array(
+                [
+                    [[1.0, 2.0, 0.9], [3.0, 4.0, 0.8]],
+                    [[5.0, 6.0, 0.7], [7.0, 8.0, 0.6]],
+                ],
+                dtype=np.float32,
+            )
+        },
+    )
+
+    key_points = sv.KeyPoints.from_rfdetr(detections)
+
+    assert key_points.xy.shape == (2, 2, 2)
+    assert key_points.confidence is not None
+    assert key_points.confidence.shape == (2, 2)
+    assert key_points.class_id is not None
+    assert np.array_equal(key_points.class_id, np.array([1, 3], dtype=int))
+
+
+def test_keypoints_from_rfdetr_missing_keypoints_raises_clear_error() -> None:
+    """Missing detections.data['keypoints'] raises a clear conversion error."""
+    detections = sv.Detections(
+        xyxy=np.array([[0, 0, 10, 10]], dtype=np.float32),
+        class_id=np.array([0], dtype=int),
+    )
+
+    with pytest.raises(ValueError, match="detections.data\\['keypoints'\\]"):
+        sv.KeyPoints.from_rfdetr(detections)
+
+
+def test_keypoints_from_rfdetr_malformed_shape_raises_clear_error() -> None:
+    """Malformed keypoints shape raises a clear conversion error."""
+    detections = sv.Detections(
+        xyxy=np.array([[0, 0, 10, 10]], dtype=np.float32),
+        class_id=np.array([0], dtype=int),
+        data={"keypoints": np.array([[[1.0, 2.0]]], dtype=np.float32)},
+    )
+
+    with pytest.raises(ValueError, match="shape \\(N, K, 3\\)"):
+        sv.KeyPoints.from_rfdetr(detections)
+
+
+def test_keypoint_annotator_uses_vertex_and_edge_rendering() -> None:
+    """Converted RF-DETR keypoints are consumable by vertex and edge annotators."""
+    scene = np.zeros((32, 32, 3), dtype=np.uint8)
+    detections = sv.Detections(
+        xyxy=np.array([[0, 0, 10, 10]], dtype=np.float32),
+        data={"keypoints": np.array([[[10.0, 10.0, 0.9], [20.0, 20.0, 0.8]]], dtype=np.float32)},
+    )
+    key_points = sv.KeyPoints.from_rfdetr(detections)
+
+    scene = sv.VertexAnnotator().annotate(scene=scene, key_points=key_points)
+    scene = sv.EdgeAnnotator(edges=[(1, 2)]).annotate(scene=scene, key_points=key_points)
+
+    assert np.any(scene != 0)