Add new parameters to imshow: cmap, vmin, vmax, and origin for enhanced image display control

Author: CSSFrancis

Examples/plot_image2d.py

@@ -15,6 +15,19 @@
 
 Key bindings on the image panel: **R** reset view · **C** toggle colorbar ·
 **L** / **S** cycle colour-scale modes.
+
+New ``imshow`` parameters
+-------------------------
+``cmap``
+    Colormap name passed directly to :meth:`~anyplotlib.figure_plots.Axes.imshow`
+    (e.g. ``"viridis"``, ``"inferno"``).  Defaults to ``"gray"``.
+``vmin`` / ``vmax``
+    Colormap clipping limits in data units.  Values outside the range are
+    clamped to the colormap endpoints.  Defaults to the data min/max.
+``origin``
+    ``"upper"`` (default) places row 0 at the top (image convention).
+    ``"lower"`` places row 0 at the bottom (scientific / matrix convention)
+    and automatically reverses the y-axis so tick values increase upward.
 """
 import numpy as np
 import anyplotlib as apl
@@ -47,13 +60,14 @@ def _ring(r, r0, width, amp):
 ax_img  = fig.add_subplot(gs[0, 0])
 ax_hist = fig.add_subplot(gs[1, 0])
 
-# ── Image panel ───────────────────────────────────────────────────────────────
-v = ax_img.imshow(image, axes=[x, y], units="nm")
-v.set_colormap("inferno")
-
+# ── Image panel — cmap, vmin, vmax supplied directly to imshow ────────────────
 vmin_init = float(image.min())
 vmax_init = float(image.max())
-v.set_clim(vmin=vmin_init, vmax=vmax_init)
+
+# Pass cmap, vmin, and vmax directly — no separate set_colormap / set_clim call
+# needed for the initial display.
+v = ax_img.imshow(image, axes=[x, y], units="nm",
+                  cmap="inferno", vmin=vmin_init, vmax=vmax_init)
 
 # First-order spot markers
 dx = x[1] - x[0]
@@ -98,12 +112,28 @@ def _apply_high(event):
 fig
 
 # %%
-# Adjust colour map
-# ------------------
+# Adjust colour map and display range
+# ------------------------------------
 # :meth:`~anyplotlib.figure_plots.Plot2D.set_colormap` switches the palette;
 # :meth:`~anyplotlib.figure_plots.Plot2D.set_clim` adjusts the display range.
+# Both are equivalent to passing ``cmap`` / ``vmin`` / ``vmax`` at construction.
 
 v.set_colormap("viridis")
 v.set_clim(vmin=0.0, vmax=0.8)
 
 fig
+
+# %%
+# origin='lower' — scientific / matrix convention
+# ------------------------------------------------
+# Passing ``origin='lower'`` places row 0 of the data at the *bottom* of the
+# image, matching the matplotlib / scientific convention.  The y-axis is
+# automatically reversed so tick values still increase upward.
+
+mat = np.arange(64, dtype=float).reshape(8, 8)   # row 0 = small values
+
+fig2, ax2 = apl.subplots()
+v2 = ax2.imshow(mat, cmap="plasma", origin="lower")
+
+fig2
+

anyplotlib/figure_plots.py

@@ -153,22 +153,42 @@ def __init__(self, fig: "Figure", spec: SubplotSpec):  # noqa: F821
     # ------------------------------------------------------------------
     def imshow(self, data: np.ndarray,
                axes: list | None = None,
-               units: str = "px") -> "Plot2D":
+               units: str = "px",
+               cmap: str | None = None,
+               vmin: float | None = None,
+               vmax: float | None = None,
+               origin: str = "upper") -> "Plot2D":
         """Attach a 2-D image to this axes cell.
 
         Parameters
         ----------
-        data : np.ndarray  shape (H, W) or (H, W, C)
+        data : np.ndarray, shape (H, W) or (H, W, C)
+            Image data.  RGB/RGBA arrays use only the first channel.
         axes : [x_axis, y_axis], optional
+            Physical coordinate arrays for each axis.
         units : str, optional
+            Axis units label.  Default ``"px"``.
+        cmap : str, optional
+            Colormap name (e.g. ``"viridis"``, ``"inferno"``).
+            Defaults to ``"gray"``.
+        vmin, vmax : float, optional
+            Colormap clipping limits in data units.  Values outside this
+            range are clamped to the colormap endpoints.  Defaults to the
+            data min / max.
+        origin : ``"upper"`` | ``"lower"``, optional
+            Where row 0 of the array is placed.  ``"upper"`` (default)
+            puts row 0 at the top, matching the usual image convention.
+            ``"lower"`` puts row 0 at the bottom, matching the matplotlib
+            convention for matrices / scientific plots.
 
         Returns
         -------
         Plot2D
         """
         x_axis = axes[0] if axes and len(axes) > 0 else None
         y_axis = axes[1] if axes and len(axes) > 1 else None
-        plot = Plot2D(data, x_axis=x_axis, y_axis=y_axis, units=units)
+        plot = Plot2D(data, x_axis=x_axis, y_axis=y_axis, units=units,
+                      cmap=cmap, vmin=vmin, vmax=vmax, origin=origin)
         self._attach(plot)
         return plot
 
@@ -495,17 +515,36 @@ class Plot2D:
     """
 
     def __init__(self, data: np.ndarray,
-                 x_axis=None, y_axis=None, units: str = "px"):
+                 x_axis=None, y_axis=None, units: str = "px",
+                 cmap: str | None = None,
+                 vmin: float | None = None,
+                 vmax: float | None = None,
+                 origin: str = "upper"):
         self._id:  str = ""       # assigned by Axes._attach
         self._fig: object = None  # assigned by Axes._attach
 
