refactor(render): single continuous-norm feeds pixels and colorbar (#699)

PR2 of the #699 color/cmap/norm unification. Consolidates the duplicated
"resolve vmin/vmax then map" logic and makes the colorbar derive from the SAME
norm as the pixels, so the two are guaranteed to agree instead of being two
independent computations that happened to match.

Root cause of the latent mismatch: shapes fill is a facecolor-baked
PatchCollection and labels are pre-baked RGB, so matplotlib never maps their
norm — the colorbar range was derived by a separate path (set_clim /
_append_outline_colorbar / the labels imshow norm relying on _map_color_seg
autoscaling the shared norm in place).

- Add `_resolve_continuous_norm(values, cmap_params)`: one pure resolver
  (honor explicit vmin/vmax, else finite data range, else [0, 1]). Every
  pixel-baking site and its matching colorbar site calls it with the SAME
  value vector, so they cannot diverge.
- Fold the 4 duplicated inline norm blocks (`_color_vector_to_rgba` x2,
  `_get_collection_shape` x2) into it; drop the now-dead `norm` param of
  `_get_collection_shape`.
- Labels: `_map_color_seg` resolves the norm instead of mutating the shared
  one; the labels imshow is fed the same resolved norm so its colorbar matches
  without the in-place-autoscale side effect.
- Datashader, image, points and graph paths are unchanged (set_array /
  reduction bounds — they already share their norm).

Behavior-preserving for normal renders: both old paths already reduced the same
vector to nanmin/nanmax. The resolver adds no vmin==vmax expansion of its own
(matplotlib already expands a degenerate clim by ±0.5 downstream, so the bar is
unchanged; degenerate pixels stay cmap(0) as before). The only edge that
unifies is an all-identical-value outline column, which previously used a
[0, 1] guard — an extreme corner now consistent with the fill path.

Adds unit tests for `_resolve_continuous_norm` and a non-visual integration
test asserting the fill colorbar clim equals the resolved pixel range.

Author: timtreis

src/spatialdata_plot/pl/render.py

@@ -70,7 +70,6 @@
     _get_linear_colormap,
     _hex_no_alpha,
     _join_table_for_element,
-    _make_continuous_mappable,
     _map_color_seg,
     _maybe_set_colors,
     _mpl_ax_contains_elements,
@@ -80,6 +79,7 @@
     _prepare_transformation,
     _rasterize_if_necessary,
     _rasterize_if_necessary_datashader,
+    _resolve_continuous_norm,
     _set_color_source_vec,
     _stream_label_centroid_stats,
     _validate_polygons,
@@ -510,21 +510,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, so the two agree (#699).
     """
     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,
@@ -963,7 +959,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,
@@ -982,7 +977,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(),
@@ -1003,7 +997,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(),
@@ -1025,7 +1018,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,
@@ -1038,25 +1030,11 @@ 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)
+        # Derive the colorbar range from the SAME resolved norm the fill pixels use, so the bar
+        # can't disagree with the rendered shapes (#699). (matplotlib path; no-op for the
+        # datashader image, whose colorbar is built separately from the reduction bounds.)
+        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,
@@ -2460,11 +2438,14 @@ def _draw_labels(
             outline_color_source_vector=outline_color_source_vector if seg_boundaries else None,
         )
 
+        # `labels` is pre-baked RGB, so imshow ignores cmap/norm for pixels — they exist only to
+        # drive the colorbar. Feed it the SAME resolved norm `_map_color_seg` used for the pixels
+        # so the bar matches, instead of relying on an in-place autoscale of the shared norm (#699).
         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/utils.py

@@ -497,6 +497,32 @@ 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 (#699).
+
+    Single source of truth so the rendered pixels and the colorbar derive the SAME
+    ``vmin``/``vmax`` from the SAME values — call it with the same value vector for both
+    and they cannot disagree. Honors explicit ``cmap_params.norm`` vmin/vmax; otherwise
+    uses the finite-value data range, falling back to ``[0, 1]`` when no finite values
+    exist. Behavior-preserving: this reproduces the data range the existing pixel path
+    already used (no special-casing of ``vmin == vmax``).
+    """
+    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(pd.Series(arr.ravel()), errors="coerce").to_numpy()
+        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,
@@ -577,15 +603,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
 
@@ -594,15 +612,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():
@@ -697,7 +707,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,
@@ -745,23 +754,12 @@ 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. The norm is resolved
+        # from the same values the colorbar uses, so pixels and colorbar agree (#699).
         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:
@@ -776,14 +774,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
@@ -1531,9 +1522,12 @@ def _map_color_seg(
         # Case B: user wants to plot a continous column
         if isinstance(color_vector, pd.Series):
             color_vector = color_vector.to_numpy()
-        # normalize only the not nan values, else the whole array would contain only nan values
+        # normalize only the not nan values, else the whole array would contain only nan values.
+        # Resolve the norm from the same values the colorbar uses so the two agree without relying
+        # on a shared-norm autoscale side effect (#699).
         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)
@@ -1558,7 +1552,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
@@ -1592,7 +1587,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:

tests/pl/test_render_shapes.py

@@ -1780,3 +1780,33 @@ def test_render_shapes_as_points_default_is_matplotlib(sdata_blobs: SpatialData)
     sdata_blobs.pl.render_shapes("blobs_circles", as_points=True, size=50).pl.show(ax=ax)
     assert len(ax.collections) == 1 and len(ax.images) == 0
     plt.close(fig)
+
+
+def _shapes_sdata_with_values(values: list[float]) -> SpatialData:
+    """A shapes element + annotating table carrying a continuous column ``val``."""
+    n = len(values)
+    polys = [Polygon([(i, 0.0), (i, 1.0), (i + 1, 1.0), (i + 1, 0.0)]) for i in range(n)]
+    geo = gpd.GeoDataFrame(geometry=gpd.GeoSeries(polys))
+    sdata = SpatialData(shapes={"p": ShapesModel.parse(geo)})
+    adata = AnnData(pd.DataFrame({"p": [str(i) for i in range(n)]}))
+    adata.obs["region"] = "p"
+    adata.obs["instance_id"] = list(range(n))
+    adata.obs["val"] = list(values)
+    sdata["table"] = TableModel.parse(adata, region="p", region_key="region", instance_key="instance_id")
+    return sdata
+
+
+def _fill_collection_clim(values: list[float]) -> tuple[float, float]:
+    from matplotlib.collections import PatchCollection
+
+    fig, ax = plt.subplots()
+    _shapes_sdata_with_values(values).pl.render_shapes(color="val").pl.show(ax=ax)
+    clims = [c.get_clim() for c in ax.collections if isinstance(c, PatchCollection)]
+    plt.close(fig)
+    assert len(clims) == 1
+    return clims[0]
+
+
+def test_continuous_fill_colorbar_matches_pixel_range():
+    """#699: the fill colorbar clim is the resolved data range, so the bar matches the shapes."""
+    assert _fill_collection_clim([0.0, 1.0, 2.0, 3.0]) == (0.0, 3.0)

tests/pl/test_utils.py

@@ -851,3 +851,57 @@ def test_cmap_with_alpha_bad_color_uses_na_with_requested_alpha(self):
         np.testing.assert_allclose(bad[:3], to_rgba(na.get_hex_with_alpha())[:3], atol=1e-6)
         # historical `_lut[:, -1] = alpha` overwrote the bad-row alpha too
         assert bad[3] == 0.25
+
+
+class TestResolveContinuousNorm:
+    """Unit tests for `_resolve_continuous_norm` — the single norm source feeding pixels + colorbar (#699)."""
+
+    @staticmethod
+    def _params(vmin: float | None = None, vmax: float | None = None) -> CmapParams:
+        from matplotlib import colormaps
+        from matplotlib.colors import Normalize
+
+        return CmapParams(cmap=colormaps["viridis"], norm=Normalize(vmin=vmin, vmax=vmax, clip=False), na_color=Color())
+
+    def test_honors_explicit_vmin_vmax(self):
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        norm = _resolve_continuous_norm(np.array([0.0, 100.0]), self._params(vmin=10.0, vmax=20.0))
+        assert (norm.vmin, norm.vmax) == (10.0, 20.0)
+
+    def test_derives_data_range_ignoring_nan_and_inf(self):
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        norm = _resolve_continuous_norm(np.array([1.0, np.nan, 5.0, np.inf, -np.inf]), self._params())
+        assert (norm.vmin, norm.vmax) == (1.0, 5.0)
+
+    def test_all_nan_falls_back_to_unit_range(self):
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        norm = _resolve_continuous_norm(np.array([np.nan, np.nan]), self._params())
+        assert (norm.vmin, norm.vmax) == (0.0, 1.0)
+
+    def test_degenerate_range_is_not_expanded(self):
+        # behavior-preserving: a single distinct value stays degenerate (no invented +/-0.5)
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        norm = _resolve_continuous_norm(np.array([5.0, 5.0, 5.0]), self._params())
+        assert (norm.vmin, norm.vmax) == (5.0, 5.0)
+
+    def test_object_dtype_coerces_color_strings_to_nan(self):
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        norm = _resolve_continuous_norm(np.array([1.0, "red", 9.0], dtype=object), self._params())
+        assert (norm.vmin, norm.vmax) == (1.0, 9.0)
+
+    def test_same_values_give_identical_norm_and_never_mutate_shared(self):
+        # the core #699 invariant: pixels and colorbar call this with the same vector -> same result,
+        # and the shared CmapParams.norm is never autoscaled in place.
+        from spatialdata_plot.pl.utils import _resolve_continuous_norm
+
+        params = self._params()
+        vals = np.array([2.0, 7.0, np.nan, 4.0])
+        a = _resolve_continuous_norm(vals, params)
+        b = _resolve_continuous_norm(vals, params)
+        assert (a.vmin, a.vmax) == (b.vmin, b.vmax) == (2.0, 7.0)
+        assert params.norm.vmin is None and params.norm.vmax is None