Skip to content

Boxes Utils

move_boxes

supervision.detection.utils.boxes.move_boxes(xyxy, offset)

Parameters:

Name Type Description Default

xyxy

NDArray[float64]

An array of shape (n, 4) containing the bounding boxes coordinates in format [x1, y1, x2, y2]

 required

offset

array

An array of shape (2,) containing offset values in format is [dx, dy].

 required

Returns:

Type Description
NDArray[float64]

npt.NDArray[np.float64]: Repositioned bounding boxes.

Examples:

import numpy as np
import supervision as sv

xyxy = np.array([
    [10, 10, 20, 20],
    [30, 30, 40, 40]
])
offset = np.array([5, 5])

sv.move_boxes(xyxy=xyxy, offset=offset)
# array([
#    [15, 15, 25, 25],
#    [35, 35, 45, 45]
# ])
Source code in supervision/detection/utils/boxes.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
def move_boxes(
    xyxy: npt.NDArray[np.float64], offset: npt.NDArray[np.int32]
) -> npt.NDArray[np.float64]:
    """
    Parameters:
        xyxy (npt.NDArray[np.float64]): 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:
        npt.NDArray[np.float64]: Repositioned bounding boxes.

    Examples:
        ```python
        import numpy as np
        import supervision as sv

        xyxy = np.array([
            [10, 10, 20, 20],
            [30, 30, 40, 40]
        ])
        offset = np.array([5, 5])

        sv.move_boxes(xyxy=xyxy, offset=offset)
        # array([
        #    [15, 15, 25, 25],
        #    [35, 35, 45, 45]
        # ])
        ```
    """
    return xyxy + np.hstack([offset, offset])

scale_boxes

supervision.detection.utils.boxes.scale_boxes(xyxy, factor)

Scale the dimensions of bounding boxes.

Parameters:

Name Type Description Default

xyxy

NDArray[float64]

An array of shape (n, 4) containing the bounding boxes coordinates in format [x1, y1, x2, y2]

 required

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.

 required

Returns:

Type Description
NDArray[float64]

npt.NDArray[np.float64]: Scaled bounding boxes.

Examples:

import numpy as np
import supervision as sv

xyxy = np.array([
    [10, 10, 20, 20],
    [30, 30, 40, 40]
])

