Merge pull request #1823 from roboflow/utils/xyxy_to_xyah

feat: ✨ add xyxy_to_xcycarh conversion function

docs/detection/utils.md

@@ -95,6 +95,12 @@ status: new
 
 :::supervision.detection.utils.xyxy_to_xywh
 
+<div class="md-typeset">
+  <h2><a href="#supervision.detection.utils.xyxy_to_xcycarh">xyxy_to_xcycarh</a></h2>
+</div>
+
+:::supervision.detection.utils.xyxy_to_xcycarh
+
 <div class="md-typeset">
   <h2><a href="#supervision.detection.utils.xcycwh_to_xyxy">xcycwh_to_xyxy</a></h2>
 </div>

supervision/__init__.py

@@ -76,6 +76,7 @@ from supervision.detection.utils import (
     xcycwh_to_xyxy,
     xywh_to_xyxy,
     xyxy_to_polygons,
+    xyxy_to_xcycarh,
     xyxy_to_xywh,
 )
 from supervision.detection.vlm import LMM, VLM
@@ -225,5 +226,6 @@ __all__ = [
     "xcycwh_to_xyxy",
     "xywh_to_xyxy",
     "xyxy_to_polygons",
+    "xyxy_to_xyah",
     "xyxy_to_xywh",
 ]

supervision/detection/utils.py

@@ -397,6 +397,56 @@ def xcycwh_to_xyxy(xcycwh: np.ndarray) -> np.ndarray:
     return xyxy
 
 
+def xyxy_to_xcycarh(xyxy: np.ndarray) -> np.ndarray:
+    """
+    Converts bounding box coordinates from `(x_min, y_min, x_max, y_max)`
+    into measurement space to format `(center x, center y, aspect ratio, height)`,
+    where the aspect ratio is `width / height`.
+
+    Args:
+        xyxy (np.ndarray): Bounding box in format `(x1, y1, x2, y2)`.
+            Expected shape is `(N, 4)`.
+    Returns:
+        np.ndarray: Bounding box in format
+            `(center x, center y, aspect ratio, height)`. Shape `(N, 4)`.
+
+    Examples:
+        ```python
+        import numpy as np
+        import supervision as sv
+
+        xyxy = np.array([
+            [10, 20, 40, 60],
+            [15, 25, 50, 70]
+        ])
+
+        sv.xyxy_to_xcycarh(xyxy=xyxy)
+        # array([
+        #     [25.  , 40.  ,  0.75, 40.  ],
+        #     [32.5 , 47.5 ,  0.77777778, 45.  ]
+        # ])
+        ```
+
+    """
+    if xyxy.size == 0:
+        return np.empty((0, 4), dtype=float)
+
+    x1, y1, x2, y2 = xyxy.T
+    width = x2 - x1
+    height = y2 - y1
+    center_x = x1 + width / 2
+    center_y = y1 + height / 2
+
+    aspect_ratio = np.divide(
+        width,
+        height,
+        out=np.zeros_like(width, dtype=float),
+        where=height != 0,
+    )
+    result = np.column_stack((center_x, center_y, aspect_ratio, height))
+    return result.astype(float)
+
+
 def mask_to_xyxy(masks: np.ndarray) -> np.ndarray:
     """
     Converts a 3D `np.array` of 2D bool masks into a 2D `np.array` of bounding boxes.

test/detection/test_utils.py

@@ -21,6 +21,7 @@ from supervision.detection.utils import (
     scale_boxes,
     xcycwh_to_xyxy,
     xywh_to_xyxy,
+    xyxy_to_xcycarh,
     xyxy_to_xywh,
 )
 
@@ -1405,6 +1406,57 @@ def test_xyxy_to_xywh(xyxy: np.ndarray, expected_result: np.ndarray) -> None:
     np.testing.assert_array_equal(result, expected_result)
 
 
+@pytest.mark.parametrize(
+    "xyxy, expected_result",
+    [
+        # Empty and zero cases
+        (np.array([]).reshape(0, 4), np.array([]).reshape(0, 4)),  # empty array
+        (
+            np.array([[0, 0, 0, 0]]),
+            np.array([[0, 0, 0.0, 0]]),
+        ),  # zero size bounding box
+        (
+            np.array([[10, 10, 10, 10]]),
+            np.array([[10, 10, 0.0, 0]]),
+        ),  # point (x1=x2, y1=y2)
+        # Zero width/height cases
+        (np.array([[50, 50, 80, 50]]), np.array([[65, 50, 0.0, 0]])),  # zero height
+        (np.array([[50, 50, 50, 80]]), np.array([[50, 65, 0.0, 30]])),  # zero width
+        # Standard cases
+        (np.array([[10, 20, 40, 60]]), np.array([[25, 40, 0.75, 40]])),  # standard case
+        (
+            np.array([[-30, -40, -10, -20]]),
+            np.array([[-20, -30, 1.0, 20]]),
+        ),  # all negative values
+        (
+            np.array([[0.1, 0.2, 0.4, 0.6]]),
+            np.array([[0.25, 0.4, 0.75, 0.4]]),
+        ),  # values between 0-1
+        # Different aspect ratios
+        (
+            np.array([[10, 20, 50, 100]]),
+            np.array([[30, 60, 0.5, 80]]),
+        ),  # tall rectangle (height > width)
+        (
+            np.array([[20, 10, 100, 50]]),
+            np.array([[60, 30, 2.0, 40]]),
+        ),  # wide rectangle (width > height)
+        (
+            np.array([[50, 50, 150, 150]]),
+            np.array([[100, 100, 1.0, 100]]),
+        ),  # height == width
+        # Multiple boxes in one array
+        (
+            np.array([[0, 0, 0, 0], [10, 20, 40, 60]]),
+            np.array([[0, 0, 0.0, 0], [25, 40, 0.75, 40]]),
+        ),  # one zero-sized box and one normal box
+    ],
+)
+def test_xyxy_to_xcycarh(xyxy: np.ndarray, expected_result: np.ndarray) -> None:
+    result = xyxy_to_xcycarh(xyxy)
+    np.testing.assert_allclose(result, expected_result)
+
+
 @pytest.mark.parametrize(
     "xcycwh, expected_result",
     [