Add per-channel norm support for render_images (#460)

Accept a list of Normalize objects in render_images so each channel
can be normalized independently — essential for multi-channel protein
data with vastly different intensity ranges.

The rendering pipeline already reads per-channel norms from CmapParams,
so this change only widens the input validation and routes per-channel
norms into the existing CmapParams creation loop.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -513,7 +513,7 @@ def render_images(
         *,
         channel: list[str] | list[int] | str | int | None = None,
         cmap: list[Colormap | str] | Colormap | str | None = None,
-        norm: Normalize | None = None,
+        norm: list[Normalize] | Normalize | None = None,
         na_color: ColorLike | None = "default",
         palette: list[str] | str | None = None,
         alpha: float | int = 1.0,
@@ -544,9 +544,11 @@ def render_images(
         cmap : list[Colormap | str] | Colormap | str | None
             Colormap or list of colormaps for continuous annotations, see :class:`matplotlib.colors.Colormap`.
             Each colormap applies to a corresponding channel.
-        norm : Normalize | None, optional
+        norm : list[Normalize] | Normalize | None, optional
             Colormap normalization for continuous annotations, see :class:`matplotlib.colors.Normalize`.
-            Applies to all channels if set.
+            A single :class:`~matplotlib.colors.Normalize` applies to all channels.
+            A list of :class:`~matplotlib.colors.Normalize` objects applies per-channel
+            (length must match the number of colormaps/channels).
         na_color : ColorLike | None, default "default" (gets set to "lightgray")
             Color to be used for NAs values, if present. Can either be a named color ("red"), a hex representation
             ("#000000ff") or a list of floats that represent RGB/RGBA values (1.0, 0.0, 0.0, 1.0). When None, the values
@@ -631,13 +633,21 @@ def render_images(
         for element, param_values in params_dict.items():
             cmap_params: list[CmapParams] | CmapParams
             if isinstance(cmap, list):
+                if isinstance(norm, list):
+                    if len(norm) != len(cmap):
+                        raise ValueError(
+                            f"Length of 'norm' list ({len(norm)}) must match the number of colormaps ({len(cmap)})."
+                        )
+                    norms = norm
+                else:
+                    norms = [norm] * len(cmap)
                 cmap_params = [
                     _prepare_cmap_norm(
                         cmap=c,
-                        norm=norm,
+                        norm=n,
                         na_color=param_values["na_color"],
                     )
-                    for c in cmap
+                    for c, n in zip(cmap, norms, strict=True)
                 ]
 
             else:

src/spatialdata_plot/pl/utils.py

@@ -2409,8 +2409,14 @@ def _type_check_params(param_dict: dict[str, Any], element_type: str) -> dict[st
 
     norm = param_dict.get("norm")
     if norm is not None:
-        if element_type in {"images", "labels"} and not isinstance(norm, Normalize):
-            raise TypeError("Parameter 'norm' must be of type Normalize.")
+        if element_type in {"images", "labels"}:
+            if isinstance(norm, list):
+                if not norm:
+                    raise ValueError("Parameter 'norm' list must not be empty.")
+                if not all(isinstance(n, Normalize) for n in norm):
+                    raise TypeError("Every item in 'norm' list must be a Normalize instance.")
+            elif not isinstance(norm, Normalize):
+                raise TypeError("Parameter 'norm' must be a Normalize or a list of Normalize instances.")
         if element_type in {"shapes", "points"} and not isinstance(norm, bool | Normalize):
             raise TypeError("Parameter 'norm' must be a boolean or a mpl.Normalize.")
 

tests/pl/test_render_images.py

@@ -416,3 +416,60 @@ def test_no_clipping_warning_palette_compositing(self):
             plt.close("all")
             clip_warns = [x for x in w if "Clipping input data" in str(x.message)]
             assert len(clip_warns) == 0, f"Got unexpected clipping warning: {clip_warns[0].message}"
+
+
+def _make_multichannel_sdata():
+    """Create a 3-channel image with different intensity ranges."""
+    rng = np.random.default_rng(42)
+    data = np.stack(
+        [
+            rng.uniform(0, 0.05, (50, 50)),  # dim
+            rng.uniform(0, 1.0, (50, 50)),  # full range
+            rng.uniform(0, 0.5, (50, 50)),  # medium
+        ],
+        axis=0,
+    ).astype(np.float32)
+    img = Image2DModel.parse(data, dims=("c", "y", "x"), c_coords=[0, 1, 2])
+    return SpatialData(images={"img": img})
+
+
+def test_per_channel_norm_list():
+    """Per-channel norm list is accepted and renders without error (#460)."""
+    sdata = _make_multichannel_sdata()
+    norms = [
+        Normalize(vmin=0, vmax=0.05, clip=True),
+        Normalize(vmin=0, vmax=1.0, clip=True),
+        Normalize(vmin=0, vmax=0.5, clip=True),
+    ]
+    fig, ax = plt.subplots()
+    sdata.pl.render_images("img", channel=[0, 1, 2], norm=norms, cmap=[plt.cm.gray] * 3).pl.show(ax=ax)
+    plt.close(fig)
+
+
+def test_single_norm_with_multiple_channels():
+    """A single Normalize shared across channels still works."""
+    sdata = _make_multichannel_sdata()
+    fig, ax = plt.subplots()
+    sdata.pl.render_images("img", channel=[0, 1, 2], norm=Normalize(0, 1), cmap=[plt.cm.gray] * 3).pl.show(ax=ax)
+    plt.close(fig)
+
+
+def test_norm_list_length_mismatch_raises():
+    """Norm list length must match cmap list length."""
+    sdata = _make_multichannel_sdata()
+    with pytest.raises(ValueError, match="must match"):
+        sdata.pl.render_images("img", channel=[0, 1, 2], norm=[Normalize(0, 1)] * 2, cmap=[plt.cm.gray] * 3).pl.show()
+
+
+def test_norm_list_empty_raises():
+    """Empty norm list is rejected."""
+    sdata = _make_multichannel_sdata()
+    with pytest.raises(ValueError, match="must not be empty"):
+        sdata.pl.render_images("img", norm=[]).pl.show()
+
+
+def test_norm_list_with_invalid_element_raises():
+    """Non-Normalize items in norm list are rejected."""
+    sdata = _make_multichannel_sdata()
+    with pytest.raises(TypeError, match="Normalize instance"):
+        sdata.pl.render_images("img", norm=["not_a_norm"]).pl.show()