fix(annotators): draw masks and halos on grayscale scenes (#2755)

`MaskAnnotator` and `HaloAnnotator` raised `ValueError` on grayscale
scenes, shaped `(H, W)` or `(H, W, 1)` or given as a Pillow "L" image,
because `_paint_masks_by_area` assigned a three-value BGR color to
single-channel pixels. Other annotators draw on the same scenes through
OpenCV, which writes the first (blue) channel of the color.

Paint grayscale canvases with that first channel, restore the singleton
channel axis that OpenCV drops in `addWeighted` and `blur`, and compute
the halo alpha from the single channel instead of `COLOR_BGR2GRAY`.
BGR scenes are unchanged.

---------

Co-authored-by: jirka <6035284+borda@users.noreply.github.com>
Co-authored-by: Codex <codex@openai.com>

Author: 3 people

docs/changelog.md

@@ -7,6 +7,8 @@ date_modified: 2026-10-16
 
 ### Unreleased <small>upcoming</small>
 
+- `sv.MaskAnnotator` and `sv.HaloAnnotator` now annotate grayscale scenes, shaped `(H, W)` or `(H, W, 1)` or given as a Pillow `"L"` image, instead of raising `ValueError`. Masks and halos take the first (blue) channel of their color, the gray value OpenCV writes for boxes and polygons on the same scene. ([#2755](https://github.com/roboflow/supervision/pull/2755))
+
 - `sv.Detections.with_nmm` now computes area-weighted confidence without overflowing integer, float16 or float32 box extents. ([#2753](https://github.com/roboflow/supervision/pull/2753))
 
 - `sv.metrics.MeanAverageRecall`, `Precision`, `Recall` and `F1Score` with `metric_target=MetricTarget.ORIENTED_BOUNDING_BOXES` now count a prediction whose IoU is exactly 0.55, 0.6, 0.8 or 0.85 as a match at that threshold, as they do for boxes and masks. The oriented-box IoU was float64 while the thresholds are float32, which rounds those four values up. ([#2752](https://github.com/roboflow/supervision/pull/2752))

src/supervision/annotators/core.py

@@ -438,6 +438,20 @@ def _iter_mask_crops(
             )
 
 
+def _color_for_canvas(
+    color_bgr: tuple[int, int, int], canvas: npt.NDArray[np.uint8]
+) -> tuple[int, ...]:
+    """Return the color as the pixel value OpenCV drawing writes to `canvas`.
+
+    A grayscale canvas, shaped ``(H, W)`` or ``(H, W, 1)``, takes the first
+    (blue) channel, as ``cv2.rectangle`` and ``cv2.fillPoly`` do, so masks match
+    the boxes and polygons other annotators draw on the same scene.
+    """
+    if canvas.ndim == 2 or canvas.shape[2] == 1:
+        return color_bgr[:1]
+    return color_bgr
+
+
 def _paint_masks_by_area(
     canvas: npt.NDArray[np.uint8],
     detections: Detections,
@@ -454,7 +468,8 @@ def _paint_masks_by_area(
     allocation per mask; dense masks fall back to full-frame boolean indexing.
 
     Args:
-        canvas: BGR image array painted in place. Shape ``(H, W, 3)``.
+        canvas: Image array painted in place: BGR of shape ``(H, W, 3)``, or
+            grayscale of shape ``(H, W)`` or ``(H, W, 1)``.
         detections: Detections whose masks to paint. Returns immediately
             without modifying `canvas` when ``detections.mask`` is ``None``.
         color: Single color or palette used to resolve each detection's color.
@@ -482,12 +497,15 @@ def _paint_masks_by_area(
     origin_x, origin_y = canvas_origin
     canvas_h, canvas_w = canvas.shape[:2]
     for detection_idx in np.flip(np.argsort(detections.area)):
-        color_bgr = resolve_color(
-            color=color,
-            detections=detections,
-            detection_idx=detection_idx,
-            color_lookup=color_lookup,
-        ).as_bgr()
+        pixel_value = _color_for_canvas(
+            resolve_color(
+                color=color,
+                detections=detections,
+                detection_idx=detection_idx,
+                color_lookup=color_lookup,
+            ).as_bgr(),
+            canvas,
+        )
         if compact_mask is not None:
             x1 = int(compact_mask.offsets[detection_idx, 0])
             y1 = int(compact_mask.offsets[detection_idx, 1])
@@ -508,7 +526,7 @@ def _paint_masks_by_area(
                 canvas_y1 : canvas_y1 + paint_h,
                 canvas_x1 : canvas_x1 + paint_w,
             ]
-            canvas_slice[crop_slice] = color_bgr
+            canvas_slice[crop_slice] = pixel_value
             if union is not None:
                 union[
                     canvas_y1 : canvas_y1 + paint_h,
@@ -517,7 +535,7 @@ def _paint_masks_by_area(
         else:
             mask = np.asarray(masks[detection_idx], dtype=bool)
             mask = mask[origin_y : origin_y + canvas_h, origin_x : origin_x + canvas_w]
-            canvas[mask] = color_bgr
+            canvas[mask] = pixel_value
             if union is not None:
                 union |= mask
     return union
@@ -564,7 +582,9 @@ def annotate(
         Args:
             scene: The image where masks will be drawn.
                 `ImageType` is a flexible type, accepting either `numpy.ndarray`
-                or `PIL.Image.Image`.
+                or `PIL.Image.Image`. Grayscale arrays may have shape `(H, W)`
+                or `(H, W, 1)`; masks are drawn in the first (blue) channel of
+                their color, as OpenCV draws boxes and polygons.
             detections: Object detections to annotate.
             custom_color_lookup: Custom color lookup array.
                 Allows to override the default color mapping strategy.
@@ -627,7 +647,8 @@ def annotate(
         tmp = cv2.addWeighted(
             colored_mask, self.opacity, scene_roi.copy(), 1 - self.opacity, 0
         )
-        scene_roi[:] = tmp
+        # OpenCV drops a singleton channel axis; restore it before assignment.
+        scene_roi[:] = tmp.reshape(scene_roi.shape)
         return scene
 
 
@@ -866,7 +887,9 @@ def annotate(
         Args:
             scene: The image where the halo effect will be applied.
                 `ImageType` is a flexible type, accepting either `numpy.ndarray`
-                or `PIL.Image.Image`.
+                or `PIL.Image.Image`. Grayscale arrays may have shape `(H, W)`
+                or `(H, W, 1)`; halos are drawn in the first (blue) channel of
+                their color, as OpenCV draws boxes and polygons.
             detections: Object detections to annotate.
             custom_color_lookup: Custom color lookup array.
                 Allows to override the default color mapping strategy.
@@ -910,18 +933,21 @@ def annotate(
         )
         assert fmask is not None  # collect_union=True always returns an array
 
-        colored_mask = cast(
-            npt.NDArray[np.uint8],
-            cv2.blur(colored_mask, (self.kernel_size, self.kernel_size)),
-        )
-        colored_mask[fmask] = [0, 0, 0]
-        gray = cv2.cvtColor(colored_mask, cv2.COLOR_BGR2GRAY)
+        # OpenCV drops a singleton channel axis; restore the scene's layout.
+        colored_mask = cv2.blur(
+            colored_mask, (self.kernel_size, self.kernel_size)
+        ).reshape(scene.shape)
+        colored_mask[fmask] = 0
+        if colored_mask.ndim == 2 or colored_mask.shape[2] == 1:
+            gray = colored_mask.reshape(scene.shape[:2])
+        else:
+            gray = cv2.cvtColor(colored_mask, cv2.COLOR_BGR2GRAY)
         gray_max = gray.max()
         if gray_max == 0:
             # no halo to draw (e.g. empty masks); leave the scene untouched
             return scene
         alpha = self.opacity * gray / gray_max
-        alpha_mask = alpha[:, :, np.newaxis]
+        alpha_mask = alpha if scene.ndim == 2 else alpha[:, :, np.newaxis]
         # Blend in float space so halo opacity cannot wrap around uint8 boundaries.
         blended_scene = np.clip(
             scene.astype(np.float32) * (1 - alpha_mask)

tests/annotators/test_core.py

@@ -770,6 +770,108 @@ def test_annotate_with_all_false_mask_preserves_scene(self):
         assert np.array_equal(result, scene)
 
 
+class TestSingleChannelMaskAnnotators:
+    """Verify mask-painting annotators on grayscale scenes."""
+
+    @staticmethod
+    def _detections(compact: bool = False) -> Detections:
+        """Return one square mask detection inside a 30x40 scene."""
+        mask = np.zeros((1, 30, 40), dtype=bool)
+        mask[0, 8:20, 10:26] = True
+        xyxy = np.array([[10, 8, 25, 19]], dtype=np.float32)
+        masks = CompactMask.from_dense(mask, xyxy, (30, 40)) if compact else mask
+        return Detections(xyxy=xyxy, mask=masks, class_id=np.array([0]))
+
+    @pytest.mark.parametrize(
+        "annotator",
+        [
+            pytest.param(
+                MaskAnnotator(color=Color(r=180, g=180, b=180), opacity=0.6),
+                id="mask",
+            ),
+            pytest.param(
+                HaloAnnotator(color=Color(r=180, g=180, b=180), kernel_size=5),
+                id="halo",
+            ),
+        ],
+    )
+    @pytest.mark.parametrize("channel_axis", [False, True])
+    @pytest.mark.parametrize("compact", [False, True])
+    def test_grayscale_matches_color_scene(
+        self,
+        annotator: MaskAnnotator | HaloAnnotator,
+        channel_axis: bool,
+        compact: bool,
+    ) -> None:
+        """A grayscale scene is annotated like each channel of its BGR copy."""
+        gray = np.arange(30 * 40, dtype=np.uint8).reshape(30, 40)
+        scene = gray[..., None].copy() if channel_axis else gray.copy()
+        color_scene = np.repeat(gray[..., None], 3, axis=2)
+        detections = self._detections(compact=compact)
+        expected = annotator.annotate(scene=color_scene, detections=detections)
+
+        result = annotator.annotate(scene=scene, detections=detections)
+
+        assert result is scene
+        assert result.shape == scene.shape
+        np.testing.assert_array_equal(result.reshape(30, 40), expected[..., 0])
+        assert not np.array_equal(result.reshape(30, 40), gray)
+
+    def test_halo_grayscale_uses_blue_color_component(self) -> None:
+        """A grayscale halo responds to changes in the BGR blue component."""
+        scene = np.zeros((30, 40), dtype=np.uint8)
+        detections = self._detections()
+        blue_halo = HaloAnnotator(
+            color=Color(r=20, g=40, b=220), kernel_size=5
+        ).annotate(scene=scene.copy(), detections=detections)
+        dim_blue_halo = HaloAnnotator(
+            color=Color(r=20, g=40, b=20), kernel_size=5
+        ).annotate(scene=scene.copy(), detections=detections)
+
+        assert blue_halo[7, 15] > dim_blue_halo[7, 15]
+
+    @pytest.mark.parametrize(
+        "annotator_type",
+        [
+            pytest.param(MaskAnnotator, id="mask"),
+            pytest.param(PolygonAnnotator, id="polygon"),
+            pytest.param(ColorAnnotator, id="color"),
+        ],
+    )
+    def test_grayscale_draws_first_color_channel(
+        self,
+        annotator_type: type[MaskAnnotator]
+        | type[PolygonAnnotator]
+        | type[ColorAnnotator],
+    ) -> None:
+        """Masks take the same gray value as other annotators' OpenCV drawing."""
+        color = Color(r=10, g=20, b=200)
+        if annotator_type is PolygonAnnotator:
+            annotator: MaskAnnotator | PolygonAnnotator | ColorAnnotator = (
+                PolygonAnnotator(color=color)
+            )
+        else:
+            annotator = annotator_type(color=color, opacity=1.0)
+        scene = np.zeros((30, 40), dtype=np.uint8)
+
+        result = annotator.annotate(scene=scene, detections=self._detections())
+
+        assert result[8, 18] == color.b
+
+    def test_grayscale_pillow_image(self) -> None:
+        """A Pillow grayscale image is annotated and returned as one."""
+        image = Image.new("L", (40, 30), color=50)
+
+        result = MaskAnnotator(color=Color.WHITE, opacity=1.0).annotate(
+            scene=image, detections=self._detections()
+        )
+
+        assert isinstance(result, Image.Image)
+        assert result.mode == "L"
+        assert result.getpixel((18, 12)) == 255
+        assert result.getpixel((2, 2)) == 50
+
+
 class TestPaintMasksByArea:
     """Tests for the _paint_masks_by_area helper function."""