feat: Detections.from_inference supports compressed RLE masks (#2178)

* Detections.from_inference works on RLE-encoded masks
* Apply suggestions from code review
* fix: harden RLE handling in from_inference and decoder
* lint: fix cv2.fillPoly color type in polygon_to_mask
* fix: resize RLE mask to image dims when size mismatches
* fix: pass RLE counts directly in coco_annotations_to_masks
* test: document mixed RLE + box-only batch misalignment
* test: add compressed RLE iscrowd case to coco_annotations_to_detections
* fix: cast polygon mask to bool in process_roboflow_result
* fix: log warning when RLE decode fails in process_roboflow_result
* fix: replace assert with ValueError in rle_to_mask
* test: add bytes invalid UTF-8 case to rle_to_mask tests
* docs: note rle_to_mask dtype change from uint8 to bool in changelog
* refactor: tighten rle_to_mask NDArray input type to np.integer[Any]
* refactor: drop mask_to_rle overloads; cast at call site
* docs: clarify COCO column-major RLE order in rle_to_mask/mask_to_rle
* refactor: update @deprecated annotations and docstrings for mask_to_rle/rle_to_mask; add pydeprecate dependency
* refactor: replace mask_to_rle body with `void` function to suppress unused argument warnings

---------

Co-authored-by: Jirka Borovec <6035284+Borda@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
This commit is contained in:
Lee Clement
2026-04-15 22:35:47 +02:00
committed by GitHub
co-authored by Jirka Borovec Copilot Claude Sonnet 4.6 pre-commit-ci[bot]
parent f28874c0c2
commit 62efdee025
13 changed files with 824 additions and 295 deletions
+6
View File
@@ -2,6 +2,12 @@
### 0.28.0 <small>Unreleased</small>
- Changed [#2178](https://github.com/roboflow/supervision/pull/2178): [`sv.Detections.from_inference`](https://supervision.roboflow.com/latest/detection/core/#supervision.detection.core.Detections.from_inference) now supports compressed COCO RLE masks. Inference responses with `rle` or `rle_mask` fields containing a compressed counts string (as produced by `pycocotools`) are decoded directly into binary masks, avoiding a lossy polygon round-trip.
- Changed [#2178](https://github.com/roboflow/supervision/pull/2178): [`sv.rle_to_mask`](https://supervision.roboflow.com/latest/detection/utils/converters/#supervision.detection.utils.converters.rle_to_mask) and [`sv.mask_to_rle`](https://supervision.roboflow.com/latest/detection/utils/converters/#supervision.detection.utils.converters.mask_to_rle) moved to `supervision.detection.utils.converters`. The old import path `supervision.dataset.utils` continues to work but is deprecated.
- Fixed [#2178](https://github.com/roboflow/supervision/pull/2178): [`sv.rle_to_mask`](https://supervision.roboflow.com/latest/detection/utils/converters/#supervision.detection.utils.converters.rle_to_mask) now returns `NDArray[bool]` as declared in its signature. Previously the implementation returned `uint8` despite the `bool` annotation; code that relied on the undocumented `uint8` output (e.g. `mask * 255` producing `uint8`) should wrap the result with `.astype(np.uint8)`.
- Fixed [#2210](https://github.com/roboflow/supervision/pull/2210): [`sv.VideoInfo.fps`](https://supervision.roboflow.com/latest/utils/video/#supervision.utils.video.VideoInfo) now returns a `float` instead of a truncated `int`. Previously, frame rates like 23.976, 29.97, and 59.94 were silently truncated, causing frame-timing drift that accumulates over long videos. The type of `VideoInfo.fps` has changed from `int` to `float`; callers that pass `fps` to APIs requiring an integer (such as `deque(maxlen=...)` or `TraceAnnotator(trace_length=...)`) should wrap the value with `int()`.
### 0.27.0 <small>Nov 16, 2025</small>
-17
View File
@@ -1,17 +0,0 @@
---
comments: true
---
# Datasets Utils
<div class="md-typeset">
<h2><a href="#supervision.dataset.utils.rle_to_mask">rle_to_mask</a></h2>
</div>
:::supervision.dataset.utils.rle_to_mask
<div class="md-typeset">
<h2><a href="#supervision.dataset.utils.mask_to_rle">mask_to_rle</a></h2>
</div>
:::supervision.dataset.utils.mask_to_rle
+12
View File
@@ -64,3 +64,15 @@ status: new
</div>
:::supervision.detection.utils.converters.xyxy_to_mask
<div class="md-typeset">
<h2><a href="#supervision.detection.utils.converters.rle_to_mask">rle_to_mask</a></h2>
</div>
:::supervision.detection.utils.converters.rle_to_mask
<div class="md-typeset">
<h2><a href="#supervision.detection.utils.converters.mask_to_rle">mask_to_rle</a></h2>
</div>
:::supervision.detection.utils.converters.mask_to_rle
-1
View File
@@ -63,7 +63,6 @@ nav:
- Trackers: trackers.md
- Datasets:
- Core: datasets/core.md
- Utils: datasets/utils.md
- Metrics:
- mAP: metrics/mean_average_precision.md
- mAR: metrics/mean_average_recall.md
+2 -1
View File
@@ -44,7 +44,6 @@ from supervision.dataset.core import (
DetectionDataset,
)
from supervision.dataset.formats.coco import get_coco_class_index_mapping
from supervision.dataset.utils import mask_to_rle, rle_to_mask
from supervision.detection.compact_mask import CompactMask
from supervision.detection.core import Detections
from supervision.detection.line_zone import (
@@ -66,9 +65,11 @@ from supervision.detection.utils.boxes import (
)
from supervision.detection.utils.converters import (
mask_to_polygons,
mask_to_rle,
mask_to_xyxy,
polygon_to_mask,
polygon_to_xyxy,
rle_to_mask,
xcycwh_to_xyxy,
xywh_to_xyxy,
xyxy_to_mask,
+8 -8
View File
@@ -2,7 +2,7 @@ import os
import warnings
from datetime import datetime
from pathlib import Path
from typing import TYPE_CHECKING, Any, Union
from typing import TYPE_CHECKING, Any, Union, cast
import numpy as np
import numpy.typing as npt
@@ -10,11 +10,13 @@ import numpy.typing as npt
from supervision.dataset.utils import (
approximate_mask_with_polygons,
map_detections_class_id,
mask_to_rle,
rle_to_mask,
)
from supervision.detection.core import Detections
from supervision.detection.utils.converters import polygon_to_mask
from supervision.detection.utils.converters import (
mask_to_rle,
polygon_to_mask,
rle_to_mask,
)
from supervision.detection.utils.masks import contains_holes, contains_multiple_segments
from supervision.utils.file import read_json_file, save_json_file
@@ -83,9 +85,7 @@ def coco_annotations_to_masks(
if image_annotation.get("iscrowd", 0):
masks.append(
rle_to_mask(
rle=np.array(segmentation["counts"]), resolution_wh=resolution_wh
).astype(bool)
rle_to_mask(rle=segmentation["counts"], resolution_wh=resolution_wh)
)
continue
@@ -179,7 +179,7 @@ def detections_to_coco_annotations(
if iscrowd:
segmentation = {
"counts": mask_to_rle(mask=mask),
"counts": cast(list[int], mask_to_rle(mask=mask, compressed=False)),
"size": list(mask.shape[:2]),
}
else:
+26 -129
View File
@@ -5,19 +5,44 @@ import os
import random
import shutil
from pathlib import Path
from typing import TYPE_CHECKING, TypeVar
from typing import TYPE_CHECKING, Any, TypeVar
import cv2
import numpy as np
import numpy.typing as npt
from deprecate import deprecated, void
from supervision.detection.core import Detections
from supervision.detection.utils.converters import mask_to_polygons
from supervision.detection.utils.converters import (
mask_to_rle as _mask_to_rle,
)
from supervision.detection.utils.converters import (
rle_to_mask as _rle_to_mask,
)
from supervision.detection.utils.polygons import (
approximate_polygon,
filter_polygons_by_area,
)
@deprecated(target=_mask_to_rle, deprecated_in="0.28.0", remove_in="0.30.0") # type: ignore[untyped-decorator]
def mask_to_rle(
mask: npt.NDArray[np.bool_], compressed: bool = False
) -> list[int] | str:
"""Deprecated. Use `supervision.detection.utils.converters.mask_to_rle`."""
return void(mask, compressed) # type: ignore[no-any-return]
@deprecated(target=_rle_to_mask, deprecated_in="0.28.0", remove_in="0.30.0") # type: ignore[untyped-decorator]
def rle_to_mask(
rle: npt.NDArray[np.integer[Any]] | list[int] | str | bytes,
resolution_wh: tuple[int, int],
) -> npt.NDArray[np.bool_]:
"""Deprecated. Use `supervision.detection.utils.converters.rle_to_mask`."""
return void(rle, resolution_wh)
if TYPE_CHECKING:
from supervision.dataset.core import DetectionDataset
@@ -137,131 +162,3 @@ def train_test_split(
split_index = int(len(data) * train_ratio)
return data[:split_index], data[split_index:]
def rle_to_mask(
rle: npt.NDArray[np.int_] | list[int], resolution_wh: tuple[int, int]
) -> npt.NDArray[np.bool_]:
"""
Converts run-length encoding (RLE) to a binary mask.
Args:
rle: The 1D RLE array, the format
used in the COCO dataset (column-wise encoding, values of an array with
even indices represent the number of pixels assigned as background,
values of an array with odd indices represent the number of pixels
assigned as foreground object).
resolution_wh: The width (w) and height (h)
of the desired binary mask.
Returns:
The generated 2D Boolean mask of shape `(h, w)`, where the foreground object is
marked with `True`'s and the rest is filled with `False`'s.
Raises:
AssertionError: If the sum of pixels encoded in RLE differs from the
number of pixels in the expected mask (computed based on resolution_wh).
Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = sv.rle_to_mask([5, 2, 2, 2, 5], (4, 4))
>>> mask # doctest: +NORMALIZE_WHITESPACE
array([[0, 0, 0, 0],
[0, 1, 1, 0],
[0, 1, 1, 0],
[0, 0, 0, 0]], dtype=uint8)
```
"""
if isinstance(rle, list):
rle = np.array(rle, dtype=int)
width, height = resolution_wh
assert width * height == np.sum(rle), (
"the sum of the number of pixels in the RLE must be the same "
"as the number of pixels in the expected mask"
)
zero_one_values = np.zeros(shape=(rle.size, 1), dtype=np.uint8)
zero_one_values[1::2] = 1
decoded_rle = np.repeat(zero_one_values, rle, axis=0)
decoded_rle = np.append(
decoded_rle, np.zeros(width * height - len(decoded_rle), dtype=np.uint8)
)
return decoded_rle.reshape((height, width), order="F")
def mask_to_rle(mask: npt.NDArray[np.bool_]) -> list[int]:
"""
Converts a binary mask into a run-length encoding (RLE).
Args:
mask: 2D binary mask where `True` indicates foreground
object and `False` indicates background.
Returns:
The run-length encoded mask. Values of a list with even indices
represent the number of pixels assigned as background (`False`), values
of a list with odd indices represent the number of pixels assigned
as foreground object (`True`).
Raises:
AssertionError: If input mask is not 2D or is empty.
Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = np.array([
... [True, True, True, True],
... [True, True, True, True],
... [True, True, True, True],
... [True, True, True, True],
... ])
>>> rle = sv.mask_to_rle(mask)
>>> [int(x) for x in rle]
[0, 16]
```
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = np.array([
... [False, False, False, False],
... [False, True, True, False],
... [False, True, True, False],
... [False, False, False, False],
... ])
>>> rle = sv.mask_to_rle(mask)
>>> [int(x) for x in rle]
[5, 2, 2, 2, 5]
```
![mask_to_rle](https://media.roboflow.com/supervision-docs/
mask-to-rle.png){ align=center width="800" }
"""
assert mask.ndim == 2, "Input mask must be 2D"
assert mask.size != 0, "Input mask cannot be empty"
on_value_change_indices = np.where(
mask.ravel(order="F") != np.roll(mask.ravel(order="F"), 1)
)[0]
on_value_change_indices = np.append(on_value_change_indices, mask.size)
# need to add 0 at the beginning when the same value is in the first and
# last element of the flattened mask
if on_value_change_indices[0] != 0:
on_value_change_indices = np.insert(on_value_change_indices, 0, 0)
rle = np.diff(on_value_change_indices)
if mask[0][0] == 1:
rle = np.insert(rle, 0, 0)
return list(rle)
+237 -1
View File
@@ -1,3 +1,7 @@
from __future__ import annotations
from typing import Any
import cv2
import numpy as np
import numpy.typing as npt
@@ -41,7 +45,7 @@ def polygon_to_mask(
"""
width, height = map(int, resolution_wh)
mask = np.zeros((height, width), dtype=np.uint8)
cv2.fillPoly(mask, [polygon.astype(np.int32)], color=1)
cv2.fillPoly(mask, [polygon.astype(np.int32)], color=(1,))
return mask
@@ -304,6 +308,238 @@ def mask_to_polygons(mask: npt.NDArray[np.bool_]) -> list[npt.NDArray[np.int32]]
]
def _decode_coco_rle_string(s: str) -> list[int]:
"""Decode a COCO compressed RLE counts string to a list of run-length integers.
Implements the decoding algorithm from the COCO API (pycocotools) for
compressed RLE strings. Each character encodes 5 data bits in a base-48
scheme with continuation and sign flags, using delta encoding for indices
beyond the first two.
Args:
s: The compressed RLE counts string.
Returns:
A list of run-length integers (alternating background/foreground counts).
"""
counts: list[int] = []
i = 0
while i < len(s):
x = 0
k = 0
more = True
while more:
if i >= len(s):
raise ValueError(
f"Malformed compressed RLE string: unexpected end at position {i}"
)
c = ord(s[i]) - 48
x |= (c & 0x1F) << (5 * k)
more = bool(c & 0x20)
i += 1
k += 1
if not more and (c & 0x10):
x |= ~0 << (5 * k)
if len(counts) > 2:
x += counts[-2]
counts.append(x)
return counts
def _encode_coco_rle_string(counts: list[int]) -> str:
"""Encode a list of run-length integers to a COCO compressed RLE string.
Implements the encoding algorithm from the COCO API (pycocotools).
The inverse of :func:`_decode_coco_rle_string`.
Args:
counts: A list of run-length integers (alternating background/foreground
counts).
Returns:
The compressed RLE counts string.
"""
chars: list[str] = []
for i, cnt in enumerate(counts):
x = cnt - counts[i - 2] if i > 2 else cnt
more = True
while more:
c = x & 0x1F
x >>= 5
more = (x != -1) if (c & 0x10) else (x != 0)
if more:
c |= 0x20
chars.append(chr(c + 48))
return "".join(chars)
def rle_to_mask(
rle: npt.NDArray[np.integer[Any]] | list[int] | str | bytes,
resolution_wh: tuple[int, int],
) -> npt.NDArray[np.bool_]:
"""
Converts a COCO run-length encoding (RLE) to a binary mask.
Implements the COCO RLE format used by ``pycocotools``: pixels are counted
in **column-major (Fortran) order** — top-to-bottom within each column,
left-to-right across columns. This is the opposite of the row-major order
used by NumPy's default ``'C'`` layout. Passing RLE data produced by a
different row-major convention will yield an incorrect mask.
Args:
rle: The COCO RLE data in one of the following formats:
- A 1D array or list of integers (uncompressed COCO RLE, where
values at even indices are background run-lengths and values at
odd indices are foreground run-lengths, both counted column-major).
- A compressed COCO RLE string or bytes, as produced by
``pycocotools.mask.encode``.
resolution_wh: The width (w) and height (h)
of the desired binary mask.
Returns:
The generated 2D Boolean mask of shape `(h, w)`, where the foreground object is
marked with `True`'s and the rest is filled with `False`'s.
Raises:
ValueError: If the sum of pixels encoded in RLE differs from the
number of pixels in the expected mask (computed based on resolution_wh).
Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = sv.rle_to_mask([5, 2, 2, 2, 5], (4, 4))
>>> mask # doctest: +NORMALIZE_WHITESPACE
array([[False, False, False, False],
[False, True, True, False],
[False, True, True, False],
[False, False, False, False]])
>>> mask = sv.rle_to_mask("52203", (4, 4))
>>> mask # doctest: +NORMALIZE_WHITESPACE
array([[False, False, False, False],
[False, True, True, False],
[False, True, True, False],
[False, False, False, False]])
```
"""
if isinstance(rle, bytes):
rle = rle.decode("utf-8")
if isinstance(rle, str):
rle = np.array(_decode_coco_rle_string(rle), dtype=int)
elif isinstance(rle, list):
rle = np.array(rle, dtype=int)
width, height = resolution_wh
if width * height != np.sum(rle):
raise ValueError(
"the sum of the number of pixels in the RLE must be the same "
"as the number of pixels in the expected mask"
)
zero_one_values = np.zeros(shape=(rle.size, 1), dtype=np.uint8)
zero_one_values[1::2] = 1
decoded_rle = np.repeat(zero_one_values, rle, axis=0)
decoded_rle = np.append(
decoded_rle, np.zeros(width * height - len(decoded_rle), dtype=np.uint8)
)
return decoded_rle.reshape((height, width), order="F").astype(bool)
def mask_to_rle(
mask: npt.NDArray[np.bool_], compressed: bool = False
) -> list[int] | str:
"""
Converts a binary mask into a COCO run-length encoding (RLE).
Produces RLE in the COCO format used by ``pycocotools``: pixels are counted
in **column-major (Fortran) order** — top-to-bottom within each column,
left-to-right across columns. The output is directly compatible with
``pycocotools.mask.decode`` and COCO annotation JSON files.
Args:
mask: 2D binary mask where `True` indicates foreground
object and `False` indicates background.
compressed: If ``True``, return a compressed COCO RLE string
compatible with ``pycocotools``. If ``False`` (default),
return a list of integers.
Returns:
The COCO run-length encoded mask. When ``compressed`` is ``False``,
values of a list with even indices represent the number of pixels
assigned as background (`False`), values of a list with odd indices
represent the number of pixels assigned as foreground object (`True`),
both counted in column-major order.
When ``compressed`` is ``True``, a COCO compressed RLE string.
Raises:
AssertionError: If input mask is not 2D or is empty.
Examples:
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = np.array([
... [True, True, True, True],
... [True, True, True, True],
... [True, True, True, True],
... [True, True, True, True],
... ])
>>> rle = sv.mask_to_rle(mask)
>>> [int(x) for x in rle]
[0, 16]
```
```pycon
>>> import numpy as np
>>> import supervision as sv
>>> mask = np.array([
... [False, False, False, False],
... [False, True, True, False],
... [False, True, True, False],
... [False, False, False, False],
... ])
>>> rle = sv.mask_to_rle(mask)
>>> [int(x) for x in rle]
[5, 2, 2, 2, 5]
>>> sv.mask_to_rle(mask, compressed=True)
'52203'
```
![mask_to_rle](https://media.roboflow.com/supervision-docs/
mask-to-rle.png){ align=center width="800" }
"""
assert mask.ndim == 2, "Input mask must be 2D"
assert mask.size != 0, "Input mask cannot be empty"
on_value_change_indices = np.where(
mask.ravel(order="F") != np.roll(mask.ravel(order="F"), 1)
)[0]
on_value_change_indices = np.append(on_value_change_indices, mask.size)
# need to add 0 at the beginning when the same value is in the first and
# last element of the flattened mask
if on_value_change_indices[0] != 0:
on_value_change_indices = np.insert(on_value_change_indices, 0, 0)
rle = np.diff(on_value_change_indices)
if mask[0][0] == 1:
rle = np.insert(rle, 0, 0)
counts = [int(count) for count in rle]
if compressed:
return _encode_coco_rle_string(counts)
return counts
def polygon_to_xyxy(polygon: npt.NDArray[np.number]) -> npt.NDArray[np.number]:
"""
Converts a polygon represented by a NumPy array into a bounding box.
+38 -4
View File
@@ -1,5 +1,6 @@
from __future__ import annotations
import logging
from itertools import chain
from typing import Any, cast
@@ -8,9 +9,11 @@ import numpy as np
import numpy.typing as npt
from supervision.config import CLASS_NAME_DATA_FIELD
from supervision.detection.utils.converters import polygon_to_mask
from supervision.detection.utils.converters import polygon_to_mask, rle_to_mask
from supervision.geometry.core import Vector
logger = logging.getLogger(__name__)
def extract_ultralytics_masks(yolov8_results: Any) -> npt.NDArray[np.bool_] | None:
if not yolov8_results.masks:
@@ -72,7 +75,7 @@ def process_roboflow_result(
confidence: list[float] = []
class_id: list[int] = []
class_name: list[str] = []
masks: list[npt.NDArray[np.uint8]] = []
masks: list[npt.NDArray[np.bool_]] = []
tracker_ids: list[int] = []
image_width = int(roboflow_result["image"]["width"])
@@ -88,7 +91,38 @@ def process_roboflow_result(
x_max = x_min + width
y_max = y_min + height
if "points" not in prediction:
rle_data = prediction.get("rle") or prediction.get("rle_mask")
if not isinstance(rle_data, dict) or not {
"size",
"counts",
}.issubset(rle_data):
rle_data = None
if rle_data is not None:
try:
h, w = rle_data["size"]
mask = rle_to_mask(rle_data["counts"], (w, h))
if (h, w) != (image_height, image_width):
mask = cv2.resize(
mask.astype(np.uint8),
(image_width, image_height),
interpolation=cv2.INTER_NEAREST,
).astype(bool)
except (ValueError, AssertionError, KeyError, TypeError) as exc:
logger.warning(
"Failed to decode RLE mask payload; falling back to box-only "
"detection. Reason: %s",
exc,
)
rle_data = None
if rle_data is not None:
xyxy.append([x_min, y_min, x_max, y_max])
class_id.append(prediction["class_id"])
class_name.append(prediction["class"])
confidence.append(prediction["confidence"])
masks.append(mask)
if "tracker_id" in prediction:
tracker_ids.append(prediction["tracker_id"])
elif "points" not in prediction:
xyxy.append([x_min, y_min, x_max, y_max])
class_id.append(prediction["class_id"])
class_name.append(prediction["class"])
@@ -104,7 +138,7 @@ def process_roboflow_result(
class_id.append(prediction["class_id"])
class_name.append(prediction["class"])
confidence.append(prediction["confidence"])
masks.append(mask)
masks.append(mask.astype(bool))
if "tracker_id" in prediction:
tracker_ids.append(prediction["tracker_id"])
+33
View File
@@ -706,6 +706,39 @@ def test_group_coco_annotations_by_image_id(
DoesNotRaise(),
), # two image annotations with mask, first mask as RLE with is crowd,
# and second as polygon without iscrowd
(
[
mock_coco_annotation(
category_id=0,
bbox=(0, 0, 4, 4),
area=4 * 4,
segmentation={
"size": [4, 4],
"counts": "52203",
},
iscrowd=True,
)
],
(4, 4),
True,
False,
Detections(
xyxy=np.array([[0, 0, 4, 4]], dtype=np.float32),
class_id=np.array([0], dtype=int),
mask=np.array(
[
[
[False, False, False, False],
[False, True, True, False],
[False, True, True, False],
[False, False, False, False],
]
],
dtype=bool,
),
),
DoesNotRaise(),
), # single iscrowd annotation with compressed COCO RLE string counts
],
)
def test_coco_annotations_to_detections(
-134
View File
@@ -3,17 +3,13 @@ from __future__ import annotations
from contextlib import ExitStack as DoesNotRaise
from typing import TypeVar
import numpy as np
import numpy.typing as npt
import pytest
from supervision import Detections
from supervision.dataset.utils import (
build_class_index_mapping,
map_detections_class_id,
mask_to_rle,
merge_class_lists,
rle_to_mask,
train_test_split,
)
from tests.helpers import _create_detections
@@ -235,133 +231,3 @@ def test_map_detections_class_id(
source_to_target_mapping=source_to_target_mapping, detections=detections
)
assert result == expected_result
@pytest.mark.parametrize(
("mask", "expected_rle", "exception"),
[
(
np.zeros((3, 3)).astype(bool),
[9],
DoesNotRaise(),
), # mask with background only (mask with only False values)
(
np.ones((3, 3)).astype(bool),
[0, 9],
DoesNotRaise(),
), # mask with foreground only (mask with only True values)
(
np.array(
[
[0, 0, 0, 0, 0],
[0, 1, 1, 1, 0],
[0, 1, 0, 1, 0],
[0, 1, 1, 1, 0],
[0, 0, 0, 0, 0],
]
).astype(bool),
[6, 3, 2, 1, 1, 1, 2, 3, 6],
DoesNotRaise(),
), # mask where foreground object has hole
(
np.array(
[
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
]
).astype(bool),
[0, 5, 5, 5, 5, 5],
DoesNotRaise(),
), # mask where foreground consists of 3 separate components
(
np.array([[[]]]).astype(bool),
None,
pytest.raises(AssertionError, match="Input mask must be 2D"),
), # raises AssertionError because mask dimensionality is not 2D
(
np.array([[]]).astype(bool),
None,
pytest.raises(AssertionError, match="Input mask cannot be empty"),
), # raises AssertionError because mask is empty
],
)
def test_mask_to_rle(
mask: npt.NDArray[np.bool_], expected_rle: list[int], exception: Exception
) -> None:
with exception:
result = mask_to_rle(mask=mask)
assert result == expected_rle
@pytest.mark.parametrize(
("rle", "resolution_wh", "expected_mask", "exception"),
[
(
np.array([9]),
[3, 3],
np.zeros((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with background only (mask with only False values); rle as array
(
[9],
[3, 3],
np.zeros((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with background only (mask with only False values); rle as list
(
np.array([0, 9]),
[3, 3],
np.ones((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with foreground only (mask with only True values)
(
np.array([6, 3, 2, 1, 1, 1, 2, 3, 6]),
[5, 5],
np.array(
[
[0, 0, 0, 0, 0],
[0, 1, 1, 1, 0],
[0, 1, 0, 1, 0],
[0, 1, 1, 1, 0],
[0, 0, 0, 0, 0],
]
).astype(bool),
DoesNotRaise(),
), # mask where foreground object has hole
(
np.array([0, 5, 5, 5, 5, 5]),
[5, 5],
np.array(
[
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
]
).astype(bool),
DoesNotRaise(),
), # mask where foreground consists of 3 separate components
(
np.array([0, 5, 5, 5, 5, 5]),
[2, 2],
None,
pytest.raises(
AssertionError, match="sum of the number of pixels in the RLE"
),
), # raises AssertionError because number of pixels in RLE does not match
# number of pixels in expected mask (width x height).
],
)
def test_rle_to_mask(
rle: npt.NDArray[np.int_],
resolution_wh: tuple[int, int],
expected_mask: npt.NDArray[np.bool_],
exception: Exception,
) -> None:
with exception:
result = rle_to_mask(rle=rle, resolution_wh=resolution_wh)
assert np.all(result == expected_mask)
+232
View File
@@ -1,9 +1,16 @@
from __future__ import annotations
from contextlib import ExitStack as DoesNotRaise
import numpy as np
import numpy.typing as npt
import pytest
from supervision.detection.utils.converters import (
_decode_coco_rle_string,
_encode_coco_rle_string,
mask_to_rle,
rle_to_mask,
xcycwh_to_xyxy,
xywh_to_xyxy,
xyxy_to_mask,
@@ -301,3 +308,228 @@ def test_xyxy_to_mask(boxes: np.ndarray, resolution_wh, expected: np.ndarray) ->
assert result.dtype == np.bool_
assert result.shape == expected.shape
np.testing.assert_array_equal(result, expected)
@pytest.mark.parametrize(
"counts",
[
[5, 2, 2, 2, 5],
[0, 16],
[9],
[0, 5, 5, 5, 5, 5],
[6, 3, 2, 1, 1, 1, 2, 3, 6],
[3, 1, 2, 4, 2, 1, 3],
],
)
def test_coco_rle_encode_decode_round_trip(counts: list[int]) -> None:
encoded = _encode_coco_rle_string(counts)
decoded = _decode_coco_rle_string(encoded)
assert decoded == counts
@pytest.mark.parametrize(
("mask", "compressed", "expected_rle", "exception"),
[
(
np.zeros((3, 3)).astype(bool),
False,
[9],
DoesNotRaise(),
), # mask with background only (mask with only False values)
(
np.ones((3, 3)).astype(bool),
False,
[0, 9],
DoesNotRaise(),
), # mask with foreground only (mask with only True values)
(
np.array(
[
[0, 0, 0, 0, 0],
[0, 1, 1, 1, 0],
[0, 1, 0, 1, 0],
[0, 1, 1, 1, 0],
[0, 0, 0, 0, 0],
]
).astype(bool),
False,
[6, 3, 2, 1, 1, 1, 2, 3, 6],
DoesNotRaise(),
), # mask where foreground object has hole
(
np.array(
[
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
]
).astype(bool),
False,
[0, 5, 5, 5, 5, 5],
DoesNotRaise(),
), # mask where foreground consists of 3 separate components
(
np.array(
[
[False, False, False, False],
[False, True, True, False],
[False, True, True, False],
[False, False, False, False],
]
),
True,
"52203",
DoesNotRaise(),
), # compressed RLE string
(
np.array([[[]]]).astype(bool),
False,
None,
pytest.raises(AssertionError, match="Input mask must be 2D"),
), # raises AssertionError because mask dimensionality is not 2D
(
np.array([[]]).astype(bool),
False,
None,
pytest.raises(AssertionError, match="Input mask cannot be empty"),
), # raises AssertionError because mask is empty
],
)
def test_mask_to_rle(
mask: npt.NDArray[np.bool_],
compressed: bool,
expected_rle: list[int] | str | None,
exception: Exception,
) -> None:
with exception:
result = mask_to_rle(mask=mask, compressed=compressed)
assert result == expected_rle
@pytest.mark.parametrize(
("rle", "resolution_wh", "expected_mask", "exception"),
[
(
np.array([9]),
[3, 3],
np.zeros((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with background only (mask with only False values); rle as array
(
[9],
[3, 3],
np.zeros((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with background only (mask with only False values); rle as list
(
np.array([0, 9]),
[3, 3],
np.ones((3, 3)).astype(bool),
DoesNotRaise(),
), # mask with foreground only (mask with only True values)
(
np.array([6, 3, 2, 1, 1, 1, 2, 3, 6]),
[5, 5],
np.array(
[
[0, 0, 0, 0, 0],
[0, 1, 1, 1, 0],
[0, 1, 0, 1, 0],
[0, 1, 1, 1, 0],
[0, 0, 0, 0, 0],
]
).astype(bool),
DoesNotRaise(),
), # mask where foreground object has hole
(
np.array([0, 5, 5, 5, 5, 5]),
[5, 5],
np.array(
[
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
[1, 0, 1, 0, 1],
]
).astype(bool),
DoesNotRaise(),
), # mask where foreground consists of 3 separate components
(
np.array([0, 5, 5, 5, 5, 5]),
[2, 2],
None,
pytest.raises(ValueError, match="sum of the number of pixels in the RLE"),
), # raises ValueError because number of pixels in RLE does not match
# number of pixels in expected mask (width x height).
(
b"3124OM1",
[4, 4],
np.array(
[
[0, 0, 1, 1],
[0, 0, 1, 1],
[0, 1, 1, 0],
[1, 1, 0, 0],
]
).astype(bool),
DoesNotRaise(),
), # compressed RLE bytes
(
"52203",
[4, 4],
np.array(
[
[0, 0, 0, 0],
[0, 1, 1, 0],
[0, 1, 1, 0],
[0, 0, 0, 0],
]
).astype(bool),
DoesNotRaise(),
), # compressed RLE string
(
"!",
[4, 4],
None,
pytest.raises(ValueError, match="Malformed compressed RLE string"),
), # malformed compressed RLE string with invalid character
(
"52P",
[4, 4],
None,
pytest.raises(ValueError, match="Malformed compressed RLE string"),
), # malformed compressed RLE: unterminated continuation byte
(
b"\xff\xfe",
[4, 4],
None,
pytest.raises(UnicodeDecodeError),
), # bytes with invalid UTF-8 sequence raises UnicodeDecodeError
],
)
def test_rle_to_mask(
rle: npt.NDArray[np.int_],
resolution_wh: tuple[int, int],
expected_mask: npt.NDArray[np.bool_],
exception: Exception,
) -> None:
with exception:
result = rle_to_mask(rle=rle, resolution_wh=resolution_wh)
assert np.all(result == expected_mask)
def test_mask_rle_compressed_round_trip() -> None:
mask = np.array(
[
[False, False, False, False],
[False, True, True, False],
[False, True, True, False],
[False, False, False, False],
]
)
compressed = mask_to_rle(mask, compressed=True)
recovered = rle_to_mask(compressed, (4, 4))
np.testing.assert_array_equal(mask, recovered)
+230
View File
@@ -17,6 +17,13 @@ from supervision.detection.utils.internal import (
TEST_MASK = np.zeros((1, 1000, 1000), dtype=bool)
TEST_MASK[:, 300:351, 200:251] = True
TEST_RLE_MASK = np.zeros((1, 4, 4), dtype=bool)
TEST_RLE_MASK[0, 1:3, 1:3] = True
TEST_RLE_NONCONTIGUOUS_MASK = np.zeros((1, 4, 4), dtype=bool)
TEST_RLE_NONCONTIGUOUS_MASK[0, 0:2, 0:2] = True
TEST_RLE_NONCONTIGUOUS_MASK[0, 3, 2:4] = True
@pytest.mark.parametrize(
("roboflow_result", "expected_result", "exception"),
@@ -219,6 +226,229 @@ TEST_MASK[:, 300:351, 200:251] = True
),
DoesNotRaise(),
), # two instance segmentation results - one correct, one incorrect
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": {"size": [4, 4], "counts": "52203"},
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
TEST_RLE_MASK,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # single RLE prediction with compressed string counts
(
{
"predictions": [
{
"x": 2.0,
"y": 2.0,
"width": 4.0,
"height": 4.0,
"confidence": 0.85,
"class_id": 1,
"class": "cat",
"rle": {"size": [4, 4], "counts": "02203ON0"},
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.0, 0.0, 4.0, 4.0]]),
np.array([0.85]),
np.array([1]),
TEST_RLE_NONCONTIGUOUS_MASK,
None,
{CLASS_NAME_DATA_FIELD: np.array(["cat"])},
),
DoesNotRaise(),
), # single RLE prediction with non-contiguous mask
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": {"size": [4, 4], "counts": "52203"},
"tracker_id": 5,
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
TEST_RLE_MASK,
np.array([5]),
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # RLE prediction with tracker_id
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle_mask": {"size": [4, 4], "counts": "52203"},
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
TEST_RLE_MASK,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # single RLE prediction with compressed string counts under rle_mask key
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": "bad_string",
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
None,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # malformed RLE payload should fall through to box-only detection
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": {"size": [4, 4]},
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
None,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # RLE dict missing counts falls through to box-only detection
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": {"size": [4, 4], "counts": "!"},
}
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5]]),
np.array([0.9]),
np.array([0]),
None,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person"])},
),
DoesNotRaise(),
), # malformed compressed counts falls through to box-only detection
(
{
"predictions": [
{
"x": 1.5,
"y": 1.5,
"width": 2.0,
"height": 2.0,
"confidence": 0.9,
"class_id": 0,
"class": "person",
"rle": {"size": [4, 4], "counts": "52203"},
},
{
"x": 3.0,
"y": 3.0,
"width": 2.0,
"height": 2.0,
"confidence": 0.8,
"class_id": 1,
"class": "car",
},
],
"image": {"width": 4, "height": 4},
},
(
np.array([[0.5, 0.5, 2.5, 2.5], [2.0, 2.0, 4.0, 4.0]]),
np.array([0.9, 0.8]),
np.array([0, 1]),
# NOTE: known misalignment — masks has 1 entry, xyxy has 2.
# Mixed RLE + box-only batches produce mask arrays shorter than
# xyxy; constructing Detections from this result would raise
# ValueError. This is a pre-existing limitation shared by the
# polygon + box-only path.
TEST_RLE_MASK,
None,
{CLASS_NAME_DATA_FIELD: np.array(["person", "car"])},
),
DoesNotRaise(),
), # mixed RLE + box-only batch — masks misaligned with xyxy (known limitation)
],
)
def test_process_roboflow_result(