feat: Detections.from_inference supports compressed RLE masks

docs/changelog.md

@@ -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>

docs/detection/utils/converters.md

@@ -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

mkdocs.yml

@@ -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

src/supervision/__init__.py

@@ -44,7 +44,6 @@
     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.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,

src/supervision/dataset/formats/coco.py

@@ -2,19 +2,21 @@
 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
 
 from supervision.dataset.utils import (
     approximate_mask_with_polygons,
     map_detections_class_id,
+)
+from supervision.detection.core import Detections
+from supervision.detection.utils.converters import (
     mask_to_rle,
+    polygon_to_mask,
     rle_to_mask,
 )
-from supervision.detection.core import Detections
-from supervision.detection.utils.converters import polygon_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:

src/supervision/dataset/utils.py

@@ -5,19 +5,44 @@
 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)