Wire scalebar_dx/scalebar_units into pl.show() (closes #614)

The scalebar machinery (ScalebarParams, _get_scalebar, ScaleBar import) was
present but unreachable: show() did not declare or forward scalebar_dx /
scalebar_units, so any user attempt raised TypeError. The downstream
ScaleBar(dx=[...], units=[...]) call in _add_decorations_to_ax also passed
broadcast lists where ScaleBar requires scalars, and ran once per render
layer (so multi-layer plots would have stacked duplicates).

- Add scalebar_dx, scalebar_units (default "um"), and scalebar_params
  (kwargs dict, mirroring colorbar_params) to show()'s signature.
- Centralize drawing in _draw_scalebar(ax, params, panel_idx); call it once
  per axis at the tail of show()'s panel loop.
- Drop the broken scalebar block + scalebar_dx/units kwargs from
  _add_decorations_to_ax; drop the now-unused scalebar_params arg from
  _render_{shapes,points,images,labels} and _add_legend_and_colorbar.
- Validate scalebar_dx/units/params types and sign in
  _validate_show_parameters.
- Add 9 non-visual regression tests + 2 visual tests (default and styled).

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -54,6 +54,7 @@
 )
 from spatialdata_plot.pl.utils import (
     _RENDER_CMD_TO_CS_FLAG,
+    _draw_scalebar,
     _get_cs_contents,
     _get_elements_to_be_rendered,
     _get_valid_cs,
@@ -889,6 +890,9 @@ def show(
         return_ax: bool = False,
         save: str | Path | None = None,
         show: bool | None = None,
+        scalebar_dx: float | None = None,
+        scalebar_units: str = "um",
+        scalebar_params: dict[str, Any] | None = None,
     ) -> Axes | list[Axes] | None:
         """
         Execute the plotting tree and display the final figure.
@@ -949,6 +953,18 @@ def show(
             automatically when running in non-interactive mode (scripts) and suppressed in
             interactive sessions (e.g. Jupyter). When ``ax`` is provided by the user, defaults
             to ``False`` to allow further modifications.
+        scalebar_dx : float | None
+            Physical size of one axes-unit in ``scalebar_units``. If ``None``, no scalebar is drawn.
+            SpatialData coordinate systems carry no unit metadata, so this value must be supplied
+            explicitly (e.g. ``1.0`` when axes are already in micrometers; the microns-per-pixel
+            value when axes are in image pixels).
+        scalebar_units : str, default "um"
+            Unit string for the scalebar (passed to :class:`matplotlib_scalebar.scalebar.ScaleBar`).
+            Only takes effect when ``scalebar_dx`` is set.
+        scalebar_params : dict[str, Any] | None
+            Extra keyword arguments forwarded to :class:`matplotlib_scalebar.scalebar.ScaleBar`,
+            e.g. ``{"location": "lower right", "color": "white", "length_fraction": 0.25}``.
+            See the matplotlib-scalebar documentation for the full list of options.
 
         Returns
         -------
@@ -986,6 +1002,9 @@ def show(
             return_ax,
             save,
             show,
+            scalebar_dx,
+            scalebar_units,
+            scalebar_params,
         )
 
         if fig is not None and not isinstance(ax, Sequence):
@@ -1098,7 +1117,7 @@ def show(
                 raise ValueError(msg)
 
         # set up canvas
-        fig_params, scalebar_params = _prepare_params_plot(
+        fig_params, scalebar_params_obj = _prepare_params_plot(
             num_panels=len(coordinate_systems),
             figsize=figsize,
             dpi=dpi,
@@ -1108,6 +1127,9 @@ def show(
             hspace=hspace,
             ncols=ncols,
             frameon=frameon,
+            scalebar_dx=scalebar_dx,
+            scalebar_units=scalebar_units,
+            scalebar_kwargs=scalebar_params,
         )
         legend_colorbar = colorbar
         legend_params = LegendParams(
@@ -1237,7 +1259,6 @@ def _draw_colorbar(
                             coordinate_system=cs,
                             ax=ax,
                             fig_params=fig_params,
-                            scalebar_params=scalebar_params,
                             legend_params=legend_params,
                             colorbar_requests=axis_colorbar_requests,
                             channel_legend_entries=axis_channel_legend_entries,
@@ -1256,7 +1277,6 @@ def _draw_colorbar(
                             coordinate_system=cs,
                             ax=ax,
                             fig_params=fig_params,
-                            scalebar_params=scalebar_params,
                             legend_params=legend_params,
                             colorbar_requests=axis_colorbar_requests,
                         )
@@ -1273,7 +1293,6 @@ def _draw_colorbar(
                             coordinate_system=cs,
                             ax=ax,
                             fig_params=fig_params,
-                            scalebar_params=scalebar_params,
                             legend_params=legend_params,
                             colorbar_requests=axis_colorbar_requests,
                         )
@@ -1309,7 +1328,6 @@ def _draw_colorbar(
                             coordinate_system=cs,
                             ax=ax,
                             fig_params=fig_params,
-                            scalebar_params=scalebar_params,
                             legend_params=legend_params,
                             colorbar_requests=axis_colorbar_requests,
                             rasterize=rasterize,
@@ -1356,6 +1374,8 @@ def _draw_colorbar(
             if axis_channel_legend_entries:
                 _draw_channel_legend(ax, axis_channel_legend_entries, legend_params, fig_params)
 
+            _draw_scalebar(ax, scalebar_params_obj, panel_idx=i)
+
         if pending_colorbars and fig_params.fig is not None:
             fig = fig_params.fig
             fig.canvas.draw()

src/spatialdata_plot/pl/render.py

@@ -53,7 +53,6 @@
     LabelsRenderParams,
     LegendParams,
     PointsRenderParams,
-    ScalebarParams,
     ShapesRenderParams,
 )
 from spatialdata_plot.pl.utils import (
@@ -268,9 +267,8 @@ def _add_legend_and_colorbar(
     colorbar: bool | str | None,
     colorbar_params: dict[str, object] | None,
     colorbar_requests: list[ColorbarSpec] | None,
-    scalebar_params: ScalebarParams,
 ) -> None:
-    """Add legend, colorbar, and scalebar decorations if the color vector warrants them."""
+    """Add legend and colorbar decorations if the color vector warrants them."""
     if not _want_decorations(color_vector, na_color):
         return
 
@@ -309,8 +307,6 @@ def _add_legend_and_colorbar(
             colorbar_params,
             col_for_color if isinstance(col_for_color, str) else None,
         ),
-        scalebar_dx=scalebar_params.scalebar_dx,
-        scalebar_units=scalebar_params.scalebar_units,
     )
 
 
@@ -320,7 +316,6 @@ def _render_shapes(
     coordinate_system: str,
     ax: matplotlib.axes.SubplotBase,
     fig_params: FigParams,
-    scalebar_params: ScalebarParams,
     legend_params: LegendParams,
     colorbar_requests: list[ColorbarSpec] | None = None,
 ) -> None:
@@ -696,7 +691,6 @@ def _render_shapes(
         colorbar=render_params.colorbar,
         colorbar_params=render_params.colorbar_params,
         colorbar_requests=colorbar_requests,
-        scalebar_params=scalebar_params,
     )
 
 
@@ -706,7 +700,6 @@ def _render_points(
     coordinate_system: str,
     ax: matplotlib.axes.SubplotBase,
     fig_params: FigParams,
-    scalebar_params: ScalebarParams,
     legend_params: LegendParams,
     colorbar_requests: list[ColorbarSpec] | None = None,
 ) -> None:
@@ -1050,7 +1043,6 @@ def _render_points(
         colorbar=render_params.colorbar,
         colorbar_params=render_params.colorbar_params,
         colorbar_requests=colorbar_requests,
-        scalebar_params=scalebar_params,
     )
 
 
@@ -1197,7 +1189,6 @@ def _render_images(
     coordinate_system: str,
     ax: matplotlib.axes.SubplotBase,
     fig_params: FigParams,
-    scalebar_params: ScalebarParams,
     legend_params: LegendParams,
     rasterize: bool,
     colorbar_requests: list[ColorbarSpec] | None = None,
@@ -1592,7 +1583,6 @@ def _render_labels(
     coordinate_system: str,
     ax: matplotlib.axes.SubplotBase,
     fig_params: FigParams,
-    scalebar_params: ScalebarParams,
     legend_params: LegendParams,
     rasterize: bool,
     colorbar_requests: list[ColorbarSpec] | None = None,
@@ -1821,7 +1811,4 @@ def _draw_labels(
             render_params.colorbar_params,
             col_for_color if isinstance(col_for_color, str) else None,
         ),
-        scalebar_dx=scalebar_params.scalebar_dx,
-        scalebar_units=scalebar_params.scalebar_units,
-        # scalebar_kwargs=scalebar_params.scalebar_kwargs,
     )

src/spatialdata_plot/pl/render_params.py

@@ -1,8 +1,8 @@
 from __future__ import annotations
 
-from collections.abc import Callable, Sequence
-from dataclasses import dataclass
-from typing import Literal
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal
 
 import numpy as np
 from matplotlib.axes import Axes
@@ -220,6 +220,7 @@ class ScalebarParams:
 
     scalebar_dx: Sequence[float] | None = None
     scalebar_units: Sequence[str] | None = None
+    scalebar_kwargs: Mapping[str, Any] = field(default_factory=dict)
 
 
 @dataclass

src/spatialdata_plot/pl/utils.py

@@ -7,7 +7,6 @@
 from copy import copy
 from functools import partial
 from pathlib import Path
-from types import MappingProxyType
 from typing import Any, Literal
 
 import dask
@@ -273,6 +272,7 @@ def _prepare_params_plot(
     # this args will be inferred from coordinate system
     scalebar_dx: float | Sequence[float] | None = None,
     scalebar_units: str | Sequence[str] | None = None,
+    scalebar_kwargs: Mapping[str, Any] | None = None,
 ) -> tuple[FigParams, ScalebarParams]:
     # handle axes and size
     wspace = 0.75 / rcParams["figure.figsize"][0] + 0.02 if wspace is None else wspace
@@ -325,11 +325,29 @@ def _prepare_params_plot(
         num_panels=num_panels,
         frameon=frameon,
     )
-    scalebar_params = ScalebarParams(scalebar_dx=scalebar_dx, scalebar_units=scalebar_units)
+    scalebar_params = ScalebarParams(
+        scalebar_dx=scalebar_dx,
+        scalebar_units=scalebar_units,
+        scalebar_kwargs=dict(scalebar_kwargs) if scalebar_kwargs else {},
+    )
 
     return fig_params, scalebar_params
 
 
+def _draw_scalebar(ax: Axes, scalebar_params: ScalebarParams, panel_idx: int) -> None:
+    """Attach a single :class:`matplotlib_scalebar.scalebar.ScaleBar` to ``ax``.
+
+    No-op when ``scalebar_dx`` is ``None``. ``scalebar_dx`` and ``scalebar_units`` are
+    broadcast lists indexed by the panel position; ``scalebar_kwargs`` is forwarded
+    verbatim to :class:`~matplotlib_scalebar.scalebar.ScaleBar`.
+    """
+    if scalebar_params.scalebar_dx is None or scalebar_params.scalebar_units is None:
+        return
+    dx = scalebar_params.scalebar_dx[panel_idx]
+    units = scalebar_params.scalebar_units[panel_idx]
+    ax.add_artist(ScaleBar(dx, units=units, **scalebar_params.scalebar_kwargs))
+
+
 def _get_cs_contents(sdata: sd.SpatialData) -> pd.DataFrame:
     """Check which coordinate systems contain which elements and return that info."""
     cs_mapping = _get_coordinate_system_mapping(sdata)
@@ -1694,9 +1712,6 @@ def _decorate_axs(
     colorbar_params: dict[str, object] | None = None,
     colorbar_requests: list[ColorbarSpec] | None = None,
     colorbar_label: str | None = None,
-    scalebar_dx: Sequence[float] | None = None,
-    scalebar_units: Sequence[str] | None = None,
-    scalebar_kwargs: Mapping[str, Any] = MappingProxyType({}),
 ) -> Axes:
     if value_to_plot is not None:
         # if only dots were plotted without an associated value
@@ -1743,10 +1758,6 @@ def _decorate_axs(
                 )
             )
 
-    if isinstance(scalebar_dx, list) and isinstance(scalebar_units, list):
-        scalebar = ScaleBar(scalebar_dx, units=scalebar_units, **scalebar_kwargs)
-        ax.add_artist(scalebar)
-
     return ax
 
 
@@ -2159,6 +2170,9 @@ def _validate_show_parameters(
     return_ax: bool,
     save: str | Path | None,
     show: bool | None,
+    scalebar_dx: float | None,
+    scalebar_units: str,
+    scalebar_params: dict[str, Any] | None,
 ) -> None:
     if coordinate_systems is not None and not isinstance(coordinate_systems, list | str):
         raise TypeError("Parameter 'coordinate_systems' must be a string or a list of strings.")
@@ -2248,6 +2262,17 @@ def _validate_show_parameters(
     if show is not None and not isinstance(show, bool):
         raise TypeError("Parameter 'show' must be a boolean or None.")
 
+    if scalebar_dx is not None:
+        if not isinstance(scalebar_dx, int | float) or isinstance(scalebar_dx, bool):
+            raise TypeError("Parameter 'scalebar_dx' must be a number or None.")
+        if scalebar_dx <= 0:
+            raise ValueError("Parameter 'scalebar_dx' must be > 0.")
+        if not isinstance(scalebar_units, str):
+            raise TypeError("Parameter 'scalebar_units' must be a string.")
+
+    if scalebar_params is not None and not isinstance(scalebar_params, dict):
+        raise TypeError("Parameter 'scalebar_params' must be a dictionary or None.")
+
 
 def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[str, Any]:
     colorbar = param_dict.get("colorbar", "auto")