refactor(render): unify color/cmap/norm pipeline — CmapParams methods + single continuous-norm (#699)

PRs 1+2 of #699, rebased onto the post-#715 (utils split) / post-#720 main.
PR3 (image-composite helper) deferred.

CmapParams gains behavior:
- fresh_norm(): a safe per-element copy (applying a Normalize autoscales vmin/vmax
  in place, leaking one element's range into the next). Converts the 3 copy(norm)
  sites in render.py.
- cmap_with_alpha() / colormap_with_alpha(): public-API replacement for the private
  cmap._lut[:, -1] = alpha poke in the 1-channel image path; byte-identical body
  colors, no shared-cmap mutation.

Single continuous-norm feeds pixels and colorbar:
- _resolve_continuous_norm(values, cmap_params) in _color.py: one resolver called by
  each pixel-baking site and its matching colorbar site with the same vector, so they
  cannot diverge. Folds the duplicated inline norm blocks in _color_vector_to_rgba and
  _get_collection_shape (now in _geometry.py; its dead `norm` param dropped) and routes
  _map_color_seg + the labels imshow + _append_outline_colorbar + the shapes set_clim
  through it.
- Datashader / image / points / graph paths unchanged (already share their norm).

Behavior-preserving for normal renders; the only unified edge is an all-identical-value
outline column. Adds unit tests for the new CmapParams methods and _resolve_continuous_norm
plus a non-visual colorbar-clim integration test.

Author: timtreis

src/spatialdata_plot/pl/_color.py

@@ -109,6 +109,29 @@ def _make_continuous_mappable(vmin: float, vmax: float, cmap: Any) -> ScalarMapp
     return ScalarMappable(norm=Normalize(vmin=vmin, vmax=vmax), cmap=cmap)
 
 
+def _resolve_continuous_norm(values: Any, cmap_params: CmapParams) -> Normalize:
+    """Resolve a concrete ``Normalize`` for continuous coloring.
+
+    Honor explicit ``norm`` vmin/vmax, else the finite-value data range of ``values``, else
+    ``[0, 1]``. Shared by the pixel and colorbar sites so both derive the same range. A degenerate
+    ``vmin == vmax`` is left as-is (matplotlib expands it downstream), not reset to ``[0, 1]``.
+    """
+    base = cmap_params.norm
+    vmin, vmax = base.vmin, base.vmax
+    if vmin is None or vmax is None:
+        arr = np.asarray(values)
+        if not np.issubdtype(arr.dtype, np.number):
+            arr = pd.to_numeric(arr.ravel(), errors="coerce")
+        finite = np.isfinite(arr)
+        data_min = float(np.nanmin(arr[finite])) if finite.any() else 0.0
+        data_max = float(np.nanmax(arr[finite])) if finite.any() else 1.0
+        if vmin is None:
+            vmin = data_min
+        if vmax is None:
+            vmax = data_max
+    return Normalize(vmin=vmin, vmax=vmax, clip=base.clip)
+
+
 def _apply_mask_to_outline_vectors(
     outline_color_vector: Any,
     outline_color_source_vector: pd.Series | None,
@@ -189,15 +212,7 @@ def _color_vector_to_rgba(
     if np.issubdtype(arr.dtype, np.number):
         finite_mask = np.isfinite(arr)
         if finite_mask.any():
-            norm = cmap_params.norm
-            if norm.vmin is None or norm.vmax is None:
-                vmin = float(np.nanmin(arr[finite_mask]))
-                vmax = float(np.nanmax(arr[finite_mask]))
-                if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
-                    vmin, vmax = 0.0, 1.0
-                used_norm = Normalize(vmin=vmin, vmax=vmax, clip=False)
-            else:
-                used_norm = norm
+            used_norm = _resolve_continuous_norm(arr, cmap_params)
             rgba[finite_mask] = cmap_params.cmap(used_norm(arr[finite_mask]))
         return rgba
 
@@ -206,15 +221,7 @@ def _color_vector_to_rgba(
     num = pd.to_numeric(series, errors="coerce").to_numpy()
     is_num = np.isfinite(num)
     if is_num.any():
-        norm = cmap_params.norm
-        if norm.vmin is None or norm.vmax is None:
-            vmin = float(np.nanmin(num[is_num]))
-            vmax = float(np.nanmax(num[is_num]))
-            if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
-                vmin, vmax = 0.0, 1.0
-            used_norm = Normalize(vmin=vmin, vmax=vmax, clip=False)
-        else:
-            used_norm = norm
+        used_norm = _resolve_continuous_norm(num, cmap_params)
         rgba[is_num] = cmap_params.cmap(used_norm(num[is_num]))
     color_mask = (~is_num) & series.notna().to_numpy()
     if color_mask.any():
@@ -754,7 +761,8 @@ def _map_color_seg(
             color_vector = color_vector.to_numpy()
         # normalize only the not nan values, else the whole array would contain only nan values
         normed_color_vector = color_vector.copy().astype(float)
-        normed_color_vector[~np.isnan(normed_color_vector)] = cmap_params.norm(
+        used_norm = _resolve_continuous_norm(normed_color_vector, cmap_params)
+        normed_color_vector[~np.isnan(normed_color_vector)] = used_norm(
             normed_color_vector[~np.isnan(normed_color_vector)]
         )
         cols = cmap_params.cmap(normed_color_vector)
@@ -779,7 +787,8 @@ def _map_color_seg(
                 assert all(_is_color_like(c) for c in color_vector), "Not all values are color-like."
                 cols = colors.to_rgba_array(color_vector)
             else:
-                cols = cmap_params.cmap(cmap_params.norm(color_vector))
+                used_norm = _resolve_continuous_norm(color_vector, cmap_params)
+                cols = cmap_params.cmap(used_norm(color_vector))
 
     if seg_erosionpx is not None:
         val_im[val_im == erosion(val_im, footprint_rectangle((seg_erosionpx, seg_erosionpx)))] = 0
@@ -813,7 +822,7 @@ def _map_color_seg(
             normed = ov.copy().astype(float)
             finite = ~np.isnan(normed)
             if finite.any():
-                normed[finite] = cmap_params.norm(normed[finite])
+                normed[finite] = _resolve_continuous_norm(ov, cmap_params)(normed[finite])
             outline_cols = cmap_params.cmap(normed)
             outline_val_im = map_array(seg, cell_id, cell_id)
         if seg_erosionpx is not None:

src/spatialdata_plot/pl/_datashader.py

@@ -5,7 +5,6 @@
 
 from __future__ import annotations
 
-from copy import copy
 from typing import Any, Literal
 
 import dask
@@ -588,7 +587,7 @@ def _render_ds_outline_by_column(
         )
         # Apply the user-provided norm (vmin/vmax) the same way the fill path does so
         # an explicit Normalize takes effect for the outline cmap.
-        norm = copy(cmap_params.norm)
+        norm = cmap_params.fresh_norm()
         agg_outline, color_span = _apply_ds_norm(agg_outline, norm)
         shaded = ds.tf.shade(
             agg_outline,

src/spatialdata_plot/pl/_geometry.py

@@ -13,11 +13,12 @@
 from geopandas import GeoDataFrame
 from matplotlib import colors
 from matplotlib.collections import PatchCollection
-from matplotlib.colors import ColorConverter, Normalize
+from matplotlib.colors import ColorConverter
 from scipy.spatial import ConvexHull
 from shapely.errors import GEOSException
 
 from spatialdata_plot._logging import logger
+from spatialdata_plot.pl._color import _resolve_continuous_norm
 from spatialdata_plot.pl.render_params import ShapesRenderParams
 from spatialdata_plot.pl.utils import _extract_scalar_value
 
@@ -167,7 +168,6 @@ def _get_collection_shape(
     shapes: list[GeoDataFrame],
     c: Any,
     s: float,
-    norm: Any,
     render_params: ShapesRenderParams,
     fill_alpha: None | float = None,
     outline_alpha: None | float = None,
@@ -215,23 +215,11 @@ def _as_rgba_array(x: Any) -> np.ndarray:
     elif c_arr.ndim == 1 and len(c_arr) == len(shapes) and np.issubdtype(c_arr.dtype, np.number):
         finite_mask = np.isfinite(c_arr)
 
-        # Select or build a normalization that ignores NaNs for scaling
-        if isinstance(norm, Normalize):
-            used_norm: Normalize = norm
-        else:
-            if finite_mask.any():
-                vmin = float(np.nanmin(c_arr[finite_mask]))
-                vmax = float(np.nanmax(c_arr[finite_mask]))
-                if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
-                    vmin, vmax = 0.0, 1.0
-            else:
-                vmin, vmax = 0.0, 1.0
-            used_norm = colors.Normalize(vmin=vmin, vmax=vmax, clip=False)
-
-        # Map finite values through cmap(norm(.)); NaNs get na_color
+        # Map finite values through cmap(norm(.)); NaNs get na_color.
         fill_c = np.empty((len(c_arr), 4), dtype=float)
         fill_c[:] = na_rgba
         if finite_mask.any():
+            used_norm = _resolve_continuous_norm(c_arr, render_params.cmap_params)
             fill_c[finite_mask] = cmap(used_norm(c_arr[finite_mask]))
 
     elif c_arr.ndim == 1 and len(c_arr) == len(shapes) and c_arr.dtype == object:
@@ -246,14 +234,7 @@ def _as_rgba_array(x: Any) -> np.ndarray:
 
         # numeric entries via cmap(norm)
         if is_num.any():
-            if isinstance(norm, Normalize):
-                used_norm = norm
-            else:
-                vmin = float(np.nanmin(num[is_num])) if is_num.any() else 0.0
-                vmax = float(np.nanmax(num[is_num])) if is_num.any() else 1.0
-                if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
-                    vmin, vmax = 0.0, 1.0
-                used_norm = colors.Normalize(vmin=vmin, vmax=vmax, clip=False)
+            used_norm = _resolve_continuous_norm(num, render_params.cmap_params)
             fill_c[is_num] = cmap(used_norm(num[is_num]))
 
         # non-numeric, non-NaN entries as explicit colors

src/spatialdata_plot/pl/render.py

@@ -38,10 +38,10 @@
     _color_vector_to_rgba,
     _get_colors_for_categorical_obs,
     _get_linear_colormap,
-    _make_continuous_mappable,
     _map_color_seg,
     _maybe_set_colors,
     _prepare_cmap_norm,
+    _resolve_continuous_norm,
     _set_color_source_vec,
 )
 from spatialdata_plot.pl._datashader import (
@@ -77,6 +77,7 @@
     PointsRenderParams,
     ShapesRenderParams,
     _DsReduction,
+    colormap_with_alpha,
 )
 from spatialdata_plot.pl.utils import (
     _decorate_axs,
@@ -515,21 +516,17 @@ def _append_outline_colorbar(
 ) -> None:
     """Append a `ColorbarSpec` for a continuous outline column.
 
-    No-op when ``outline_color_vector`` has no finite values. Honors user-supplied
-    `vmin`/`vmax` on ``cmap_params.norm``; falls back to data range. Mirrors the
-    `vmin == vmax` ±0.5 expansion used by the fill colorbar.
+    No-op when ``outline_color_vector`` has no finite values; derives the bar from the same resolved
+    norm the outline pixels use.
     """
     arr = pd.to_numeric(pd.Series(np.asarray(outline_color_vector)), errors="coerce").to_numpy()
-    finite = np.isfinite(arr)
-    if not finite.any():
+    if not np.isfinite(arr).any():
         return
-    norm = cmap_params.norm
-    vmin = norm.vmin if norm.vmin is not None else float(np.nanmin(arr[finite]))
-    vmax = norm.vmax if norm.vmax is not None else float(np.nanmax(arr[finite]))
+    used_norm = _resolve_continuous_norm(outline_color_vector, cmap_params)
     colorbar_requests.append(
         ColorbarSpec(
             ax=ax,
-            mappable=_make_continuous_mappable(vmin, vmax, cmap_params.cmap),
+            mappable=ScalarMappable(norm=used_norm, cmap=cmap_params.cmap),
             params=colorbar_params,
             label=outline_col,
             alpha=alpha,
@@ -747,7 +744,7 @@ def _render_shapes(
 
     color_vector = _maybe_apply_transfunc(color_source_vector, color_vector, render_params.transfunc)
 
-    norm = copy(render_params.cmap_params.norm)
+    norm = render_params.cmap_params.fresh_norm()
 
     if len(color_vector) == 0:
         color_vector = [render_params.cmap_params.na_color.get_hex_with_alpha()]
@@ -968,7 +965,6 @@ def _render_shapes(
                 render_params=render_params,
                 rasterized=sc_settings._vector_friendly,
                 cmap=None,
-                norm=None,
                 fill_alpha=0.0,
                 outline_alpha=render_params.outline_alpha[0],
                 outline_color=outline_rgba,
@@ -987,7 +983,6 @@ def _render_shapes(
                 render_params=render_params,
                 rasterized=sc_settings._vector_friendly,
                 cmap=None,
-                norm=None,
                 fill_alpha=0.0,
                 outline_alpha=render_params.outline_alpha[0],
                 outline_color=render_params.outline_params.outer_outline_color.get_hex(),
@@ -1008,7 +1003,6 @@ def _render_shapes(
                 render_params=render_params,
                 rasterized=sc_settings._vector_friendly,
                 cmap=None,
-                norm=None,
                 fill_alpha=0.0,
                 outline_alpha=render_params.outline_alpha[1],
                 outline_color=render_params.outline_params.inner_outline_color.get_hex(),
@@ -1030,7 +1024,6 @@ def _render_shapes(
             render_params=render_params,
             rasterized=sc_settings._vector_friendly,
             cmap=render_params.cmap_params.cmap,
-            norm=norm,
             fill_alpha=render_params.fill_alpha,
             outline_alpha=0.0,
             zorder=render_params.zorder,
@@ -1043,25 +1036,9 @@ def _render_shapes(
             path.vertices = trans.transform(path.vertices)
 
     if not values_are_categorical:
-        # Respect explicit vmin/vmax; otherwise derive from finite numeric values, falling back to [0, 1] if unavailable
-        vmin = render_params.cmap_params.norm.vmin
-        vmax = render_params.cmap_params.norm.vmax
-        if vmin is None or vmax is None:
-            numeric_values = pd.to_numeric(np.asarray(color_vector), errors="coerce")
-            finite_mask = np.isfinite(numeric_values)
-            if finite_mask.any():
-                data_min = float(np.nanmin(numeric_values[finite_mask]))
-                data_max = float(np.nanmax(numeric_values[finite_mask]))
-                if vmin is None:
-                    vmin = data_min
-                if vmax is None:
-                    vmax = data_max
-            else:
-                if vmin is None:
-                    vmin = 0.0
-                if vmax is None:
-                    vmax = 1.0
-        _cax.set_clim(vmin=vmin, vmax=vmax)
+        # Colorbar range from the same resolved norm the fill pixels use.
+        used_norm = _resolve_continuous_norm(color_vector, render_params.cmap_params)
+        _cax.set_clim(vmin=used_norm.vmin, vmax=used_norm.vmax)
 
     _add_legend_and_colorbar(
         ax=ax,
@@ -1511,7 +1488,7 @@ def _render_points(
 
     trans, trans_data = _prepare_transformation(sdata.points[element], coordinate_system, ax)
 
-    norm = copy(render_params.cmap_params.norm)
+    norm = render_params.cmap_params.fresh_norm()
 
     method = render_params.method
 
@@ -1972,9 +1949,8 @@ def _render_images(
             else render_params.cmap_params.cmap
         )
 
-        # Overwrite alpha in cmap: https://stackoverflow.com/a/10127675
-        cmap._init()
-        cmap._lut[:, -1] = render_params.alpha
+        # Bake a uniform alpha into a fresh cmap (no shared-cmap mutation).
+        cmap = colormap_with_alpha(cmap, render_params.alpha, render_params.cmap_params.na_color.get_hex_with_alpha())
 
         # norm needs to be passed directly to ax.imshow(). If we normalize before, that method would always clip.
         _ax_show_and_transform(
@@ -2432,7 +2408,7 @@ def _render_labels(
             y=xy[:, 1],
             color_vector=point_color_vector,
             color_source_vector=point_color_source_vector,
-            norm=copy(render_params.cmap_params.norm),  # ax.scatter autoscales in place; don't mutate the shared norm
+            norm=render_params.cmap_params.fresh_norm(),  # ax.scatter autoscales in place; don't mutate the shared norm
             na_color=na_color,
             adata=table if table_name is not None else None,
             col_for_color=col_for_color,
@@ -2465,11 +2441,12 @@ def _draw_labels(
             outline_color_source_vector=outline_color_source_vector if seg_boundaries else None,
         )
 
+        # labels is pre-baked RGB; cmap/norm only drive the colorbar, so feed the same resolved norm.
         cax = ax.imshow(
             labels,
             rasterized=True,
             cmap=None if categorical else render_params.cmap_params.cmap,
-            norm=None if categorical else render_params.cmap_params.norm,
+            norm=None if categorical else _resolve_continuous_norm(color_vector, render_params.cmap_params),
             alpha=alpha,
             origin="lower",
             zorder=render_params.zorder,

src/spatialdata_plot/pl/render_params.py

@@ -1,13 +1,14 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Mapping, Sequence
+from copy import copy
 from dataclasses import dataclass, field
 from typing import Any, Literal
 
 import numpy as np
 from matplotlib.axes import Axes
 from matplotlib.cm import ScalarMappable
-from matplotlib.colors import Colormap, ListedColormap, Normalize, rgb2hex, to_hex
+from matplotlib.colors import Colormap, ListedColormap, Normalize, rgb2hex, to_hex, to_rgba
 from matplotlib.figure import Figure
 
 _FontWeight = Literal["light", "normal", "medium", "semibold", "bold", "heavy", "black"]
@@ -148,6 +149,23 @@ def is_fully_transparent(self) -> bool:
         return self.alpha == "00"
 
 
+def colormap_with_alpha(cmap: Colormap, alpha: float, na_color: str) -> Colormap:
+    """Return ``cmap`` rebuilt with a uniform ``alpha`` and ``na_color`` as the bad/NaN color.
+
+    Resampling at ``linspace(0, 1, N)`` is lossless (matplotlib quantizes ``__call__`` into ``N`` bins).
+    """
+    lut = cmap(np.linspace(0, 1, cmap.N))
+    lut[:, -1] = alpha
+    new = ListedColormap(lut, name=cmap.name)
+    # Apply alpha to under/over too, matching the old ``_lut[:, -1] = alpha`` (which hit every row).
+    new.set_extremes(
+        bad=[*to_rgba(na_color)[:3], alpha],
+        under=[*cmap.get_under()[:3], alpha],
+        over=[*cmap.get_over()[:3], alpha],
+    )
+    return new
+
+
 @dataclass
 class CmapParams:
     """Cmap params."""
@@ -157,6 +175,14 @@ class CmapParams:
     na_color: Color
     cmap_is_default: bool = True
 
+    def fresh_norm(self) -> Normalize:
+        """Return a copy of ``norm`` safe to apply/autoscale without mutating the shared one.
+
+        ``Normalize.__call__`` autoscales ``vmin``/``vmax`` in place when unset, which would leak one
+        element's data range into later elements that reuse the same ``CmapParams``.
+        """
+        return copy(self.norm)
+
 
 @dataclass
 class FigParams: