feat: Detections.from_inference supports compressed RLE masks

[leeclemnet]

Before submitting

• Self-reviewed the code
• Updated documentation, follow Google-style
• Added docs entry for autogeneration (if new functions/classes)
• Added/updated tests
• All tests pass locally

Description

Add RLE mask support to sv.Detections.from_inference for models that return compressed COCO RLE (e.g. SAM3, semantic segmentation), and extend rle_to_mask/mask_to_rle with compressed string encoding/decoding — implemented as a pure Python COCO RLE codec with no new dependencies.

cc @PawelPeczek-Roboflow

Type of Change

• ✨ New feature (non-breaking change which adds functionality)

Motivation and Context

Workflows currently supports COCO RLE compressed string serialization for segmentation masks, originally for SAM3 instance segmentation and now also for semantic segmentation models where masks may not be contiguous and therefore can't be represented as polygons. We would like sv.Detections.from_inference() to handle such data and automatically decode it into binary masks as it currently does for polygon mask data.

The existing rle_to_mask util supports this conversion but not from compressed strings (see #1952).

Closes #1952

Changes Made

• Add RLE mask support to sv.Detections.from_inference for models like SAM3 and semantic segmentation that return compressed COCO RLE instead of polygons
• Extend rle_to_mask to accept compressed COCO RLE strings (no new dependencies — pure Python decoder)
• Add compressed flag to mask_to_rle for producing COCO RLE strings
• Move rle_to_mask and mask_to_rle from dataset/utils to detection/utils/converters with the other converters - necessary to avoid circular dependency, and dataset.utils already imports from detection.utils.converters - backwards compatibility maintained through re-export
• Bugfix: rle_to_mask return type was uint8, now bool as per function signature

Testing

• I have tested this code locally
• I have added unit tests that prove my fix is effective or that my feature works
• All new and existing tests pass

Google Colab (optional)

Colab link:

Screenshots/Videos (optional)

Additional Notes

[codecov]

Codecov Report

❌ Patch coverage is 97.14286% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 77%. Comparing base (f28874c) to head (1b9a1d4).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2178   +/-   ##
=======================================
  Coverage       77%     77%           
=======================================
  Files           66      66           
  Lines         8115    8189   +74     
=======================================
+ Hits          6232    6303   +71     
- Misses        1883    1886    +3     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds compressed COCO RLE mask support across Supervision’s detection inference pipeline and converters, enabling sv.Detections.from_inference() to decode masks provided as compressed RLE strings/bytes (e.g., SAM3 / semantic segmentation outputs) without adding dependencies.

Changes:

• Implement pure-Python COCO compressed RLE string encode/decode and extend rle_to_mask / mask_to_rle to support compressed formats.
• Update inference result processing to accept RLE mask payloads (rle / rle_mask) and build Detections.mask accordingly.
• Move RLE utilities into detection.utils.converters, update exports/docs, and relocate tests accordingly.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/detection/utils/test_internal.py	Adds inference parsing test cases for compressed RLE masks (incl. non-contiguous + tracker_id).
tests/detection/utils/test_converters.py	Adds unit tests for compressed RLE codec and mask↔RLE conversions.
tests/dataset/test_utils.py	Removes RLE tests from dataset utils (now covered under converters).
src/supervision/detection/utils/internal.py	Extends Roboflow/inference result parsing to decode RLE masks.
src/supervision/detection/utils/converters.py	Adds COCO compressed RLE codec + compressed support in converters.
src/supervision/dataset/utils.py	Removes old implementations and re-exports converters versions for compatibility.
src/supervision/dataset/formats/coco.py	Updates imports to use the new converter locations.
src/supervision/init.py	Exposes mask_to_rle / rle_to_mask from converters at top-level API.
mkdocs.yml	Removes datasets utils docs page from nav.
docs/detection/utils/converters.md	Documents rle_to_mask / mask_to_rle under converters.
docs/datasets/utils.md	Removes the old dataset utils docs page.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

src/supervision/detection/utils/internal.py:132

• process_roboflow_result builds masks only for predictions that include RLE/polygon data. If a batch mixes masked and box-only predictions, masks_arr ends up shorter than xyxy_arr, and Detections.from_inference() will raise during validation because mask.shape[0] != len(xyxy). Consider keeping masks aligned by appending an empty mask for box-only predictions whenever any mask is present in the batch (or, alternatively, dropping masks entirely when they can’t be produced for all predictions).

        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"])
            confidence.append(prediction["confidence"])
            if "tracker_id" in prediction:
                tracker_ids.append(prediction["tracker_id"])
        elif len(prediction["points"]) >= 3:

[Borda]

@leeclemnet could you pls check that updated version?