sv.scale_boxes(xyxy=xyxy, factor=1.5)
# array([
#    [ 7.5,  7.5, 22.5, 22.5],
#    [27.5, 27.5, 42.5, 42.5]
# ])
Source code in supervision/detection/utils/boxes.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def scale_boxes(
    xyxy: npt.NDArray[np.float64], factor: float
) -> npt.NDArray[np.float64]:
    """
    Scale the dimensions of bounding boxes.

    Parameters:
        xyxy (npt.NDArray[np.float64]): 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:
        npt.NDArray[np.float64]: Scaled bounding boxes.

    Examples:
        ```python
        import numpy as np
        import supervision as sv

        xyxy = np.array([
            [10, 10, 20, 20],
            [30, 30, 40, 40]
        ])

        sv.scale_boxes(xyxy=xyxy, factor=1.5)
        # 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)

clip_boxes

supervision.detection.utils.boxes.clip_boxes(xyxy, resolution_wh)

Clips bounding boxes coordinates to fit within the frame resolution.

Parameters:

Name Type Description Default

xyxy

ndarray

A numpy array of shape (N, 4) where each row corresponds to a bounding box in the format (x_min, y_min, x_max, y_max).

 required

resolution_wh

Tuple[int, int]

A tuple of the form (width, height) representing the resolution of the frame.

 required

Returns:

Type Description
ndarray

np.ndarray: A numpy array of shape (N, 4) where each row corresponds to a bounding box with coordinates clipped to fit within the frame resolution.

Examples:

import numpy as np
import supervision as sv

xyxy = np.array([
    [10, 20, 300, 200],
    [15, 25, 350, 450],
    [-10, -20, 30, 40]
])

sv.clip_boxes(xyxy=xyxy, resolution_wh=(320, 240))
# array([
#     [ 10,  20, 300, 200],
#     [ 15,  25, 320, 240],
#     [  0,   0,  30,  40]
# ])
Source code in supervision/detection/utils/boxes.py 
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def clip_boxes(xyxy: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
    """
    Clips bounding boxes coordinates to fit within the frame resolution.

    Args:
        xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each
            row corresponds to a bounding box in
            the format `(x_min, y_min, x_max, y_max)`.
        resolution_wh (Tuple[int, int]): A tuple of the form `(width, height)`
            representing the resolution of the frame.

    Returns:
        np.ndarray: A numpy array of shape `(N, 4)` where each row
            corresponds to a bounding box with coordinates clipped to fit
            within the frame resolution.

    Examples:
        ```python
        import numpy as np
        import supervision as sv

        xyxy = np.array([
            [10, 20, 300, 200],
            [15, 25, 350, 450],
            [-10, -20, 30, 40]
        ])

        sv.clip_boxes(xyxy=xyxy, resolution_wh=(320, 240))
        # array([
        #     [ 10,  20, 300, 200],
        #     [ 15,  25, 320, 240],
        #     [  0,   0,  30,  40]
        # ])
        ```
    """
    result = np.copy(xyxy)
    width, height = resolution_wh
    result[:, [0, 2]] = result[:, [0, 2]].clip(0, width)
    result[:, [1, 3]] = result[:, [1, 3]].clip(0, height)
    return result

pad_boxes

supervision.detection.utils.boxes.pad_boxes(xyxy, px, py=None)

Pads bounding boxes coordinates with a constant padding.

Parameters:

Name Type Description Default

xyxy

ndarray

A numpy array of shape (N, 4) where each row corresponds to a bounding box in the format (x_min, y_min, x_max, y_max).

 required

px

int

The padding value to be added to both the left and right sides of each bounding box.

 required

py

Optional[int]

The padding value to be added to both the top and bottom sides of each bounding box. If not provided, px will be used for both dimensions.

 None

Returns:

Type Description
ndarray

np.ndarray: A numpy array of shape (N, 4) where each row corresponds to a bounding box with coordinates padded according to the provided padding values.

Examples:

import numpy as np
import supervision as sv

xyxy = np.array([
    [10, 20, 30, 40],
    [15, 25, 35, 45]
])

sv.pad_boxes(xyxy=xyxy, px=5, py=10)
# array([
#     [ 5, 10, 35, 50],
#     [10, 15, 40, 55]
# ])
Source code in supervision/detection/utils/boxes.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def pad_boxes(xyxy: np.ndarray, px: int, py: int | None = None) -> np.ndarray:
    """
    Pads bounding boxes coordinates with a constant padding.

    Args:
        xyxy (np.ndarray): A numpy array of shape `(N, 4)` where each
            row corresponds to a bounding box in the format
            `(x_min, y_min, x_max, y_max)`.
        px (int): The padding value to be added to both the left and right sides of
            each bounding box.
        py (Optional[int]): The padding value to be added to both the top and bottom
            sides of each bounding box. If not provided, `px` will be used for both
            dimensions.

    Returns:
        np.ndarray: A numpy array of shape `(N, 4)` where each row corresponds to a
            bounding box with coordinates padded according to the provided padding
            values.

    Examples:
        ```python
        import numpy as np
        import supervision as sv

        xyxy = np.array([
            [10, 20, 30, 40],
            [15, 25, 35, 45]
        ])

        sv.pad_boxes(xyxy=xyxy, px=5, py=10)
        # array([
        #     [ 5, 10, 35, 50],
        #     [10, 15, 40, 55]
        # ])
        ```
    """
    if py is None:
        py = px

    result = xyxy.copy()
    result[:, [0, 1]] -= [px, py]
    result[:, [2, 3]] += [px, py]

    return result

denormalize_boxes

supervision.detection.utils.boxes.denormalize_boxes(normalized_xyxy, resolution_wh, normalization_factor=1.0)

Converts normalized bounding box coordinates to absolute pixel values.

Parameters:

Name Type Description Default

normalized_xyxy

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.

 required

resolution_wh

Tuple[int, int]

A tuple (width, height) representing the target image resolution.

 required

normalization_factor

float

The normalization range of the input coordinates. Defaults to 1.0.

 1.0

Returns:

Type Description
ndarray

np.ndarray: An array of shape (N, 4) with absolute coordinates in (x_min, y_min, x_max, y_max) format.

Examples:

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]
])
resolution_wh = (100, 200)
sv.denormalize_boxes(normalized_xyxy, resolution_wh)
# 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.]
# ])
Source code in supervision/detection/utils/boxes.py 
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
def denormalize_boxes(
    normalized_xyxy: np.ndarray,
    resolution_wh: tuple[int, int],
    normalization_factor: float = 1.0,
) -> np.ndarray:
    """
    Converts normalized bounding box coordinates to absolute pixel values.

    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.

    Returns:
        np.ndarray: An array of shape `(N, 4)` with absolute coordinates in
            `(x_min, y_min, x_max, y_max)` format.

    Examples:
        ```python
        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]
        ])
        resolution_wh = (100, 200)
        sv.denormalize_boxes(normalized_xyxy, resolution_wh)
        # 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.]
        # ])
        ```
    """  # noqa E501 // docs
    width, height = resolution_wh
    result = normalized_xyxy.copy()

    result[[0, 2]] = (result[[0, 2]] * width) / normalization_factor
    result[[1, 3]] = (result[[1, 3]] * height) / normalization_factor

    return result

Comments