Merge branch 'develop' into feat/zone-coord-transform

Author: Borda

docs/changelog.md

@@ -11,6 +11,8 @@ date_modified: 2026-10-16
 
 - Transformed `sv.PolygonZone` anchors just outside the mask remain outside even when rounding would move a fractional coordinate onto the edge pixel. ([#2657](https://github.com/roboflow/supervision/pull/2657))
 
+- `sv.Detections.from_ultralytics` now removes letterbox padding using the rounded content dimensions. Fractional padding no longer shifts or truncates segmentation masks when restoring the original image resolution. ([#2739](https://github.com/roboflow/supervision/pull/2739))
+
 - `sv.Detections` indexed with a Python list of booleans, such as `detections[[c == 0 for c in detections.class_id]]`, now selects list-valued `data` with the same mask as its arrays. The list was read as positions, so `True` and `False` became the indices `1` and `0`: an all-`True` mask returned the second item for every row (`["cat", "dog", "bird"]` became `["dog", "dog", "dog"]`), any other mask failed with `ValueError: Length of list for key ... must be ...`, and a list of `np.bool_` values raised `TypeError`. Integer lists, slices and NumPy index arrays are unchanged. ([#2737](https://github.com/roboflow/supervision/pull/2737)) Integer-list selection allocates only for requested rows, avoiding quadratic position-array allocation when the smoother selects rows repeatedly.
 
 - `sv.move_boxes` and `InferenceSlicer` translations no longer wrap integer coordinates when an offset crosses the input dtype's bounds. A `uint8` box at `[250, 0, 255, 10]` shifted by `[10, 0]` previously became `[4, 0, 9, 10]`; translations now promote integer results to `int64`, or `float64` when the result exceeds the `int64` range, while floating-point behavior is unchanged. ([#2734](https://github.com/roboflow/supervision/pull/2734))

src/supervision/detection/utils/internal.py

@@ -42,9 +42,9 @@ def extract_ultralytics_masks(yolov8_results: Any) -> npt.NDArray[np.bool_] | No
     """Extract boolean masks from Ultralytics results, cropping letterbox padding.
 
     Handles the case where the inference resolution differs from the original image
-    shape by computing the letterbox padding offsets, cropping them out, and resizing
-    each proto mask back to `orig_shape`. Thresholds at 0.5 to match Ultralytics'
-    semantics and avoid dilating masks through float interpolation.
+    shape by recovering the rounded letterbox content size, cropping its padding,
+    and resizing each proto mask back to `orig_shape`. Thresholds at 0.5 to match
+    Ultralytics' semantics and avoid dilating masks through float interpolation.
 
     Args:
         yolov8_results: Ultralytics results object with `.masks` and `.orig_shape`.
@@ -59,20 +59,22 @@ def extract_ultralytics_masks(yolov8_results: Any) -> npt.NDArray[np.bool_] | No
     orig_shape = yolov8_results.orig_shape
     inference_shape = tuple(yolov8_results.masks.data.shape[1:])
 
-    pad = (0, 0)
+    top, left = 0, 0
+    bottom, right = inference_shape
 
     if inference_shape != orig_shape:
         gain = min(
             inference_shape[0] / orig_shape[0],
             inference_shape[1] / orig_shape[1],
         )
-        pad = (
-            (inference_shape[1] - orig_shape[1] * gain) / 2,
-            (inference_shape[0] - orig_shape[0] * gain) / 2,
-        )
-
-    top, left = int(pad[1]), int(pad[0])
-    bottom, right = int(inference_shape[0] - pad[1]), int(inference_shape[1] - pad[0])
+        # LetterBox rounds the resized content before splitting padding. An odd
+        # padding pixel belongs to the bottom/right, not to the content crop.
+        content_height = round(orig_shape[0] * gain)
+        content_width = round(orig_shape[1] * gain)
+        top = (inference_shape[0] - content_height) // 2
+        left = (inference_shape[1] - content_width) // 2
+        bottom = top + content_height
+        right = left + content_width
 
     mask_maps = []
     masks = _to_numpy(yolov8_results.masks.data)

tests/detection/test_ultralytics_arrays.py

@@ -57,6 +57,38 @@ def _boxes(backend: str, count: int, tracked: bool = False) -> SimpleNamespace:
 class TestUltralyticsArrayResults:
     """Keep tensor and NumPy Results equivalent across the public adapters."""
 
+    @pytest.mark.parametrize("backend", ["numpy", "tensor"])
+    @pytest.mark.parametrize("portrait", [False, True])
+    @pytest.mark.parametrize("with_boxes", [False, True])
+    def test_restores_letterboxed_foreground(
+        self, backend: str, portrait: bool, with_boxes: bool
+    ) -> None:
+        """Removing rounded letterbox padding preserves every foreground pixel."""
+        masks = np.zeros((1, 448, 640), dtype=np.float32)
+        masks[:, 11:437, :] = 1
+        orig_shape = (333, 500)
+        if portrait:
+            masks = masks.transpose(0, 2, 1)
+            orig_shape = orig_shape[::-1]
+        height, width = orig_shape
+        xyxy = np.array([[0, 0, width - 1, height - 1]], dtype=np.float32)
+        boxes = _boxes(backend, 1)
+        boxes.xyxy = _property(xyxy, backend)
+        results = SimpleNamespace(
+            boxes=boxes if with_boxes else None,
+            obb=None,
+            masks=SimpleNamespace(data=_property(masks, backend)),
+            orig_shape=orig_shape,
+            names={0: "person"},
+        )
+
+        detections = Detections.from_ultralytics(results)
+
+        np.testing.assert_array_equal(
+            detections.mask, np.ones((1, height, width), bool)
+        )
+        np.testing.assert_array_equal(detections.xyxy, xyxy)
+
     @pytest.mark.parametrize("backend", ["numpy", "tensor"])
     @pytest.mark.parametrize(
         "tracked", [pytest.param(False, id="plain"), pytest.param(True, id="tracked")]

tests/detection/utils/test_internal.py

@@ -68,6 +68,47 @@ def test_extract_ultralytics_masks_thresholds_resized_proto_at_half() -> None:
     assert masks[0].sum() < int((resized > 0).sum())
 
 
+class TestExtractUltralyticsLetterboxMasks:
+    """Restore mask geometry after rounded and asymmetric letterbox padding."""
+
+    @pytest.mark.parametrize("portrait", [False, True])
+    @pytest.mark.parametrize(
+        ("orig_shape", "inference_shape", "content_rows"),
+        [
+            pytest.param((333, 500), (448, 640), (11, 437), id="fractional-padding"),
+            pytest.param((332, 500), (448, 640), (11, 436), id="odd-padding"),
+            pytest.param((480, 640), (640, 640), (80, 560), id="integer-padding"),
+            pytest.param((320, 320), (640, 640), (0, 640), id="resize-without-padding"),
+            pytest.param((17, 19), (17, 19), (0, 17), id="original-resolution"),
+        ],
+    )
+    def test_preserves_content_geometry(
+        self,
+        portrait: bool,
+        orig_shape: tuple[int, int],
+        inference_shape: tuple[int, int],
+        content_rows: tuple[int, int],
+    ) -> None:
+        """Foreground bands are scaled from content pixels, excluding padding."""
+        top, bottom = content_rows
+        content = np.zeros((bottom - top, inference_shape[1]), dtype=np.float32)
+        content[2:-2, 2:-2] = 1
+        content[5:9] = 0
+        proto = np.zeros((1, *inference_shape), dtype=np.float32)
+        proto[0, top:bottom] = content
+        if portrait:
+            proto = proto.transpose(0, 2, 1)
+            content = content.T
+            orig_shape = orig_shape[::-1]
+        expected = cv2.resize(content, (orig_shape[1], orig_shape[0])) > 0.5
+        results = _FakeYOLOMaskResults(masks_arr=proto, orig_shape=orig_shape)
+
+        actual = extract_ultralytics_masks(results)
+
+        assert actual is not None
+        np.testing.assert_array_equal(actual[0], expected)
+
+
 def _pred(
     yx: tuple[float, float] = (1.5, 1.5),
     size: tuple[float, float] = (2.0, 2.0),