Skip to content

Commit 9995c6f

Browse files
committed
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.
1 parent bfda2ed commit 9995c6f

7 files changed

Lines changed: 223 additions & 90 deletions

File tree

‎src/spatialdata_plot/pl/_color.py‎

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,32 @@ def _make_continuous_mappable(vmin: float, vmax: float, cmap: Any) -> ScalarMapp
109109
return ScalarMappable(norm=Normalize(vmin=vmin, vmax=vmax), cmap=cmap)
110110

111111

112+
def _resolve_continuous_norm(values: Any, cmap_params: CmapParams) -> Normalize:
113+
"""Resolve a concrete ``Normalize`` for continuous coloring (#699).
114+
115+
Single source of truth so the rendered pixels and the colorbar derive the SAME
116+
``vmin``/``vmax`` from the SAME values — call it with the same value vector for both
117+
and they cannot disagree. Honors explicit ``cmap_params.norm`` vmin/vmax; otherwise
118+
uses the finite-value data range, falling back to ``[0, 1]`` when no finite values
119+
exist. Behavior-preserving: this reproduces the data range the existing pixel path
120+
already used (no special-casing of ``vmin == vmax``).
121+
"""
122+
base = cmap_params.norm
123+
vmin, vmax = base.vmin, base.vmax
124+
if vmin is None or vmax is None:
125+
arr = np.asarray(values)
126+
if not np.issubdtype(arr.dtype, np.number):
127+
arr = pd.to_numeric(pd.Series(arr.ravel()), errors="coerce").to_numpy()
128+
finite = np.isfinite(arr)
129+
data_min = float(np.nanmin(arr[finite])) if finite.any() else 0.0
130+
data_max = float(np.nanmax(arr[finite])) if finite.any() else 1.0
131+
if vmin is None:
132+
vmin = data_min
133+
if vmax is None:
134+
vmax = data_max
135+
return Normalize(vmin=vmin, vmax=vmax, clip=base.clip)
136+
137+
112138
def _apply_mask_to_outline_vectors(
113139
outline_color_vector: Any,
114140
outline_color_source_vector: pd.Series | None,
@@ -189,15 +215,7 @@ def _color_vector_to_rgba(
189215
if np.issubdtype(arr.dtype, np.number):
190216
finite_mask = np.isfinite(arr)
191217
if finite_mask.any():
192-
norm = cmap_params.norm
193-
if norm.vmin is None or norm.vmax is None:
194-
vmin = float(np.nanmin(arr[finite_mask]))
195-
vmax = float(np.nanmax(arr[finite_mask]))
196-
if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
197-
vmin, vmax = 0.0, 1.0
198-
used_norm = Normalize(vmin=vmin, vmax=vmax, clip=False)
199-
else:
200-
used_norm = norm
218+
used_norm = _resolve_continuous_norm(arr, cmap_params)
201219
rgba[finite_mask] = cmap_params.cmap(used_norm(arr[finite_mask]))
202220
return rgba
203221

@@ -206,15 +224,7 @@ def _color_vector_to_rgba(
206224
num = pd.to_numeric(series, errors="coerce").to_numpy()
207225
is_num = np.isfinite(num)
208226
if is_num.any():
209-
norm = cmap_params.norm
210-
if norm.vmin is None or norm.vmax is None:
211-
vmin = float(np.nanmin(num[is_num]))
212-
vmax = float(np.nanmax(num[is_num]))
213-
if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
214-
vmin, vmax = 0.0, 1.0
215-
used_norm = Normalize(vmin=vmin, vmax=vmax, clip=False)
216-
else:
217-
used_norm = norm
227+
used_norm = _resolve_continuous_norm(num, cmap_params)
218228
rgba[is_num] = cmap_params.cmap(used_norm(num[is_num]))
219229
color_mask = (~is_num) & series.notna().to_numpy()
220230
if color_mask.any():
@@ -752,9 +762,12 @@ def _map_color_seg(
752762
# Case B: user wants to plot a continous column
753763
if isinstance(color_vector, pd.Series):
754764
color_vector = color_vector.to_numpy()
755-
# normalize only the not nan values, else the whole array would contain only nan values
765+
# normalize only the not nan values, else the whole array would contain only nan values.
766+
# Resolve the norm from the same values the colorbar uses so the two agree without relying
767+
# on a shared-norm autoscale side effect (#699).
756768
normed_color_vector = color_vector.copy().astype(float)
757-
normed_color_vector[~np.isnan(normed_color_vector)] = cmap_params.norm(
769+
used_norm = _resolve_continuous_norm(normed_color_vector, cmap_params)
770+
normed_color_vector[~np.isnan(normed_color_vector)] = used_norm(
758771
normed_color_vector[~np.isnan(normed_color_vector)]
759772
)
760773
cols = cmap_params.cmap(normed_color_vector)
@@ -779,7 +792,8 @@ def _map_color_seg(
779792
assert all(_is_color_like(c) for c in color_vector), "Not all values are color-like."
780793
cols = colors.to_rgba_array(color_vector)
781794
else:
782-
cols = cmap_params.cmap(cmap_params.norm(color_vector))
795+
used_norm = _resolve_continuous_norm(color_vector, cmap_params)
796+
cols = cmap_params.cmap(used_norm(color_vector))
783797

784798
if seg_erosionpx is not None:
785799
val_im[val_im == erosion(val_im, footprint_rectangle((seg_erosionpx, seg_erosionpx)))] = 0
@@ -813,7 +827,7 @@ def _map_color_seg(
813827
normed = ov.copy().astype(float)
814828
finite = ~np.isnan(normed)
815829
if finite.any():
816-
normed[finite] = cmap_params.norm(normed[finite])
830+
normed[finite] = _resolve_continuous_norm(ov, cmap_params)(normed[finite])
817831
outline_cols = cmap_params.cmap(normed)
818832
outline_val_im = map_array(seg, cell_id, cell_id)
819833
if seg_erosionpx is not None:

‎src/spatialdata_plot/pl/_datashader.py‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55

66
from __future__ import annotations
77

8-
from copy import copy
98
from typing import Any, Literal
109

1110
import dask
@@ -588,7 +587,7 @@ def _render_ds_outline_by_column(
588587
)
589588
# Apply the user-provided norm (vmin/vmax) the same way the fill path does so
590589
# an explicit Normalize takes effect for the outline cmap.
591-
norm = copy(cmap_params.norm)
590+
norm = cmap_params.fresh_norm()
592591
agg_outline, color_span = _apply_ds_norm(agg_outline, norm)
593592
shaded = ds.tf.shade(
594593
agg_outline,

‎src/spatialdata_plot/pl/_geometry.py‎

Lines changed: 6 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,12 @@
1313
from geopandas import GeoDataFrame
1414
from matplotlib import colors
1515
from matplotlib.collections import PatchCollection
16-
from matplotlib.colors import ColorConverter, Normalize
16+
from matplotlib.colors import ColorConverter
1717
from scipy.spatial import ConvexHull
1818
from shapely.errors import GEOSException
1919

2020
from spatialdata_plot._logging import logger
21+
from spatialdata_plot.pl._color import _resolve_continuous_norm
2122
from spatialdata_plot.pl.render_params import ShapesRenderParams
2223
from spatialdata_plot.pl.utils import _extract_scalar_value
2324

@@ -167,7 +168,6 @@ def _get_collection_shape(
167168
shapes: list[GeoDataFrame],
168169
c: Any,
169170
s: float,
170-
norm: Any,
171171
render_params: ShapesRenderParams,
172172
fill_alpha: None | float = None,
173173
outline_alpha: None | float = None,
@@ -215,23 +215,12 @@ def _as_rgba_array(x: Any) -> np.ndarray:
215215
elif c_arr.ndim == 1 and len(c_arr) == len(shapes) and np.issubdtype(c_arr.dtype, np.number):
216216
finite_mask = np.isfinite(c_arr)
217217

218-
# Select or build a normalization that ignores NaNs for scaling
219-
if isinstance(norm, Normalize):
220-
used_norm: Normalize = norm
221-
else:
222-
if finite_mask.any():
223-
vmin = float(np.nanmin(c_arr[finite_mask]))
224-
vmax = float(np.nanmax(c_arr[finite_mask]))
225-
if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
226-
vmin, vmax = 0.0, 1.0
227-
else:
228-
vmin, vmax = 0.0, 1.0
229-
used_norm = colors.Normalize(vmin=vmin, vmax=vmax, clip=False)
230-
231-
# Map finite values through cmap(norm(.)); NaNs get na_color
218+
# Map finite values through cmap(norm(.)); NaNs get na_color. The norm is resolved
219+
# from the same values the colorbar uses, so pixels and colorbar agree (#699).
232220
fill_c = np.empty((len(c_arr), 4), dtype=float)
233221
fill_c[:] = na_rgba
234222
if finite_mask.any():
223+
used_norm = _resolve_continuous_norm(c_arr, render_params.cmap_params)
235224
fill_c[finite_mask] = cmap(used_norm(c_arr[finite_mask]))
236225

237226
elif c_arr.ndim == 1 and len(c_arr) == len(shapes) and c_arr.dtype == object:
@@ -246,14 +235,7 @@ def _as_rgba_array(x: Any) -> np.ndarray:
246235

247236
# numeric entries via cmap(norm)
248237
if is_num.any():
249-
if isinstance(norm, Normalize):
250-
used_norm = norm
251-
else:
252-
vmin = float(np.nanmin(num[is_num])) if is_num.any() else 0.0
253-
vmax = float(np.nanmax(num[is_num])) if is_num.any() else 1.0
254-
if not np.isfinite(vmin) or not np.isfinite(vmax) or vmin == vmax:
255-
vmin, vmax = 0.0, 1.0
256-
used_norm = colors.Normalize(vmin=vmin, vmax=vmax, clip=False)
238+
used_norm = _resolve_continuous_norm(num, render_params.cmap_params)
257239
fill_c[is_num] = cmap(used_norm(num[is_num]))
258240

259241
# non-numeric, non-NaN entries as explicit colors

‎src/spatialdata_plot/pl/render.py‎

Lines changed: 22 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -38,10 +38,10 @@
3838
_color_vector_to_rgba,
3939
_get_colors_for_categorical_obs,
4040
_get_linear_colormap,
41-
_make_continuous_mappable,
4241
_map_color_seg,
4342
_maybe_set_colors,
4443
_prepare_cmap_norm,
44+
_resolve_continuous_norm,
4545
_set_color_source_vec,
4646
)
4747
from spatialdata_plot.pl._datashader import (
@@ -77,6 +77,7 @@
7777
PointsRenderParams,
7878
ShapesRenderParams,
7979
_DsReduction,
80+
colormap_with_alpha,
8081
)
8182
from spatialdata_plot.pl.utils import (
8283
_decorate_axs,
@@ -515,21 +516,17 @@ def _append_outline_colorbar(
515516
) -> None:
516517
"""Append a `ColorbarSpec` for a continuous outline column.
517518
518-
No-op when ``outline_color_vector`` has no finite values. Honors user-supplied
519-
`vmin`/`vmax` on ``cmap_params.norm``; falls back to data range. Mirrors the
520-
`vmin == vmax` ±0.5 expansion used by the fill colorbar.
519+
No-op when ``outline_color_vector`` has no finite values. Derives the bar from the same
520+
resolved norm the outline pixels use, so the two agree (#699).
521521
"""
522522
arr = pd.to_numeric(pd.Series(np.asarray(outline_color_vector)), errors="coerce").to_numpy()
523-
finite = np.isfinite(arr)
524-
if not finite.any():
523+
if not np.isfinite(arr).any():
525524
return
526-
norm = cmap_params.norm
527-
vmin = norm.vmin if norm.vmin is not None else float(np.nanmin(arr[finite]))
528-
vmax = norm.vmax if norm.vmax is not None else float(np.nanmax(arr[finite]))
525+
used_norm = _resolve_continuous_norm(outline_color_vector, cmap_params)
529526
colorbar_requests.append(
530527
ColorbarSpec(
531528
ax=ax,
532-
mappable=_make_continuous_mappable(vmin, vmax, cmap_params.cmap),
529+
mappable=ScalarMappable(norm=used_norm, cmap=cmap_params.cmap),
533530
params=colorbar_params,
534531
label=outline_col,
535532
alpha=alpha,
@@ -747,7 +744,7 @@ def _render_shapes(
747744

748745
color_vector = _maybe_apply_transfunc(color_source_vector, color_vector, render_params.transfunc)
749746

750-
norm = copy(render_params.cmap_params.norm)
747+
norm = render_params.cmap_params.fresh_norm()
751748

752749
if len(color_vector) == 0:
753750
color_vector = [render_params.cmap_params.na_color.get_hex_with_alpha()]
@@ -968,7 +965,6 @@ def _render_shapes(
968965
render_params=render_params,
969966
rasterized=sc_settings._vector_friendly,
970967
cmap=None,
971-
norm=None,
972968
fill_alpha=0.0,
973969
outline_alpha=render_params.outline_alpha[0],
974970
outline_color=outline_rgba,
@@ -987,7 +983,6 @@ def _render_shapes(
987983
render_params=render_params,
988984
rasterized=sc_settings._vector_friendly,
989985
cmap=None,
990-
norm=None,
991986
fill_alpha=0.0,
992987
outline_alpha=render_params.outline_alpha[0],
993988
outline_color=render_params.outline_params.outer_outline_color.get_hex(),
@@ -1008,7 +1003,6 @@ def _render_shapes(
10081003
render_params=render_params,
10091004
rasterized=sc_settings._vector_friendly,
10101005
cmap=None,
1011-
norm=None,
10121006
fill_alpha=0.0,
10131007
outline_alpha=render_params.outline_alpha[1],
10141008
outline_color=render_params.outline_params.inner_outline_color.get_hex(),
@@ -1030,7 +1024,6 @@ def _render_shapes(
10301024
render_params=render_params,
10311025
rasterized=sc_settings._vector_friendly,
10321026
cmap=render_params.cmap_params.cmap,
1033-
norm=norm,
10341027
fill_alpha=render_params.fill_alpha,
10351028
outline_alpha=0.0,
10361029
zorder=render_params.zorder,
@@ -1043,25 +1036,11 @@ def _render_shapes(
10431036
path.vertices = trans.transform(path.vertices)
10441037

10451038
if not values_are_categorical:
1046-
# Respect explicit vmin/vmax; otherwise derive from finite numeric values, falling back to [0, 1] if unavailable
1047-
vmin = render_params.cmap_params.norm.vmin
1048-
vmax = render_params.cmap_params.norm.vmax
1049-
if vmin is None or vmax is None:
1050-
numeric_values = pd.to_numeric(np.asarray(color_vector), errors="coerce")
1051-
finite_mask = np.isfinite(numeric_values)
1052-
if finite_mask.any():
1053-
data_min = float(np.nanmin(numeric_values[finite_mask]))
1054-
data_max = float(np.nanmax(numeric_values[finite_mask]))
1055-
if vmin is None:
1056-
vmin = data_min
1057-
if vmax is None:
1058-
vmax = data_max
1059-
else:
1060-
if vmin is None:
1061-
vmin = 0.0
1062-
if vmax is None:
1063-
vmax = 1.0
1064-
_cax.set_clim(vmin=vmin, vmax=vmax)
1039+
# Derive the colorbar range from the SAME resolved norm the fill pixels use, so the bar
1040+
# can't disagree with the rendered shapes (#699). (matplotlib path; no-op for the
1041+
# datashader image, whose colorbar is built separately from the reduction bounds.)
1042+
used_norm = _resolve_continuous_norm(color_vector, render_params.cmap_params)
1043+
_cax.set_clim(vmin=used_norm.vmin, vmax=used_norm.vmax)
10651044

10661045
_add_legend_and_colorbar(
10671046
ax=ax,
@@ -1511,7 +1490,7 @@ def _render_points(
15111490

15121491
trans, trans_data = _prepare_transformation(sdata.points[element], coordinate_system, ax)
15131492

1514-
norm = copy(render_params.cmap_params.norm)
1493+
norm = render_params.cmap_params.fresh_norm()
15151494

15161495
method = render_params.method
15171496

@@ -1972,9 +1951,9 @@ def _render_images(
19721951
else render_params.cmap_params.cmap
19731952
)
19741953

1975-
# Overwrite alpha in cmap: https://stackoverflow.com/a/10127675
1976-
cmap._init()
1977-
cmap._lut[:, -1] = render_params.alpha
1954+
# Bake a uniform alpha into the cmap via a public-API rebuild (no private `_lut` poke,
1955+
# no mutation of the shared cmap). The selected cmap may be palette-derived, so apply to it.
1956+
cmap = colormap_with_alpha(cmap, render_params.alpha, render_params.cmap_params.na_color.get_hex_with_alpha())
19781957

19791958
# norm needs to be passed directly to ax.imshow(). If we normalize before, that method would always clip.
19801959
_ax_show_and_transform(
@@ -2432,7 +2411,7 @@ def _render_labels(
24322411
y=xy[:, 1],
24332412
color_vector=point_color_vector,
24342413
color_source_vector=point_color_source_vector,
2435-
norm=copy(render_params.cmap_params.norm), # ax.scatter autoscales in place; don't mutate the shared norm
2414+
norm=render_params.cmap_params.fresh_norm(), # ax.scatter autoscales in place; don't mutate the shared norm
24362415
na_color=na_color,
24372416
adata=table if table_name is not None else None,
24382417
col_for_color=col_for_color,
@@ -2465,11 +2444,14 @@ def _draw_labels(
24652444
outline_color_source_vector=outline_color_source_vector if seg_boundaries else None,
24662445
)
24672446

2447+
# `labels` is pre-baked RGB, so imshow ignores cmap/norm for pixels — they exist only to
2448+
# drive the colorbar. Feed it the SAME resolved norm `_map_color_seg` used for the pixels
2449+
# so the bar matches, instead of relying on an in-place autoscale of the shared norm (#699).
24682450
cax = ax.imshow(
24692451
labels,
24702452
rasterized=True,
24712453
cmap=None if categorical else render_params.cmap_params.cmap,
2472-
norm=None if categorical else render_params.cmap_params.norm,
2454+
norm=None if categorical else _resolve_continuous_norm(color_vector, render_params.cmap_params),
24732455
alpha=alpha,
24742456
origin="lower",
24752457
zorder=render_params.zorder,

0 commit comments

Comments
 (0)