From f563c5a63472380ca261e64656a95e6a0ad4f33c Mon Sep 17 00:00:00 2001
From: SkalskiP <piotr.skalski92@gmail.com>
Date: Fri, 14 Nov 2025 12:53:58 +0100
Subject: [PATCH] update `denormalize_boxes` docstring and examples

---
 supervision/detection/utils/boxes.py | 67 ++++++++++++++++------------
 test/detection/utils/test_boxes.py   |  4 +-
 2 files changed, 40 insertions(+), 31 deletions(-)

diff --git a/supervision/detection/utils/boxes.py b/supervision/detection/utils/boxes.py
index 60542a43..44b78cba 100644
--- a/supervision/detection/utils/boxes.py
+++ b/supervision/detection/utils/boxes.py
@@ -95,24 +95,27 @@ def pad_boxes(xyxy: np.ndarray, px: int, py: int | None = None) -> np.ndarray:
 
 
 def denormalize_boxes(
-    normalized_xyxy: np.ndarray,
+    xyxy: np.ndarray,
     resolution_wh: tuple[int, int],
     normalization_factor: float = 1.0,
 ) -> np.ndarray:
     """
-    Converts normalized bounding box coordinates to absolute pixel values.
+    Convert normalized bounding box coordinates to absolute pixel coordinates.
+
+    Multiplies each bounding box coordinate by image size and divides by
+    `normalization_factor`, mapping values from normalized `[0, normalization_factor]`
+    to absolute pixel values for a given resolution.
 
     Args:
-        normalized_xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each row
-            contains normalized coordinates in the format `(x_min, y_min, x_max, y_max)`,
-            with values between 0 and `normalization_factor`.
-        resolution_wh (Tuple[int, int]): A tuple `(width, height)` representing the
-            target image resolution.
-        normalization_factor (float, optional): The normalization range of the input
-            coordinates. Defaults to 1.0.
+        xyxy (`numpy.ndarray`): Normalized bounding boxes of shape `(N, 4)`,
+            where each row is `(x_min, y_min, x_max, y_max)`, values in
+            `[0, normalization_factor]`.
+        resolution_wh (`tuple[int, int]`): Target image resolution as `(width, height)`.
+        normalization_factor (`float`): Maximum value of input coordinate range.
+            Defaults to `1.0`.
 
     Returns:
-        np.ndarray: An array of shape `(N, 4)` with absolute coordinates in
+        (`numpy.ndarray`): Array of shape `(N, 4)` with absolute coordinates in
             `(x_min, y_min, x_max, y_max)` format.
 
     Examples:
@@ -120,32 +123,38 @@ def denormalize_boxes(
         import numpy as np
         import supervision as sv
 
-        # Default normalization (0-1)
         normalized_xyxy = np.array([
             [0.1, 0.2, 0.5, 0.6],
-            [0.3, 0.4, 0.7, 0.8]
+            [0.3, 0.4, 0.7, 0.8],
+            [0.2, 0.1, 0.6, 0.5]
         ])
-        resolution_wh = (100, 200)
-        sv.denormalize_boxes(normalized_xyxy, resolution_wh)
+        sv.denormalize_boxes(normalized_xyxy, (1280, 720))
         # array([
-        #     [ 10.,  40.,  50., 120.],
-        #     [ 30.,  80.,  70., 160.]
-        # ])
-
-        # Custom normalization (0-100)
-        normalized_xyxy = np.array([
-            [10., 20., 50., 60.],
-            [30., 40., 70., 80.]
-        ])
-        sv.denormalize_boxes(normalized_xyxy, resolution_wh, normalization_factor=100.0)
-        # array([
-        #     [ 10.,  40.,  50., 120.],
-        #     [ 30.,  80.,  70., 160.]
+        #     [128., 144., 640., 432.],
+        #     [384., 288., 896., 576.],
+        #     [256.,  72., 768., 360.]
         # ])
         ```
-    """  # noqa E501 // docs
+
+        ```
+        import numpy as np
+        import supervision as sv
+
+        normalized_xyxy = np.array([
+            [256., 128., 768., 640.]
+        ])
+        result = sv.denormalize_boxes(
+            normalized_xyxy,
+            (1280, 720),
+            normalization_factor=1024.0
+        )
+        # array([
+        #     [320.,  90., 960., 450.]
+        # ])
+        ```
+    """
     width, height = resolution_wh
-    result = normalized_xyxy.copy()
+    result = xyxy.copy()
 
     result[:, [0, 2]] = (result[:, [0, 2]] * width) / normalization_factor
     result[:, [1, 3]] = (result[:, [1, 3]] * height) / normalization_factor
diff --git a/test/detection/utils/test_boxes.py b/test/detection/utils/test_boxes.py
index b27dd87d..787c970f 100644
--- a/test/detection/utils/test_boxes.py
+++ b/test/detection/utils/test_boxes.py
@@ -219,7 +219,7 @@ def test_scale_boxes(
     ],
 )
 def test_denormalize_boxes(
-    normalized_xyxy: np.ndarray,
+    xyxy: np.ndarray,
     resolution_wh: tuple[int, int],
     normalization_factor: float,
     expected_result: np.ndarray,
@@ -227,7 +227,7 @@ def test_denormalize_boxes(
 ) -> None:
     with exception:
         result = denormalize_boxes(
-            normalized_xyxy=normalized_xyxy,
+            xyxy=xyxy,
             resolution_wh=resolution_wh,
             normalization_factor=normalization_factor,
         )