feat(color): PercentileNormalize for percentile-based contrast limits

Heavy-tailed images (fluorescence, Xenium morphology) render dim because the
default per-channel min/max normalization maps the bulk of the signal to
near-black — a single bright outlier sets vmax. This addresses the dimness
reported in #370.

Add PercentileNormalize, a matplotlib Normalize subclass that autoscales
vmin/vmax to data percentiles (pmin/pmax) instead of min/max. It plugs into the
existing `norm=` argument with no new parameter: a single instance is broadcast
and autoscaled independently per channel, and a list applies channelwise limits
(length must match the channel count, as already validated).

Unify the two normalization code paths: _resolve_continuous_norm (single-channel
colorbar + shapes/points/labels) now delegates to the norm's own autoscale_None
instead of reimplementing min/max, so PercentileNormalize is honored everywhere.
This is behavior-preserving for plain Normalize (min/max) and LogNorm
(positive-only domain); an equivalence test locks that.

Default behavior is unchanged (still min/max); percentile contrast is opt-in.

Usage:
    import spatialdata_plot as sdp
    sdata.pl.render_images("morphology_focus", palette=[...], channel=[...],
                           norm=sdp.PercentileNormalize(0, 99.5))

Author: timtreis

src/spatialdata_plot/__init__.py

@@ -3,7 +3,8 @@
 from . import pl
 from ._logging import set_verbosity
 from ._settings import Verbosity
+from .pl._color import PercentileNormalize
 
-__all__ = ["pl", "set_verbosity", "Verbosity"]
+__all__ = ["PercentileNormalize", "Verbosity", "pl", "set_verbosity"]
 
 __version__ = version("spatialdata-plot")

src/spatialdata_plot/pl/_color.py

@@ -110,39 +110,82 @@ def _make_continuous_mappable(vmin: float, vmax: float, cmap: Any) -> ScalarMapp
     return ScalarMappable(norm=Normalize(vmin=vmin, vmax=vmax), cmap=cmap)
 
 
+class PercentileNormalize(Normalize):
+    """:class:`~matplotlib.colors.Normalize` that autoscales to data percentiles instead of min/max.
+
+    Heavy-tailed images (fluorescence, Xenium morphology) have a few very bright pixels, so the
+    default min/max mapping crushes the bulk of the signal into near-black. ``PercentileNormalize``
+    derives ``vmin``/``vmax`` from the ``pmin``/``pmax`` percentiles of the data instead, which
+    matches the per-channel contrast limits used by viewers like Xenium Explorer.
+
+    It plugs into the existing ``norm`` argument like any other ``Normalize``: a single instance is
+    autoscaled independently per channel, and a list applies channelwise limits.
+
+    Parameters
+    ----------
+    pmin
+        Lower percentile in ``[0, 100]`` (``pmin < pmax``) used to derive ``vmin``.
+    pmax
+        Upper percentile in ``[0, 100]`` used to derive ``vmax``.
+    clip
+        Forwarded to :class:`~matplotlib.colors.Normalize`.
+
+    Notes
+    -----
+    Explicitly setting ``vmin``/``vmax`` overrides the corresponding percentile.
+    """
+
+    def __init__(self, pmin: float = 0.0, pmax: float = 100.0, clip: bool = False) -> None:
+        if not 0.0 <= pmin < pmax <= 100.0:
+            raise ValueError(f"Require 0 <= pmin < pmax <= 100, got pmin={pmin}, pmax={pmax}.")
+        super().__init__(vmin=None, vmax=None, clip=clip)
+        self.pmin = pmin
+        self.pmax = pmax
+
+    def autoscale_None(self, A: Any) -> None:
+        """Fill unset ``vmin``/``vmax`` from the ``pmin``/``pmax`` percentiles of finite values."""
+        finite = np.asarray(A)
+        finite = finite[np.isfinite(finite)]
+        if finite.size:
+            if self.vmin is None:
+                self.vmin = float(np.percentile(finite, self.pmin))
+            if self.vmax is None:
+                self.vmax = float(np.percentile(finite, self.pmax))
+
+
 def _resolve_continuous_norm(values: Any, cmap_params: CmapParams) -> Normalize:
     """Resolve ``cmap_params.norm`` with concrete vmin/vmax 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. Preserves the
-    norm subclass (``LogNorm``/``PowerNorm``/...) so non-linear scaling is not silently linearized.
+    Honor explicit ``norm`` vmin/vmax, else delegate to the norm's own ``autoscale_None`` over the
+    finite values of ``values`` (so plain ``Normalize`` uses min/max, ``LogNorm`` uses its
+    positive-only range, and ``PercentileNormalize`` uses percentiles), else fall back to ``[0, 1]``.
+    Shared by the pixel and colorbar sites so both derive the same range; preserves the norm
+    subclass so non-linear scaling is not silently linearized.
     """
