Fix norm inconsistencies across all image rendering paths

1. Copy norm in _prepare_cmap_norm so each CmapParams gets an
   independent instance — fixes shared-norm bug when cmap is a list
   and cross-element state sharing in chained render_images calls.

2. Move per-channel auto-ranging norm copy outside if/else so it
   covers both list and single-cmap branches.

3. Global auto-range for float RGB data outside [0,1]: instead of
   clipping (which destroys contrast), scale using global min/max
   across all RGB channels to preserve color balance.

4. Explicit np.clip in Path 2A-default after stacking normalized
   channels, instead of relying on matplotlib's silent clipping.

5. Remove dead percentiles_for_norm field from ImageRenderParams
   and the quantiles_for_norm deprecation alias.

6. Remove unreachable ch_norm-is-not-None guard since
   _prepare_cmap_norm always creates a Normalize.

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

Author: timtreis

src/spatialdata_plot/pl/basic.py

@@ -505,7 +505,7 @@ def render_points(
 
         return sdata
 
-    @_deprecation_alias(elements="element", quantiles_for_norm="percentiles_for_norm", version="version 0.3.0")
+    @_deprecation_alias(elements="element", version="version 0.3.0")
     def render_images(
         self,
         element: str | None = None,

src/spatialdata_plot/pl/render.py

@@ -1019,19 +1019,28 @@ def _render_points(
 
 
 def _normalize_dtype_to_float(arr: np.ndarray) -> np.ndarray:
-    """Normalize an integer or float array to float64 in [0, 1] for matplotlib.
+    """Normalize an array to float64 in [0, 1] for matplotlib.
 
     - uint8 → divide by 255
-    - other int/uint dtypes → divide by dtype max
-    - float → clip to [0, 1]
+    - other unsigned int → divide by dtype max
+    - signed int → divide by dtype max, clip negatives to 0
+    - float already in [0, 1] → pass through
+    - float outside [0, 1] → global auto-range (preserves relative balance across channels)
     """
     if arr.dtype == np.uint8:
         return arr.astype(np.float64) / 255.0
     if arr.dtype.kind == "u":
         return arr.astype(np.float64) / np.iinfo(arr.dtype).max
     if arr.dtype.kind == "i":
         return np.clip(arr.astype(np.float64) / np.iinfo(arr.dtype).max, 0, 1)
-    result: np.ndarray = np.clip(arr, 0, 1).astype(np.float64)
+    # Float: if already in [0, 1], keep as-is; otherwise auto-range globally
+    arr_f: np.ndarray = arr.astype(np.float64)
+    vmin, vmax = arr_f.min(), arr_f.max()
+    if vmin >= 0.0 and vmax <= 1.0:
+        return arr_f
+    if vmin == vmax:
+        return np.zeros_like(arr_f)
+    result: np.ndarray = (arr_f - vmin) / (vmax - vmin)
     return result
 
 
@@ -1221,18 +1230,17 @@ def _render_images(
                 ch_norm = render_params.cmap_params[ch_idx].norm
             else:
                 ch_norm = render_params.cmap_params.norm
-                # When a single auto-ranging norm is shared across channels, copy it so
-                # each channel normalizes independently based on its own value range.
-                if isinstance(ch_norm, Normalize) and (ch_norm.vmin is None or ch_norm.vmax is None):
-                    ch_norm = copy(ch_norm)
 
-            if ch_norm is not None:
-                layers[ch] = ch_norm(layers[ch])
+            # Auto-ranging norms are stateful — copy so each channel normalizes independently
+            if isinstance(ch_norm, Normalize) and (ch_norm.vmin is None or ch_norm.vmax is None):
+                ch_norm = copy(ch_norm)
+
+            layers[ch] = ch_norm(layers[ch])
 
         # 2A) Image has 3 channels, no palette info, and no/only one cmap was given
         if palette is None and n_channels == 3 and not isinstance(render_params.cmap_params, list):
             if render_params.cmap_params.cmap_is_default:  # -> use RGB
-                stacked = np.stack([layers[ch] for ch in layers], axis=-1)
+                stacked = np.clip(np.stack([layers[ch] for ch in layers], axis=-1), 0, 1)
             else:  # -> use given cmap for each channel
                 channel_cmaps = [render_params.cmap_params.cmap] * n_channels
                 stacked = (

src/spatialdata_plot/pl/render_params.py

@@ -265,7 +265,6 @@ class ImageRenderParams:
     channel: list[str] | list[int] | int | str | None = None
     palette: ListedColormap | list[str] | None = None
     alpha: float = 1.0
-    percentiles_for_norm: tuple[float | None, float | None] = (None, None)
     scale: str | None = None
     zorder: int = 0
     colorbar: bool | str | None = "auto"

src/spatialdata_plot/pl/utils.py

@@ -628,8 +628,7 @@ def _prepare_cmap_norm(
 
     assert isinstance(cmap, Colormap), f"Invalid type of `cmap`: {type(cmap)}, expected `Colormap`."
 
-    if norm is None:
-        norm = Normalize(vmin=None, vmax=None, clip=False)
+    norm = Normalize(vmin=None, vmax=None, clip=False) if norm is None else copy(norm)
 
     cmap.set_bad(na_color.get_hex_with_alpha())