Merge pull request #651 from roboflow/feature/scale_boxes_utility

Add `scale_boxes` function to detection utils

Author: SkalskiP

docs/detection/utils.md

@@ -25,3 +25,11 @@
 ## filter_polygons_by_area
 
 :::supervision.detection.utils.filter_polygons_by_area
+
+## move_boxes
+
+:::supervision.detection.utils.move_boxes
+
+## scale_boxes
+
+:::supervision.detection.utils.scale_boxes

supervision/__init__.py

@@ -40,9 +40,11 @@
     filter_polygons_by_area,
     mask_to_polygons,
     mask_to_xyxy,
+    move_boxes,
     non_max_suppression,
     polygon_to_mask,
     polygon_to_xyxy,
+    scale_boxes,
 )
 from supervision.draw.color import Color, ColorPalette
 from supervision.draw.utils import (

supervision/detection/utils.py

@@ -383,18 +383,65 @@ def process_roboflow_result(
 
 def move_boxes(xyxy: np.ndarray, offset: np.ndarray) -> np.ndarray:
     """
-    Args:
+    Parameters:
         xyxy (np.ndarray): An array of shape `(n, 4)` containing the bounding boxes
             coordinates in format `[x1, y1, x2, y2]`
         offset (np.array): An array of shape `(2,)` containing offset values in format
             is `[dx, dy]`.
 
     Returns:
-        (np.ndarray) repositioned bounding boxes
+        np.ndarray: Repositioned bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> offset = np.array([5, 5])
+        >>> sv.move_boxes(boxes, offset)
+        ... array([
+        ...     [15, 15, 25, 25],
+        ...     [35, 35, 45, 45]
+        ... ])
+        ```
     """
     return xyxy + np.hstack([offset, offset])
 
 
+def scale_boxes(xyxy: np.ndarray, factor: float) -> np.ndarray:
+    """
+    Scale the dimensions of bounding boxes.
+
+    Parameters:
+        xyxy (np.ndarray): An array of shape `(n, 4)` containing the bounding boxes
+            coordinates in format `[x1, y1, x2, y2]`
+        factor (float): A float value representing the factor by which the box
+            dimensions are scaled. A factor greater than 1 enlarges the boxes, while a
+            factor less than 1 shrinks them.
+
+    Returns:
+        np.ndarray: Scaled bounding boxes.
+
+    Example:
+        ```python
+        >>> import numpy as np
+        >>> import supervision as sv
+
+        >>> boxes = np.array([[10, 10, 20, 20], [30, 30, 40, 40]])
+        >>> factor = 1.5
+        >>> sv.scale_boxes(boxes, factor)
+        ... array([
+        ...     [ 7.5,  7.5, 22.5, 22.5],
+        ...     [27.5, 27.5, 42.5, 42.5]
+        ... ])
+        ```
+    """
+    centers = (xyxy[:, :2] + xyxy[:, 2:]) / 2
+    new_sizes = (xyxy[:, 2:] - xyxy[:, :2]) * factor
+    return np.concatenate((centers - new_sizes / 2, centers + new_sizes / 2), axis=1)
+
+
 def calculate_masks_centroids(masks: np.ndarray) -> np.ndarray:
     """
     Calculate the centroids of binary masks in a tensor.

test/detection/test_utils.py

@@ -11,6 +11,7 @@
     move_boxes,
     non_max_suppression,
     process_roboflow_result,
+    scale_boxes,
 )
 
 TEST_MASK = np.zeros((1, 1000, 1000), dtype=bool)
@@ -504,6 +505,52 @@ def test_move_boxes(
         assert np.array_equal(result, expected_result)
 
 
+@pytest.mark.parametrize(
+    "xyxy, factor, expected_result, exception",
+    [
+        (
+            np.empty(shape=(0, 4)),
+            2.0,
+            np.empty(shape=(0, 4)),
+            DoesNotRaise(),
+        ),  # empty xyxy array
+        (
+            np.array([[0, 0, 10, 10]]),
+            1.0,
+            np.array([[0, 0, 10, 10]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 1.0
+        (
+            np.array([[0, 0, 10, 10]]),
+            2.0,
+            np.array([[-5, -5, 15, 15]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 2.0
+        (
+            np.array([[0, 0, 10, 10]]),
+            0.5,
+            np.array([[2.5, 2.5, 7.5, 7.5]]),
+            DoesNotRaise(),
+        ),  # single box with factor equal to 0.5
+        (
+            np.array([[0, 0, 10, 10], [10, 10, 30, 30]]),
+            2.0,
+            np.array([[-5, -5, 15, 15], [0, 0, 40, 40]]),
+            DoesNotRaise(),
+        ),  # two boxes with factor equal to 2.0
+    ],
+)
+def test_scale_boxes(
+    xyxy: np.ndarray,
+    factor: float,
+    expected_result: np.ndarray,
+    exception: Exception,
+) -> None:
+    with exception:
+        result = scale_boxes(xyxy=xyxy, factor=factor)
+        assert np.array_equal(result, expected_result)
+
+
 @pytest.mark.parametrize(
     "masks, expected_result, exception",
     [