From e12bfe263d89c59d41be535191e1f964fd5a85bc Mon Sep 17 00:00:00 2001
From: SkalskiP <piotr.skalski92@gmail.com>
Date: Sun, 16 Nov 2025 13:27:29 +0100
Subject: [PATCH 1/2] add `box_aspect_ratio` property to `sv.Detections`

---
 supervision/__init__.py              |  2 --
 supervision/detection/core.py        | 37 ++++++++++++++++++++
 supervision/detection/utils/boxes.py | 51 ----------------------------
 3 files changed, 37 insertions(+), 53 deletions(-)

diff --git a/supervision/__init__.py b/supervision/__init__.py
index b74d37054..00820076f 100644
--- a/supervision/__init__.py
+++ b/supervision/__init__.py
@@ -52,7 +52,6 @@
 from supervision.detection.tools.polygon_zone import PolygonZone, PolygonZoneAnnotator
 from supervision.detection.tools.smoother import DetectionsSmoother
 from supervision.detection.utils.boxes import (
-    box_aspect_ratio,
     clip_boxes,
     denormalize_boxes,
     move_boxes,
@@ -200,7 +199,6 @@
     "VideoInfo",
     "VideoSink",
     "approximate_polygon",
-    "box_aspect_ratio",
     "box_iou",
     "box_iou_batch",
     "box_iou_batch_with_jaccard",
diff --git a/supervision/detection/core.py b/supervision/detection/core.py
index e5e298bbb..6ca6abc56 100644
--- a/supervision/detection/core.py
+++ b/supervision/detection/core.py
@@ -2088,6 +2088,43 @@ def box_area(self) -> np.ndarray:
         """
         return (self.xyxy[:, 3] - self.xyxy[:, 1]) * (self.xyxy[:, 2] - self.xyxy[:, 0])
 
+    @property
+    def box_aspect_ratio(self) -> np.ndarray:
+        """
+        Compute the aspect ratio (width divided by height) for each bounding box.
+
+        Returns:
+            np.ndarray: Array of shape `(N,)` containing aspect ratios, where `N` is the
+            number of boxes (width / height for each box).
+
+        Examples:
+            ```python
+            import numpy as np
+            import supervision as sv
+
+            xyxy = np.array([
+                [10, 10, 50, 50],
+                [60, 10, 180, 50],
+                [10, 60, 50, 180],
+            ])
+
+            detections = sv.Detections(xyxy=xyxy)
+
+            detections.box_aspect_ratio
+            # array([1.0, 3.0, 0.33333333])
+
+            ar = detections.box_aspect_ratio
+            detections[(ar < 2.0) & (ar > 0.5)].xyxy
+            # array([[10., 10., 50., 50.]])
+            ```
+        """
+        widths = self.xyxy[:, 2] - self.xyxy[:, 0]
+        heights = self.xyxy[:, 3] - self.xyxy[:, 1]
+
+        aspect_ratios = np.full_like(widths, np.nan, dtype=np.float64)
+        np.divide(widths, heights, out=aspect_ratios, where=heights != 0)
+        return aspect_ratios
+
     def with_nms(
         self,
         threshold: float = 0.5,
diff --git a/supervision/detection/utils/boxes.py b/supervision/detection/utils/boxes.py
index c7f81b3e9..52e4b6956 100644
--- a/supervision/detection/utils/boxes.py
+++ b/supervision/detection/utils/boxes.py
@@ -6,57 +6,6 @@
 from supervision.detection.utils.iou_and_nms import box_iou_batch
 
 
-def box_aspect_ratio(xyxy: np.ndarray) -> np.ndarray:
-    """
-    Calculate aspect ratios of bounding boxes given in xyxy format.
-
-    Computes the width divided by height for each bounding box. Returns NaN
-    for boxes with zero height to avoid division errors.
-
-    Args:
-        xyxy (`numpy.ndarray`): Array of bounding boxes in
-            `(x_min, y_min, x_max, y_max)` format with shape `(N, 4)`.
-
-    Returns:
-        `numpy.ndarray`: Array of aspect ratios with shape `(N,)`, where each element is
-            the width divided by height of a box. Elements are NaN if height is zero.
-
-    Examples:
-        ```python
-        import numpy as np
-        import supervision as sv
-
-        xyxy = np.array([
-            [10, 20, 30, 50],
-            [0, 0, 40, 10],
-        ])
-
-        sv.box_aspect_ratio(xyxy)
-        # array([0.66666667, 4.        ])
-
-        xyxy = np.array([
-            [10, 10, 30, 10],
-            [5, 5, 25, 25],
-        ])
-
-        sv.box_aspect_ratio(xyxy)
-        # array([       nan, 1.        ])
-        ```
-    """
-    widths = xyxy[:, 2] - xyxy[:, 0]
-    heights = xyxy[:, 3] - xyxy[:, 1]
-
-    aspect_ratios = np.full_like(widths, np.nan, dtype=np.float64)
-    np.divide(
-        widths,
-        heights,
-        out=aspect_ratios,
-        where=heights != 0,
-    )
-
-    return aspect_ratios
-
-
 def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
     """
     Clips bounding boxes coordinates to fit within the frame resolution.

From bbc37b4b6a55d18bca94978f94f49602f53cae87 Mon Sep 17 00:00:00 2001
From: SkalskiP <piotr.skalski92@gmail.com>
Date: Sun, 16 Nov 2025 13:34:51 +0100
Subject: [PATCH 2/2] fix failing tests

---
 test/utils/test_internal.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/test/utils/test_internal.py b/test/utils/test_internal.py
index 07674f39c..749d4be3a 100644
--- a/test/utils/test_internal.py
+++ b/test/utils/test_internal.py
@@ -145,6 +145,7 @@ def __private_property(self):
                 "metadata",
                 "area",
                 "box_area",
+                "box_aspect_ratio",
             },
             DoesNotRaise(),
         ),