@@ -7,6 +7,8 @@ date_modified: 2026-10-16
 
 ### Unreleased <small>upcoming</small>
 
+- Keypoint annotators use x/y when drawing accepted three-coordinate keypoints. Vertex and ellipse drawing no longer raises a tuple-unpacking error, and edge and label visibility checks ignore the extra coordinate. Rendering matches equivalent two-coordinate input, including missing-point and explicit-visibility handling. ([#2759](https://github.com/roboflow/supervision/pull/2759))
+
 - `sv.metrics.MeanAverageRecall` now follows COCO's last-target tie rule when multiple eligible targets have the same IoU. This preserves confidence-ordered matching and the crowd/ignore handling added in #2750. ([#2758](https://github.com/roboflow/supervision/pull/2758))
 
 - `sv.MaskAnnotator` and `sv.HaloAnnotator` now annotate grayscale scenes, shaped `(H, W)` or `(H, W, 1)` or given as a Pillow `"L"` image, instead of raising `ValueError`. Masks and halos take the first (blue) channel of their color, the gray value OpenCV writes for boxes and polygons on the same scene. ([#2755](https://github.com/roboflow/supervision/pull/2755))
 
@@ -82,8 +82,8 @@ def annotate(self, scene: ImageType, key_points: KeyPoints) -> ImageType:
         Args:
             scene: The image where skeleton vertices will be drawn. `ImageType` is a
                 flexible type, accepting either `numpy.ndarray` or `PIL.Image.Image`.
-            key_points: A collection of key points where each key point consists of x
-                and y coordinates.
+            key_points: A collection of key points. Only the first two coordinate
+                channels, x and y, determine pixel positions.
 
         Returns:
             The annotated image, matching the type of `scene` (`numpy.ndarray`
@@ -116,7 +116,7 @@ def annotate(self, scene: ImageType, key_points: KeyPoints) -> ImageType:
             return scene
 
         for detection_index, xy in enumerate(key_points.xy):
-            for point_index, (x, y) in enumerate(xy):
+            for point_index, (x, y) in enumerate(xy[:, :2]):
                 if np.allclose((x, y), 0) or not _has_finite_coordinates((x, y)):
                     continue
                 if (
@@ -169,8 +169,8 @@ def __init__(
     def annotate(self, scene: ImageType, key_points: KeyPoints) -> ImageType:
         """Annotates the given scene by drawing lines between specified key points to
         form edges. Edges where either endpoint is marked as not visible via
-        ``key_points.visible``, or where either endpoint has a non-finite coordinate,
-        are skipped.
+        ``key_points.visible``, or where either endpoint has a non-finite x/y
+        coordinate, are skipped. An extra coordinate does not affect drawing.
 
         Args:
             scene: The image where skeleton edges will be drawn. `ImageType` is a
@@ -265,8 +265,8 @@ def annotate(self, scene: ImageType, key_points: KeyPoints) -> ImageType:
 
             for edge in edges:
                 idx_a, idx_b = _validate_edge_indices(edge=edge, vertex_count=len(xy))
-                xy_a = xy[idx_a]
-                xy_b = xy[idx_b]
+                xy_a = xy[idx_a, :2]
+                xy_b = xy[idx_b, :2]
                 if np.allclose(xy_a, 0) or np.allclose(xy_b, 0):
                     continue
                 if not _has_finite_coordinates(xy_a) or not _has_finite_coordinates(
@@ -363,13 +363,13 @@ def _decompose_covariance(
     def _iter_ellipse_params(
         self, key_points: KeyPoints
     ) -> list[list[tuple[tuple[int, int], tuple[int, int], float, float, Color]]]:
-        """Return ellipse params grouped by sigma level (outermost first)."""
+        """Return image-space ellipse params, using x/y, outermost level first."""
         covariances = self._get_covariances(key_points)
         levels: list[
             list[tuple[tuple[int, int], tuple[int, int], float, float, Color]]
         ] = [[] for _ in self.sigma]
         for detection_index, xy in enumerate(key_points.xy):
-            for point_index, (x, y) in enumerate(xy):
+            for point_index, (x, y) in enumerate(xy[:, :2]):
                 if np.allclose((x, y), 0) or not _has_finite_coordinates((x, y)):
                     continue
                 if (
@@ -886,7 +886,7 @@ def annotate(
         all_text_colors: list[Color] = []
 
         for i in range(skeletons_count):
-            xy = key_points.xy[i]
+            xy = key_points.xy[i, :, :2]
 
             class_id = (
                 int(key_points.class_id[i]) if key_points.class_id is not None else None
 
@@ -6,6 +6,80 @@
 from tests.helpers import assert_image_mostly_same
 
 
+class TestThreeCoordinateKeyPointAnnotators:
+    @pytest.mark.parametrize(
+        "annotator_name", ["EdgeAnnotator", "VertexLabelAnnotator"]
+    )
+    @pytest.mark.parametrize("dtype", ["float32", "float64"])
+    @pytest.mark.parametrize("depth", [0.5, np.nan, np.inf, -np.inf])
+    @pytest.mark.parametrize("visible", [None, True, False])
+    def test_depth_does_not_change_xy_checks(
+        self, annotator_name: str, dtype: str, depth: float, visible: bool | None
+    ) -> None:
+        """Depth preserves x/y validity, missing points and explicit visibility."""
+        scene = np.zeros((64, 64, 3), dtype=np.uint8)
+        xy = np.array([[[0, 0], [25, 30], [50, 45], [np.nan, 30]]], dtype=dtype)
+        xyz = np.concatenate([xy, np.full((1, 4, 1), depth, dtype=dtype)], axis=2)
+        visibility = None if visible is None else np.full((1, 4), visible)
+        points = sv.KeyPoints(xy=xyz.copy(), visible=visibility)
+        reference = sv.KeyPoints(xy=xy.copy(), visible=visibility)
+        annotator = (
+            sv.EdgeAnnotator(edges=[(1, 2), (2, 3), (3, 4)])
+            if annotator_name == "EdgeAnnotator"
+            else sv.VertexLabelAnnotator()
+        )
+        expected = annotator.annotate(scene.copy(), reference)
+
+        actual = annotator.annotate(scene.copy(), points)
+
+        np.testing.assert_array_equal(actual, expected)
+        assert bool(np.any(actual)) is (visible is not False)
+        np.testing.assert_array_equal(points.xy, xyz)
+        if visible is None:
+            assert points.visible is None
+        else:
+            np.testing.assert_array_equal(points.visible, np.full((1, 4), visible))
+
+    @pytest.mark.parametrize(
+        "annotator_name",
+        [
+            "VertexAnnotator",
+            "VertexEllipseAreaAnnotator",
+            "VertexEllipseOutlineAnnotator",
+            "VertexEllipseHaloAnnotator",
+        ],
+    )
+    @pytest.mark.parametrize("dtype", ["float32", "float64"])
+    @pytest.mark.parametrize("hidden", [False, True])
+    def test_matches_two_coordinate_rendering(
+        self, annotator_name: str, dtype: str, hidden: bool
+    ) -> None:
+        """An extra coordinate leaves pixel rendering and visibility unchanged."""
+        scene = np.zeros((64, 64, 3), dtype=np.uint8)
+        xy = np.array([[[25.0, 30.0], [0.0, 0.0], [np.nan, np.nan]]], dtype=dtype)
+        xyz = np.concatenate([xy, np.full((1, 3, 1), 0.2, dtype=dtype)], axis=2)
+        visible = np.array([[not hidden, True, True]])
+        covariance = np.tile(np.eye(2, dtype=np.float32) * 9, (1, 3, 1, 1))
+        points = sv.KeyPoints(
+            xy=xyz.copy(),
+            visible=visible.copy(),
+            data={"covariance": covariance.copy()},
+        )
+        reference = sv.KeyPoints(
+            xy=xy, visible=visible, data={"covariance": covariance}
+        )
+        annotator = getattr(sv, annotator_name)()
+        expected = annotator.annotate(scene.copy(), reference)
+
+        actual = annotator.annotate(scene.copy(), points)
+
+        np.testing.assert_array_equal(actual, expected)
+        assert bool(np.any(actual)) is not hidden
+        np.testing.assert_array_equal(points.xy, xyz)
+        np.testing.assert_array_equal(points.visible, visible)
+        np.testing.assert_array_equal(points.data["covariance"], covariance)
+
+
 class TestVertexAnnotator:
     """Verify that VertexAnnotator correctly draws keypoints on an image.
 
@@ -245,20 +319,14 @@ def test_non_finite_endpoint_does_not_hide_finite_edges(self, scene):
         result = annotator.annotate(scene=scene.copy(), key_points=key_points)
         assert not np.array_equal(result, scene)
 
-    def test_non_finite_z_skips_edge_despite_finite_xy(self, scene):
-        """A finite (x, y) pair with a non-finite z component is skipped.
-
-        Pins the current full-row finiteness rule, which matches
-        `KeyPoints.as_detections`: a non-finite z vetoes drawing even though z is never
-        rasterized by EdgeAnnotator. A future change to only check (x, y) should be a
-        deliberate decision, not an accidental one.
-        """
+    def test_non_finite_z_does_not_hide_finite_xy(self, scene):
+        """Edges use finite x/y coordinates even when depth is non-finite."""
         key_points = sv.KeyPoints(
             xy=np.array([[[10.0, 10.0, np.nan], [90.0, 90.0, 1.0]]], dtype=np.float32),
         )
         annotator = sv.EdgeAnnotator(edges=[(1, 2)])
         result = annotator.annotate(scene=scene.copy(), key_points=key_points)
-        assert np.array_equal(result, scene)
+        assert not np.array_equal(result, scene)
 
     def test_all_non_finite_multi_detection_draws_nothing(self, scene):
         """A fully non-finite, multi-detection, multi-point array draws nothing and does
@@ -634,20 +702,14 @@ def test_non_finite_vertex_skipped_when_visible_is_set(self, scene):
         result = annotator.annotate(scene=scene.copy(), key_points=key_points)
         assert not np.array_equal(result, scene)
 
-    def test_non_finite_z_skips_label_despite_finite_xy(self, scene):
-        """A finite (x, y) pair with a non-finite z component is skipped.
-
-        Pins the current full-row finiteness rule, which matches
-        `KeyPoints.as_detections`: a non-finite z vetoes drawing even though z is never
-        rasterized by VertexLabelAnnotator. A future change to only check (x, y) should
-        be a deliberate decision, not an accidental one.
-        """
+    def test_non_finite_z_does_not_hide_finite_xy(self, scene):
+        """Labels use finite x/y coordinates even when depth is non-finite."""
         key_points = sv.KeyPoints(
             xy=np.array([[[50.0, 50.0, np.nan]]], dtype=np.float32),
         )
         annotator = sv.VertexLabelAnnotator()
         result = annotator.annotate(scene=scene.copy(), key_points=key_points)
-        assert np.array_equal(result, scene)
+        assert not np.array_equal(result, scene)
 
     def test_all_non_finite_multi_detection_draws_nothing(self, scene):
         """A fully non-finite, multi-detection, multi-point array draws nothing and does