-    base = cmap_params.norm
-    vmin, vmax = base.vmin, base.vmax
-    if vmin is None or vmax is None:
+    resolved = copy(cmap_params.norm)
+    if resolved.vmin is None or resolved.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)
-        if isinstance(base, LogNorm):
-            # LogNorm's domain excludes 0/negatives; derive the range from strictly-positive
-            # finite values only (mirrors matplotlib's LogNorm.autoscale_None). Otherwise a
-            # data_min <= 0 produces a LogNorm that raises "Invalid vmin or vmax" when called.
-            positive = arr[finite & (arr > 0)]
-            data_min = float(np.nanmin(positive)) if positive.size else 1.0
-            data_max = float(np.nanmax(positive)) if positive.size else 1.0
+        finite = arr[np.isfinite(arr)]
+        if finite.size:
+            resolved.autoscale_None(finite)
+        if isinstance(resolved, LogNorm):
+            # LogNorm needs strictly-positive bounds; all-nonpositive/empty data can't provide them
+            # (matplotlib leaves them at 0), so fall back to a valid domain instead of raising later.
+            if resolved.vmin is None or resolved.vmin <= 0:
+                resolved.vmin = 1.0
+            if resolved.vmax is None or resolved.vmax <= 0:
+                resolved.vmax = 1.0
         else:
-            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
-    if vmin == vmax and not isinstance(base, LogNorm):
+            # Empty/all-NaN data can't fill the bounds; fall back to the unit interval.
+            if resolved.vmin is None:
+                resolved.vmin = 0.0
+            if resolved.vmax is None:
+                resolved.vmax = 1.0
+    if resolved.vmin == resolved.vmax and not isinstance(resolved, LogNorm):
         # degenerate range collapses the cmap onto its floor; fall back to [0, 1]. LogNorm exempt (0 not in domain).
-        vmin, vmax = 0.0, 1.0
-    resolved = copy(base)
-    resolved.vmin, resolved.vmax = vmin, vmax
+        resolved.vmin, resolved.vmax = 0.0, 1.0
     return resolved
 
 

src/spatialdata_plot/pl/basic.py

@@ -768,6 +768,10 @@ def render_images(
             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 channels).
+            For heavy-tailed images (e.g. fluorescence/Xenium morphology) where min/max
+            scaling looks dim, pass :class:`~spatialdata_plot.PercentileNormalize` to clip each
+            channel to a percentile range (single instance for all channels, or a list for
+            channelwise limits).
         palette : list[str] | str | None
             Palette to color images. Can be a single palette name (broadcast to all channels) or a list
             matching the number of channels.

tests/pl/test_utils.py

@@ -1126,3 +1126,85 @@ def test_precomputed_rgba_passthrough(self):
 
         arr = np.array([[1.0, 0.0, 0.0, 1.0], [0.0, 0.0, 1.0, 1.0]])
         np.testing.assert_allclose(ColorSpec("continuous", None, arr).to_rgba(self._params()), arr)
