fix(shapes,labels): re-add outline bool toggle (#748)

The `outline` parameter was removed in favor of inferring outline visibility
from outline_alpha/outline_width/outline_color. It kept working silently only
because **kwargs swallowed it; removing **kwargs turned every outline=... call
into a TypeError, breaking notebooks and downstream code.

Re-introduce `outline` as a first-class convenience toggle (tri-state):
- None (default): infer visibility from the outline_* detail params (no change).
- True: force outline on, defaulting any unset detail param.
- False: force outline off, overriding detail params (warns on conflict).

outline is authoritative over inference; detail params only control how the
outline looks. Applied to both render_shapes and render_labels.

Author: timtreis

src/spatialdata_plot/pl/_color.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Mapping, Sequence
 from copy import copy
 from dataclasses import dataclass, replace
@@ -312,6 +313,31 @@ def _set_outline(
     )
 
 
+def _resolve_outline_toggle(
+    outline: bool | None,
+    outline_alpha: float | int | tuple[float | int, float | int] | None,
+    detail_params_set: bool,
+) -> float | int | tuple[float | int, float | int] | None:
+    """Resolve the ``outline`` bool toggle onto an effective ``outline_alpha``.
+
+    - ``None``  -> ``outline_alpha`` unchanged (visibility inferred from the ``outline_*`` params).
+    - ``True``  -> force on: 1.0 if ``outline_alpha`` is unset/zero, else the given value.
+    - ``False`` -> force off: 0.0, warning if any ``outline_*`` param was also set.
+    """
+    if outline is None:
+        return outline_alpha
+    alpha_is_zero = outline_alpha is None or bool(np.all(np.asarray(outline_alpha, dtype=float) == 0.0))
+    if outline:
+        return 1.0 if alpha_is_zero else outline_alpha
+    if detail_params_set or not alpha_is_zero:
+        warnings.warn(
+            "`outline=False` overrides the `outline_*` parameters you set; no outline will be drawn.",
+            UserWarning,
+            stacklevel=3,
+        )
+    return 0.0
+
+
 def _get_colors_for_categorical_obs(
     categories: Sequence[str | int],
     palette: ListedColormap | str | list[str] | None = None,

src/spatialdata_plot/pl/basic.py

@@ -34,6 +34,7 @@
     _maybe_set_colors,
     _next_palette_colors,
     _prepare_cmap_norm,
+    _resolve_outline_toggle,
     _set_outline,
 )
 from spatialdata_plot.pl._validate import (
@@ -325,6 +326,7 @@ def render_shapes(
         groups: list[str] | str | None = None,
         palette: dict[str, str] | list[str] | str | None = None,
         na_color: ColorLike | None = "default",
+        outline: bool | None = None,
         outline_width: float | int | tuple[float | int, float | int] | None = None,
         outline_color: ColorLike | tuple[ColorLike] | None = None,
         outline_alpha: float | int | tuple[float | int, float | int] | None = None,
@@ -388,6 +390,10 @@ def render_shapes(
             elements are hidden. Pass any explicit color (e.g. ``"lightgray"``) to show them in that color instead.
             Accepts a named color (``"red"``), a hex string (``"#000000ff"``), or an RGB/RGBA list
             (``[1.0, 0.0, 0.0, 1.0]``). Pass ``None`` to make NA values fully transparent.
+        outline : bool | None, default None
+            Convenience on/off switch. ``None`` infers visibility from the ``outline_*`` params;
+            ``True`` forces an outline on (defaults fill in any unset width/color/alpha); ``False``
+            forces it off, overriding and warning about any ``outline_*`` you set.
         outline_width : float | int | tuple[float | int, float | int], optional
             Width of the border. If 2 values are given (tuple), 2 borders are shown with these widths (outer & inner).
             If `outline_color` and/or `outline_alpha` are used to indicate that one/two outlines should be drawn, the
@@ -466,6 +472,9 @@ def render_shapes(
         """
         if as_points:
             _validate_as_points_size(size)
+        outline_alpha = _resolve_outline_toggle(
+            outline, outline_alpha, outline_width is not None or outline_color is not None
+        )
         panel_param_dicts = _expand_color_panels(
             self._sdata,
             color,
@@ -968,6 +977,7 @@ def render_labels(
         cmap: Colormap | str | None = None,
         norm: Normalize | None = None,
         na_color: ColorLike | None = "default",
+        outline: bool | None = None,
         outline_alpha: float | int = 0.0,
         fill_alpha: float | int | None = None,
         outline_color: ColorLike | None = None,
@@ -1029,6 +1039,10 @@ def render_labels(
             labels are hidden. Pass any explicit color (e.g. ``"lightgray"``) to show them in that color instead.
             Accepts a named color (``"red"``), a hex string (``"#000000ff"``), or an RGB/RGBA list
             (``[1.0, 0.0, 0.0, 1.0]``). Pass ``None`` to make NA values fully transparent.
+        outline : bool | None, default None
+            Convenience on/off switch; thickness is set by ``contour_px``. ``None`` infers visibility from
+            ``outline_color``/``outline_alpha``; ``True`` forces on (alpha defaults to 1.0); ``False``
+            forces it off, overriding and warning about any params you set.
         outline_alpha : float | int, default 0.0
             Alpha value for the outline of the labels. Invisible by default.
         fill_alpha : float | int | None, optional
@@ -1078,6 +1092,8 @@ def render_labels(
         """
         if as_points:
             _validate_as_points_size(size)
+        # labels outline_alpha is always scalar; cast narrows the helper's wider return union
+        outline_alpha = cast("float | int", _resolve_outline_toggle(outline, outline_alpha, outline_color is not None))
         panel_param_dicts = _expand_color_panels(
             self._sdata,
             color,

tests/pl/test_render_labels.py

@@ -921,3 +921,21 @@ def test_resolve_as_points_method_threshold_and_fallback():
     # explicit matplotlib always matplotlib; empty always matplotlib
     assert _resolve_as_points_method(rp_mpl, n=10**9, allow_datashader=True) == "matplotlib"
     assert _resolve_as_points_method(rp_auto, n=0, allow_datashader=True) == "matplotlib"
+
+
+# Regression tests for #748: the `outline` bool convenience toggle on render_labels.
+def test_outline_toggle_true_draws_outline(sdata_blobs: SpatialData):
+    # outline=True must not raise (the reported regression) and forces outline_alpha to 1.0.
+    on = sdata_blobs.pl.render_labels("blobs_labels", outline=True, contour_px=15)
+    assert list(on.plotting_tree.values())[-1].outline_alpha == 1.0
+
+
+def test_outline_toggle_none_preserves_default_off(sdata_blobs: SpatialData):
+    off = sdata_blobs.pl.render_labels("blobs_labels")
+    assert list(off.plotting_tree.values())[-1].outline_alpha == 0.0
+
+
+def test_outline_toggle_false_forces_off_and_warns(sdata_blobs: SpatialData):
+    with pytest.warns(UserWarning, match="outline=False"):
+        out = sdata_blobs.pl.render_labels("blobs_labels", outline=False, outline_color="red")
+    assert list(out.plotting_tree.values())[-1].outline_alpha == 0.0

tests/pl/test_render_shapes.py

@@ -2005,3 +2005,31 @@ def test_scale_geometries_matches_affinity_scale():
         expected = np.array([affinity.scale(g, xfact=scale, yfact=scale) for g in geoms], dtype=object)
         result = _scale_geometries(arr, scale)
         assert all(shapely.equals_exact(a, b, tolerance=1e-9) for a, b in zip(expected, result, strict=True))
+
+
+# Regression tests for #748: the `outline` bool convenience toggle on render_shapes.
+# It resolves onto the outline_* detail params; outline is authoritative over inference.
+def test_outline_toggle_true_draws_outline_like_alpha(sdata_blobs: SpatialData):
+    # outline=True must not raise (the reported regression) and must draw an outline
+    # equivalent to setting outline_alpha=1.0 explicitly.
+    on = sdata_blobs.pl.render_shapes("blobs_polygons", outline=True)
+    explicit = sdata_blobs.pl.render_shapes("blobs_polygons", outline_alpha=1.0)
+    on_alpha = list(on.plotting_tree.values())[-1].outline_alpha
+    explicit_alpha = list(explicit.plotting_tree.values())[-1].outline_alpha
+    assert on_alpha[0] > 0
+    assert on_alpha == explicit_alpha
+
+
+def test_outline_toggle_none_preserves_inference(sdata_blobs: SpatialData):
+    # Default (outline=None) keeps current behavior: no outline unless a detail param is set.
+    off = sdata_blobs.pl.render_shapes("blobs_polygons")
+    inferred = sdata_blobs.pl.render_shapes("blobs_polygons", outline_alpha=1.0)
+    assert list(off.plotting_tree.values())[-1].outline_alpha[0] == 0
+    assert list(inferred.plotting_tree.values())[-1].outline_alpha[0] > 0
+
+
+def test_outline_toggle_false_forces_off_and_warns(sdata_blobs: SpatialData):
+    # outline=False wins over explicit detail params and warns about the conflict.
+    with pytest.warns(UserWarning, match="outline=False"):
+        out = sdata_blobs.pl.render_shapes("blobs_polygons", outline=False, outline_color="red")
+    assert list(out.plotting_tree.values())[-1].outline_alpha[0] == 0