Skip to content

Feature/xyxy to mask #2006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 5, 2025
Merged

Feature/xyxy to mask #2006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
32dca29
`xyxy_to_mask` implementation + tests
SkalskiP Nov 5, 2025
a3ea8cd
bump version from `0.27.0rc1` to `0.27.0rc2`
SkalskiP Nov 5, 2025
3e7e4ca
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Nov 5, 2025
1c83989
docs and examples
SkalskiP Nov 5, 2025
89ee57f
fix(pre_commit): 🎨 auto format pre-commit hooks
pre-commit-ci[bot] Nov 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/detection/utils/converters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,9 @@ status: new
</div>

:::supervision.detection.utils.converters.polygon_to_xyxy

<div class="md-typeset">
<h2><a href="#supervision.detection.utils.converters.xyxy_to_mask">xyxy_to_mask</a></h2>
</div>

:::supervision.detection.utils.converters.xyxy_to_mask
2 changes: 1 addition & 1 deletion pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
name = "supervision"
description = "A set of easy-to-use utils that will come in handy in any Computer Vision project"
license = { text = "MIT" }
version = "0.27.0rc1"
version = "0.27.0rc2"
readme = "README.md"
requires-python = ">=3.9"
authors = [
Expand Down
2 changes: 2 additions & 0 deletions supervision/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@
polygon_to_xyxy,
xcycwh_to_xyxy,
xywh_to_xyxy,
xyxy_to_mask,
xyxy_to_polygons,
xyxy_to_xcycarh,
xyxy_to_xywh,
Expand Down Expand Up @@ -249,6 +250,7 @@
"tint_image",
"xcycwh_to_xyxy",
"xywh_to_xyxy",
"xyxy_to_mask",
"xyxy_to_polygons",
"xyxy_to_xcycarh",
"xyxy_to_xywh",
Expand Down
64 changes: 64 additions & 0 deletions supervision/detection/utils/converters.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,6 +229,70 @@ def mask_to_xyxy(masks: np.ndarray) -> np.ndarray:
return xyxy


def xyxy_to_mask(boxes: np.ndarray, resolution_wh: tuple[int, int]) -> np.ndarray:
"""
Converts a 2D `np.ndarray` of bounding boxes into a 3D `np.ndarray` of bool masks.

Parameters:
boxes (np.ndarray): A 2D `np.ndarray` of shape `(N, 4)`
containing bounding boxes `(x_min, y_min, x_max, y_max)`
resolution_wh (Tuple[int, int]): A tuple `(width, height)` specifying
the resolution of the output masks

Returns:
np.ndarray: A 3D `np.ndarray` of shape `(N, height, width)`
containing 2D bool masks for each bounding box

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

boxes = np.array([[0, 0, 2, 2]])

sv.xyxy_to_mask(boxes, (5, 5))
# array([
# [[ True, True, True, False, False],
# [ True, True, True, False, False],
# [ True, True, True, False, False],
# [False, False, False, False, False],
# [False, False, False, False, False]]
# ])

boxes = np.array([[0, 0, 1, 1], [3, 3, 4, 4]])

sv.xyxy_to_mask(boxes, (5, 5))
# array([
# [[ True, True, False, False, False],
# [ True, True, False, False, False],
# [False, False, False, False, False],
# [False, False, False, False, False],
# [False, False, False, False, False]],
#
# [[False, False, False, False, False],
# [False, False, False, False, False],
# [False, False, False, False, False],
# [False, False, False, True, True],
# [False, False, False, True, True]]
# ])
```
"""
width, height = resolution_wh
n = boxes.shape[0]
masks = np.zeros((n, height, width), dtype=bool)

for i, (x_min, y_min, x_max, y_max) in enumerate(boxes):
x_min = max(0, int(x_min))
y_min = max(0, int(y_min))
x_max = min(width - 1, int(x_max))
y_max = min(height - 1, int(y_max))

if x_max >= x_min and y_max >= y_min:
masks[i, y_min : y_max + 1, x_min : x_max + 1] = True

return masks


def mask_to_polygons(mask: np.ndarray) -> list[np.ndarray]:
"""
Converts a binary mask to a list of polygons.
Expand Down
172 changes: 172 additions & 0 deletions test/detection/utils/test_converters.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
from supervision.detection.utils.converters import (
xcycwh_to_xyxy,
xywh_to_xyxy,
xyxy_to_mask,
xyxy_to_xcycarh,
xyxy_to_xywh,
)
Expand Down Expand Up @@ -129,3 +130,174 @@ def test_xyxy_to_xcycarh(xyxy: np.ndarray, expected_result: np.ndarray) -> None:
def test_xcycwh_to_xyxy(xcycwh: np.ndarray, expected_result: np.ndarray) -> None:
result = xcycwh_to_xyxy(xcycwh)
np.testing.assert_array_equal(result, expected_result)


@pytest.mark.parametrize(
"boxes,resolution_wh,expected",
[
# 0) Empty input
(
np.array([], dtype=float).reshape(0, 4),
(5, 4),
np.array([], dtype=bool).reshape(0, 4, 5),
),
# 1) Single pixel box
(
np.array([[2, 1, 2, 1]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, False, False],
[False, False, True, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 2) Horizontal line, inclusive bounds
(
np.array([[1, 2, 3, 2]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, False, False],
[False, False, False, False, False],
[False, True, True, True, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 3) Vertical line, inclusive bounds
(
np.array([[3, 0, 3, 2]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, True, False],
[False, False, False, True, False],
[False, False, False, True, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 4) Proper rectangle fill
(
np.array([[1, 1, 3, 2]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, False, False],
[False, True, True, True, False],
[False, True, True, True, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 5) Negative coordinates clipped to [0, 0]
(
np.array([[-2, -1, 1, 1]], dtype=float),
(5, 4),
np.array(
[
[
[True, True, False, False, False],
[True, True, False, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 6) Overflow coordinates clipped to width-1 and height-1
(
np.array([[3, 2, 10, 10]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, False, False],
[False, False, False, False, False],
[False, False, False, True, True],
[False, False, False, True, True],
]
],
dtype=bool,
),
),
# 7) Invalid box where max < min after ints, mask stays empty
(
np.array([[3, 2, 1, 4]], dtype=float),
(5, 4),
np.array(
[
[
[False, False, False, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 8) Fractional coordinates are floored by int conversion
# (0.2,0.2)-(2.8,1.9) -> (0,0)-(2,1)
(
np.array([[0.2, 0.2, 2.8, 1.9]], dtype=float),
(5, 4),
np.array(
[
[
[True, True, True, False, False],
[True, True, True, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
]
],
dtype=bool,
),
),
# 9) Multiple boxes, separate masks
(
np.array([[0, 0, 1, 0], [2, 1, 4, 3]], dtype=float),
(5, 4),
np.array(
[
# Box 0: row 0, cols 0..1
[
[True, True, False, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
[False, False, False, False, False],
],
# Box 1: rows 1..3, cols 2..4
[
[False, False, False, False, False],
[False, False, True, True, True],
[False, False, True, True, True],
[False, False, True, True, True],
],
],
dtype=bool,
),
),
],
)
def test_xyxy_to_mask(boxes: np.ndarray, resolution_wh, expected: np.ndarray) -> None:
result = xyxy_to_mask(boxes, resolution_wh)
assert result.dtype == np.bool_
assert result.shape == expected.shape
np.testing.assert_array_equal(result, expected)