+
+
+class TestPercentileNormalize:
+    """PercentileNormalize + _resolve_continuous_norm (issue #370: dim multichannel renders)."""
+
+    @staticmethod
+    def _three_channel_sdata() -> SpatialData:
+        from spatialdata.models import Image2DModel
+        from spatialdata.transformations import Identity
+
+        arr = np.zeros((3, 8, 8), dtype=np.uint16)
+        img = Image2DModel.parse(arr, dims=("c", "y", "x"), transformations={"global": Identity()})
+        return SpatialData(images={"img": img})
+
+    @pytest.mark.parametrize("norm_kind", ["normalize", "percentile"])
+    def test_norm_single_or_list_must_match_channels(self, norm_kind):
+        from matplotlib.colors import Normalize
+
+        from spatialdata_plot import PercentileNormalize
+        from spatialdata_plot.pl._validate import _validate_image_render_params
+
+        make = (lambda: Normalize(0, 200)) if norm_kind == "normalize" else (lambda: PercentileNormalize(1, 99))
+        sdata = self._three_channel_sdata()
+        kw = {
+            "element": "img",
+            "channel": None,
+            "alpha": 1.0,
+            "palette": None,
+            "cmap": None,
+            "scale": None,
+            "colorbar": True,
+            "colorbar_params": {},
+        }
+        # a single norm (broadcast) and a length-matching list are accepted; a mismatched list is rejected
+        _validate_image_render_params(sdata, norm=make(), **kw)
+        _validate_image_render_params(sdata, norm=[make() for _ in range(3)], **kw)
+        with pytest.raises(ValueError, match="must match the number of channels"):
+            _validate_image_render_params(sdata, norm=[make(), make()], **kw)
+
+    def test_autoscale_uses_percentiles(self):
+        from spatialdata_plot import PercentileNormalize
+
+        # heavy-tailed: one huge outlier should not set vmax under p99
+        data = np.concatenate([np.linspace(0, 100, 1000), [10000.0]])
+        norm = PercentileNormalize(1, 99)
+        norm.autoscale_None(data)
+        assert norm.vmin == pytest.approx(np.percentile(data, 1))
+        assert norm.vmax == pytest.approx(np.percentile(data, 99))
+        assert norm.vmax < 10000.0
+
+    def test_explicit_vmin_vmax_override_percentiles(self):
+        from spatialdata_plot import PercentileNormalize
+
+        norm = PercentileNormalize(1, 99)
+        norm.vmin, norm.vmax = 5.0, 50.0
+        norm.autoscale_None(np.linspace(0, 100, 100))
+        assert (norm.vmin, norm.vmax) == (5.0, 50.0)
+
+    @pytest.mark.parametrize("pmin,pmax", [(99, 1), (-1, 50), (50, 101), (5, 5)])
+    def test_invalid_percentiles_raise(self, pmin, pmax):
+        from spatialdata_plot import PercentileNormalize
+
+        with pytest.raises(ValueError):
+            PercentileNormalize(pmin, pmax)
+
+    def test_nan_values_ignored(self):
+        from spatialdata_plot import PercentileNormalize
+
+        norm = PercentileNormalize(0, 100)
+        norm.autoscale_None(np.array([np.nan, 1.0, 2.0, 3.0, np.inf, -np.inf]))
+        assert (norm.vmin, norm.vmax) == (1.0, 3.0)
+
+    def test_resolve_honors_percentile_norm(self):
+        # _resolve_continuous_norm (colorbar/shapes path) must defer to the norm's percentile autoscale;
+        # min/max and degenerate/empty fallbacks for builtin norms are covered by TestResolveContinuousNorm.
+        from spatialdata_plot import PercentileNormalize
+        from spatialdata_plot.pl._color import _prepare_cmap_norm, _resolve_continuous_norm
+
+        values = np.concatenate([np.linspace(0, 100, 1000), [10000.0]])
+        resolved = _resolve_continuous_norm(values, _prepare_cmap_norm(norm=PercentileNormalize(0, 99)))
+        assert resolved.vmax == pytest.approx(np.percentile(values, 99))
+        assert resolved.vmax < 10000.0