+        _valid_origins = ("upper", "lower")
+        if origin not in _valid_origins:
+            raise ValueError(
+                f"origin must be one of {_valid_origins!r}, got {origin!r}"
+            )
+        self._origin: str = origin
+
         data = np.asarray(data)
         if data.ndim == 3:
             data = data[:, :, 0]
         if data.ndim != 2:
             raise ValueError(f"data must be 2-D (H x W), got {data.shape}")
 
         h, w = data.shape
+
+        # origin='lower' — row 0 at the bottom, matching matplotlib's matrix
+        # convention.  Flip the data so our renderer (which always draws row 0
+        # at the top) shows the correct orientation, and reverse the y-axis so
+        # tick values increase upward.
+        if origin == "lower":
+            data = np.flipud(data)
+
         x_axis_given = x_axis is not None
         y_axis_given = y_axis is not None
         if x_axis is None:
@@ -515,12 +554,20 @@ def __init__(self, data: np.ndarray,
         x_axis = np.asarray(x_axis, dtype=float)
         y_axis = np.asarray(y_axis, dtype=float)
 
-        img_u8, vmin, vmax = _normalize_image(data)
+        if origin == "lower":
+            y_axis = y_axis[::-1]
+
+        img_u8, raw_vmin, raw_vmax = _normalize_image(data)
         self._raw_u8   = img_u8
-        self._raw_vmin = vmin
-        self._raw_vmax = vmax
+        self._raw_vmin = raw_vmin
+        self._raw_vmax = raw_vmax
+
+        cmap_name = cmap if cmap is not None else "gray"
+        cmap_lut  = _build_colormap_lut(cmap_name)
 
-        cmap_lut = _build_colormap_lut("gray")
+        # vmin/vmax clip the colormap in data units; default to the full range.
+        disp_min = float(vmin) if vmin is not None else raw_vmin
+        disp_max = float(vmax) if vmax is not None else raw_vmax
 
         # Compute physical pixel scale (data-units per pixel) from axis arrays
         scale_x = float(abs(x_axis[-1] - x_axis[0]) / max(w - 1, 1)) if len(x_axis) >= 2 else 1.0
@@ -538,14 +585,14 @@ def __init__(self, data: np.ndarray,
             "units":             units,
             "scale_x":           scale_x,
             "scale_y":           scale_y,
-            "display_min":       vmin,
-            "display_max":       vmax,
-            "raw_min":           vmin,
-            "raw_max":           vmax,
+            "display_min":       disp_min,
+            "display_max":       disp_max,
+            "raw_min":           raw_vmin,
+            "raw_max":           raw_vmax,
             "show_colorbar":     False,
             "log_scale":         False,
             "scale_mode":        "linear",
-            "colormap_name":     "gray",
+            "colormap_name":     cmap_name,
             "colormap_data":     cmap_lut,
             "zoom":              1.0,
             "center_x":          0.5,
@@ -589,13 +636,21 @@ def to_state_dict(self) -> dict:
     # ------------------------------------------------------------------
     def update(self, data: np.ndarray,
                x_axis=None, y_axis=None, units: str | None = None) -> None:
-        """Replace the image data."""
+        """Replace the image data.
+
+        The ``origin`` supplied at construction is automatically re-applied
+        so the new data is displayed with the same orientation.
+        """
         data = np.asarray(data)
         if data.ndim == 3:
             data = data[:, :, 0]
         if data.ndim != 2:
             raise ValueError(f"data must be 2-D, got {data.shape}")
         h, w = data.shape
+
+        if self._origin == "lower":
+            data = np.flipud(data)
+
         img_u8, vmin, vmax = _normalize_image(data)
         self._raw_u8, self._raw_vmin, self._raw_vmax = img_u8, vmin, vmax
 
@@ -604,21 +659,24 @@ def update(self, data: np.ndarray,
             self._state["image_width"] = w
             self._state["has_axes"] = True
         if y_axis is not None:
-            self._state["y_axis"] = np.asarray(y_axis, float).tolist()
+            ya = np.asarray(y_axis, float)
+            if self._origin == "lower":
+                ya = ya[::-1]
+            self._state["y_axis"] = ya.tolist()
             self._state["image_height"] = h
             self._state["has_axes"] = True
         if units is not None:
             self._state["units"] = units
 
         self._state.update({
-            "image_b64":   self._encode_bytes(img_u8),
+            "image_b64":    self._encode_bytes(img_u8),
             "image_width":  w,
             "image_height": h,
-            "display_min": vmin,
-            "display_max": vmax,
-            "raw_min":     vmin,
-            "raw_max":     vmax,
-            "colormap_data":  _build_colormap_lut(self._state["colormap_name"]),
+            "display_min":  vmin,
+            "display_max":  vmax,
+            "raw_min":      vmin,
+            "raw_max":      vmax,
+            "colormap_data": _build_colormap_lut(self._state["colormap_name"]),
         })
         self._push()