anyplotlib 0.7.3__tar.gz → 0.8.0__tar.gz

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/AGENTS.md

@@ -115,7 +115,7 @@ grep -nE '^\s*(function|const|let) [A-Za-z_]' anyplotlib/figure_esm.js
 ```
 
 and reconcile against the two numbered tables (the section map near the top and
-the 2-D function table). Both were last verified at 9,285 lines.
+the 2-D function table). Both were last verified at 10,119 lines.
 
 Changelog entries: add a fragment file to `upcoming_changes/` (e.g.
 `123.new_feature.rst`) — towncrier assembles `CHANGELOG.rst` at release time.

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/CHANGELOG.rst

@@ -10,6 +10,55 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.8.0 (2026-08-25)
+==================
+
+API and Behaviour Changes
+-------------------------
+
+- In tile mode, ``set_data``/``update_tile_source`` now re-derive the quantisation band
+  ``raw_min``/``raw_max`` from the incoming frame when the current band is unset or
+  degenerate (it previously stayed as first derived, even from a flat placeholder). A
+  band that is already valid is still never re-derived, so a contrast change keeps
+  re-windowing in the LUT with no pixel re-encode. One visible consequence: a tiled plot
+  born on a placeholder now quantises subsequent frames over the frame's own range
+  rather than the display window, matching what ``imshow`` of a large frame has always
+  done — so its wire bytes can differ by a rounding step from the equivalent untiled
+  plot, while the displayed image is unchanged. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+
+
+New Features
+------------
+
+- Added :meth:`~anyplotlib.plot2d.Plot2D.set_tile_band` to pin the fixed quantisation
+  band tile bytes are encoded over, for a consumer that already knows the honest range
+  (a camera's bit depth, a detector's saturation point) or whose source starts flat and
+  so has no range to auto-derive. It re-samples the overview and any active detail tile
+  over the new band in a single push, replacing the practice of reaching into
+  ``plot._state["raw_min"/"raw_max"]`` and calling ``update_tile_source()`` by hand. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+- Added :meth:`~anyplotlib.plot2d.Plot2D.set_display_window`, which moves the
+  contrast window without re-quantising the pixels — the non-destructive
+  counterpart to :meth:`~anyplotlib.plot2d.Plot2D.set_clim`, and what lets a
+  saved page be re-windowed with no Python behind it. (`#61 <https://github.com/CSSFrancis/anyplotlib/pull/61>`_)
+
+
+Bug Fixes
+---------
+
+- Fixed a tiled 2-D image rendering solid black when tile mode was entered on a flat
+  placeholder frame (e.g. ``imshow`` of zeros before real data exists). The fixed
+  quantisation band ``raw_min``/``raw_max`` was derived from that placeholder — a
+  degenerate ``(0, 0)`` — and no later ``set_data`` re-derived it, leaving the two ends
+  of the protocol disagreeing about what it meant: the Python encoder treats a
+  degenerate band as unset and quantises over the display window, while the renderer
+  honoured ``(0, 0)`` and mapped every code below the display floor. The panel rendered
+  black on the WebGPU and Canvas2D paths alike, beside perfectly healthy stats and
+  histograms, with no warning. ``set_data`` and ``update_tile_source`` now re-derive a
+  degenerate band from the incoming frame, and the renderer falls back to the display
+  window for a degenerate band in tile mode — in the image LUT and in the colorbar
+  tick placement, which read the band the same way. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+
+
 0.7.3 (2026-08-13)
 ==================
 

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: anyplotlib
-Version: 0.7.3
+Version: 0.8.0
 Summary: A plotting library using python, javascript and anywidget for performant in browser plotting.
 Project-URL: Homepage, https://cssfrancis.github.io/anyplotlib/
 Project-URL: Repository, https://github.com/CSSFrancis/anyplotlib

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/anyplotlib/FIGURE_ESM.md

@@ -59,20 +59,20 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 | `_createInsetDOM` / `_applyAllInsetStates` | 1129 / 1512 |
 | `_resizePanelDOM` | 2225 |
 | **2D drawing**: `_imgFitRect` | 2384 |
-| `draw2d` | 2692 |
-| `drawScaleBar2d` / `drawColorbar2d` | 2887 / 3125 |
-| **Floating keys**: `_keyEnsure` / `_keyRect` / `drawKeys` | 2986 / 3009 / 3022 |
-| `_drawAxes2d` (ticks, labels, title) | 3180 |
-| `drawOverlay2d` / `drawMarkers2d` | 3333 / 3497 |
-| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2512 / 2536 / 2597 |
+| `draw2d` | 2713 |
+| `drawScaleBar2d` / `drawColorbar2d` | 2908 / 3188 |
+| **Floating keys**: `_keyEnsure` / `_keyRect` / `drawKeys` | 3007 / 3030 / 3043 |
+| `_drawAxes2d` (ticks, labels, title) | 3242 |
+| `drawOverlay2d` / `drawMarkers2d` | 3395 / 3559 |
+| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2533 / 2557 / 2618 |
 | Binary-bytes splice: `_spliceBinaryBytes` / `_registerBinaryPixelListeners` | 730 / 761 |
-| **3D drawing**: `draw3d` | 5236 |
-| Event emission `_emitEvent` | 6073 |
-| 3D event handlers `_attachEvents3d` | 6125 |
-| **1D drawing**: `draw1d` | 6346 |
-| `_drawLine` (1D series + markers) | 6499 |
-| `drawOverlay1d` / `drawMarkers1d` | 6792 / 6876 |
-| Marker hit-test `_markerHitTest2d` | 7144 |
+| **3D drawing**: `draw3d` | 5298 |
+| Event emission `_emitEvent` | 6135 |
+| 3D event handlers `_attachEvents3d` | 6187 |
+| **1D drawing**: `draw1d` | 6408 |
+| `_drawLine` (1D series + markers) | 6561 |
+| `drawOverlay1d` / `drawMarkers1d` | 6854 / 6938 |
+| Marker hit-test `_markerHitTest2d` | 7206 |
 
 > **`raster` marker (1D/PlotXY)** — `drawMarkers1d` has a `type==='raster'`
 > branch that blits a single RGBA image across data-coord `extent` (the fast
@@ -81,16 +81,16 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 > redraws never re-transmit them; the decoded `OffscreenCanvas` is cached on
 > the marker set (`ms._rasterBmp`/`_rasterKey`). The shared `clip_path` block
 > clips it to a curved sector.
-| Panel event dispatch `_attachPanelEvents` | 7401 |
-| 2D events `_attachEvents2d` | 7443 |
-| 1D events `_attachEvents1d` | 7827 |
-| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 8099 / 8372 |
-| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8285 / 8299 / 8328 / 8363 |
-| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8495 / 8568 |
-| Shared-axis propagation `_getShareGroups` | 8639 |
-| Figure resize `_applyFigResizeDOM` | 8703 |
-| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8894 / 8957 / 9333 |
-| Generic redraw `_redrawPanel` | 9523 |
+| Panel event dispatch `_attachPanelEvents` | 7463 |
+| 2D events `_attachEvents2d` | 7505 |
+| 1D events `_attachEvents1d` | 7889 |
+| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 8161 / 8440 |
+| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8353 / 8367 / 8396 / 8431 |
+| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8565 / 8638 |
+| Shared-axis propagation `_getShareGroups` | 8709 |
+| Figure resize `_applyFigResizeDOM` | 8773 |
+| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8964 / 9027 / 9403 |
+| Generic redraw `_redrawPanel` | 9593 |
 
 > **`brush` widget (2-D)** — the one widget whose drag is *modal*, and the one
 > that must NOT write the model per tick. `_ovHitTest2d` takes an extra `mods`
@@ -269,12 +269,13 @@ st.colorbar_label_size            (label font sizes; optional)
 
 | Function | Line | Purpose |
 |----------|------|---------|
-| **`_imgFitRect(iw,ih,cw,ch)`** | **2372** | Largest rect of aspect `iw:ih` centred in `cw×ch`; all 2-D coordinate functions derive from this |
-| `draw2d(p)` | 2680 | Main render: `_resizePanelDOM` → decode → LUT → ImageBitmap → blit; then mask, axes, scale bar, colorbar, overlay, markers |
-| `drawScaleBar2d(p)` | 2875 | Physical scale bar |
-| `drawColorbar2d(p)` | 2961 | Gradient strip + min/max marks + rotated label centred in the `_cbWidth` gutter |
-| `_drawAxes2d(p)` | 3016 | Ticks (edge labels nudged inward both axes), axis labels + title via `_drawTex` |
-| `drawOverlay2d(p)` / `drawMarkers2d(p)` | 3169 / 3333 | Widgets / marker groups |
+| **`_imgFitRect(iw,ih,cw,ch)`** | **2384** | Largest rect of aspect `iw:ih` centred in `cw×ch`; all 2-D coordinate functions derive from this |
+| `draw2d(p)` | 2713 | Main render: `_resizePanelDOM` → decode → LUT → ImageBitmap → blit; then mask, axes, scale bar, colorbar, overlay, markers |
+| `drawScaleBar2d(p)` | 2908 | Physical scale bar |
+| `_rawBand(st)` / `_buildLut32(st)` | 2433 / 2440 | The quantisation band the u8 bytes were encoded over, then the 256-entry LUT built from it. `_rawBand` mirrors Python `_tile_quant_clim`: a DEGENERATE band (`raw_max <= raw_min`) is UNSET and falls back to `display_min/max`. Both render paths and the colorbar go through it — honouring a `(0, 0)` band paints solid black |
+| `drawColorbar2d(p)` | 3188 | Gradient strip + min/max marks (band-relative, via `_rawBand`) + rotated label centred in the `_cbWidth` gutter |
+| `_drawAxes2d(p)` | 3242 | Ticks (edge labels nudged inward both axes), axis labels + title via `_drawTex` |
+| `drawOverlay2d(p)` / `drawMarkers2d(p)` | 3395 / 3559 | Widgets / marker groups |
 
 Zoom model: at `zoom=1` the whole image fills the fit-rect; at `zoom=Z>1` a
 `1/Z` region fills it.  `_imgToCanvas2d` / `_canvasToImg2d` must stay exact

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/anyplotlib/figure_esm.js

@@ -2415,10 +2415,31 @@ function render({ model, el, onResize }) {
     };
   }
 
+  // The quantisation band the uint8 image bytes were encoded over, as [lo, hi].
+  // A DEGENERATE band (raw_max <= raw_min) means DIFFERENT things on the two
+  // encoder paths, and the LUT has to read it the way the bytes were written:
+  //
+  //   plain (_normalize_image): a constant frame quantises to ALL-ZERO bytes and
+  //     reports (c, c) — the band NAMES the single value code 0 stands for, and
+  //     hMin + raw/255 * (range||1) reconstructs it. Keep honouring it.
+  //   tile (_tile_quant_clim): a degenerate band is treated as UNSET and the
+  //     bytes are quantised over the DISPLAY window instead — so they are already
+  //     display-mapped and the LUT must be the identity window over them.
+  //
+  // Reading a tiled degenerate band the plain way is GH #60: a plot that entered
+  // tile mode on a flat placeholder carries the band (0, 0), every code maps to
+  // hMin + raw/255 * 1 in [0, 1], lands below any sane display floor, and the
+  // panel renders solid black beside perfectly healthy stats.
+  function _rawBand(st) {
+    const lo=st.raw_min, hi=st.raw_max;
+    if(lo==null||hi==null) return [st.display_min, st.display_max];
+    if(hi>lo) return [lo,hi];
+    return st.tile_enabled ? [st.display_min, st.display_max] : [lo,hi];
+  }
+
   function _buildLut32(st) {
     const dMin=st.display_min, dMax=st.display_max;
-    const hMin=st.raw_min!=null?st.raw_min:dMin;
-    const hMax=st.raw_max!=null?st.raw_max:dMax;
+    const [hMin,hMax]=_rawBand(st);
     const mode=st.scale_mode||'linear';
     const range=hMax-hMin||1;
     const cmapData=st.colormap_data||[];
@@ -3198,8 +3219,7 @@ function render({ model, el, onResize }) {
 
     // display_min / display_max tick marks
     const dMin=st.display_min, dMax=st.display_max;
-    const hMin=st.raw_min!=null?st.raw_min:dMin;
-    const hMax=st.raw_max!=null?st.raw_max:dMax;
+    const [hMin,hMax]=_rawBand(st);
     const vRange=(hMax-hMin)||1;
     function _vToY(v){return imgH-1-((v-hMin)/vRange)*(imgH-1);}
     ctx.strokeStyle='rgba(255,255,255,0.85)'; ctx.lineWidth=1.5;

{anyplotlib-0.7.3 → anyplotlib-0.8.0}/anyplotlib/plot2d/_plot2d.py

@@ -507,11 +507,7 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         # (raw_min/raw_max fixed, display_min/display_max move) with NO pixel re-encode
         # or re-transfer — set_clim just moves the display window (see set_clim). Set
         # once from the full-res range; keep any existing band on a re-enable.
-        if (self._state.get("raw_min") is None
-                or not (self._state.get("raw_max", 0) > self._state.get("raw_min", 0))):
-            rng = self._backend_display_range(self._tile_backend)
-            if rng is not None:
-                self._state["raw_min"], self._state["raw_max"] = rng
+        self._ensure_tile_band()
         _was_on = self._tile_on
         if not self._tile_on:
             self._tile_on = True
@@ -561,6 +557,13 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             setter = getattr(self._tile_backend, "set_array", None)
             if setter is not None:
                 setter(array)
+        # The quantisation band is derived ONCE (enable_tile) and then held fixed, so
+        # a contrast change re-windows in the LUT with no pixel re-encode. But if it
+        # was never VALIDLY derived — tile mode started on a flat placeholder, so the
+        # probe refused and the band stayed degenerate — the new data in the backend
+        # is the first chance to get it right. Must run BEFORE the overview/detail are
+        # re-sampled below so they quantise over the corrected band in the SAME push.
+        self._ensure_tile_band()
         reg = self._state.get("detail_region") or []
         has_detail = len(reg) == 4
         # Refresh the overview base ONLY when no detail tile is shown (zoomed out) —
@@ -622,6 +625,70 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         except Exception as e:
             _TLOG.warning("[TILEDBG] overview refresh FAILED: %s", e)
 
+    def _ensure_tile_band(self) -> bool:
+        """Derive the fixed quantisation band (raw_min/raw_max) from the CURRENT tile
+        backend when it is unset or DEGENERATE, by the same rule _tile_quant_clim
+        uses to read it back. Returns True iff the band was (re-)derived.
+
+        The degenerate case is the one that bites: a plot that entered tile mode on a
+        flat placeholder (e.g. zeros before real data exists) probes a range of
+        (0, 0) — _backend_display_range refuses it, so the band keeps the
+        constructor's raw min/max, which for zeros is also (0, 0). Every later
+        set_data then re-sampled the overview against a band the encoder treated as
+        unset (quantising over the display window) while the frontend LUT honoured
+        (0, 0) literally and painted the panel solid black. Calling this on each data
+        swap re-derives the band as soon as a frame with real range arrives, so the
+        two ends of the protocol agree on what the bytes mean.
+        """
+        lo, hi = self._state.get("raw_min"), self._state.get("raw_max")
+        if lo is not None and hi is not None and hi > lo:
+            return False                      # a valid band is kept, never re-derived
+        if self._tile_backend is None:
+            return False
+        rng = self._backend_display_range(self._tile_backend)
+        if rng is None:
+            # Still flat (an all-constant frame): leave the band unset/degenerate —
+            # _tile_quant_clim and the JS LUT both fall back to the display window.
+            return False
+        self._state["raw_min"], self._state["raw_max"] = rng
+        _TLOG.debug("[TILEDBG] tile band (re-)derived from backend → raw=(%s,%s)",
+                    *rng)
+        return True
+
+    def set_tile_band(self, vmin: float, vmax: float) -> None:
+        """PIN the fixed quantisation band the tile bytes are encoded over.
+
+        Tile mode normally derives this band once, from the full-res data (see
+        ``enable_tile``), and then holds it: a contrast change re-windows in the LUT
+        with no pixel re-encode or re-transfer. A live consumer that already KNOWS the
+        honest range — a camera's bit depth, a detector's saturation point — can pin
+        it here instead of letting the first frame decide, so the contrast doesn't
+        shift when a later frame happens to contain a brighter pixel.
+
+        Pinning also survives what auto-derivation cannot: a source whose first frames
+        are flat (a placeholder, a closed shutter) has no range to derive from, and
+        the band stays unset until a frame with real content arrives.
+
+        Re-samples the overview (and any active detail tile) over the new band in a
+        single push, so the pixels and the band the renderer reads them with never
+        disagree. Raises if the plot is not in tile mode or the range is degenerate."""
+        if not self._tile_on:
+            raise RuntimeError(
+                "set_tile_band requires tile mode — the band is the quantisation "
+                "range for the TILE bytes. Call enable_tile() first (or use "
+                "set_clim() to change the display window on a plain plot).")
+        lo, hi = float(vmin), float(vmax)
+        if not (hi > lo):
+            raise ValueError(
+                f"set_tile_band requires vmax > vmin, got ({lo}, {hi}). A degenerate "
+                f"band is what 'unset' means here — both the encoder and the "
+                f"renderer then fall back to the display window.")
+        self._state["raw_min"], self._state["raw_max"] = lo, hi
+        # Re-encode over the new band. update_tile_source() with no array re-samples
+        # from the backend in place (keeping zoom/center and the detail region) and
+        # pushes — so the band and the bytes it describes ship together.
+        self.update_tile_source()
+
     def _tile_quant_clim(self):
         """The FIXED quantisation band (raw_min/raw_max) the tile bytes are encoded
         over, so a contrast change re-windows in the LUT without re-encoding pixels.
@@ -1470,7 +1537,11 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         raw frame, not merely re-windowing the existing codes (which are saturated
         outside the previous band and so couldn't widen past it). For an RGB frame
         (no scalar quantisation) or when no raw frame is cached, fall back to a pure
-        display-window update."""
+        display-window update.
+
+        See :meth:`set_display_window` for the non-destructive counterpart — the
+        one to reach for when the pixels must not move (a tiled plot, or a
+        serialised figure being re-windowed with no Python behind it)."""
         new_min = float(vmin) if vmin is not None else self._state.get("display_min")
         new_max = float(vmax) if vmax is not None else self._state.get("display_max")
 
@@ -1512,6 +1583,40 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             self._state["display_max"] = float(vmax)
         self._push()
 
+    def set_display_window(self, vmin=None, vmax=None) -> None:
+        """Move the display window WITHOUT re-quantising the pixels.
+
+        The non-destructive counterpart to :meth:`set_clim`. Both change the
+        contrast; they differ in what they do to the data behind it:
+
+        ``set_clim``
+            re-encodes the cached raw frame over the new range, so the codes
+            always span exactly the visible band — maximum precision for what is
+            on screen, but the pixels are re-encoded and re-sent, and the old
+            band is gone.
+        ``set_display_window``
+            leaves the codes and their ``raw_min``/``raw_max`` band alone and
+            moves only the window the LUT maps through it. Nothing is re-encoded
+            and nothing travels but two floats.
+
+        Use it when the pixels must stay put: a tiled plot, where re-quantising
+        would re-encode the full-res frame on every drag tick (``set_clim``
+        already routes there internally), or a figure that has been serialised
+        and is being re-windowed with no Python behind it — which is how a saved
+        page gets a working contrast control at all.
+
+        The trade is precision. Quantisation spans ``[raw_min, raw_max]``, so a
+        window much narrower than that band resolves in coarse steps, and one
+        WIDER than it recovers nothing: values outside the band were saturated
+        to 0/255 when the frame was encoded. Quantise over the range you want to
+        be able to reach.
+        """
+        if vmin is not None:
+            self._state["display_min"] = float(vmin)
+        if vmax is not None:
+            self._state["display_max"] = float(vmax)
+        self._push()
+
     def set_detail(self, tile=None, x0=None, x1=None, y0=None, y1=None) -> None:
         """Upload a HIGH-RES detail tile covering the LOGICAL image-pixel rectangle
         ``[x0:x1, y0:y1]`` of the base image (in the SAME orientation as the frame

anyplotlib-0.8.0/anyplotlib/tests/test_plot2d/test_display_window.py

@@ -0,0 +1,135 @@
+"""
+tests/test_plot2d/test_display_window.py
+========================================
+``Plot2D.set_display_window`` — moving the contrast window WITHOUT re-quantising.
+
+The distinction from ``set_clim`` is the whole point, so these pin it from both
+sides: ``set_clim`` re-encodes the frame and collapses ``raw_*`` onto the new
+band; ``set_display_window`` leaves the codes and the band alone and moves only
+the window the LUT maps through.
+
+That difference is what decides whether a SERIALISED figure can have a working
+contrast control. A page saved after ``set_clim`` holds codes saturated outside
+the band it was saved with, so widening in JS recovers nothing; quantised over a
+wide band and windowed with ``set_display_window``, the same page can be
+re-windowed either way with no Python behind it.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+import anyplotlib as apl
+
+
+def _plot(data=None):
+    fig, ax = apl.subplots(1, 1)
+    if data is None:
+        data = np.arange(64, dtype=float).reshape(8, 8)
+    return ax.imshow(data)
+
+
+class TestWindowMoves:
+    def test_it_sets_both_ends(self):
+        p = _plot()
+        p.set_display_window(10.0, 40.0)
+        assert p._state["display_min"] == 10.0
+        assert p._state["display_max"] == 40.0
+
+    def test_either_end_alone_leaves_the_other(self):
+        p = _plot()
+        p.set_display_window(10.0, 40.0)
+        p.set_display_window(vmax=25.0)
+        assert p._state["display_min"] == 10.0
+        assert p._state["display_max"] == 25.0
+
+    def test_it_pushes_so_the_change_reaches_js(self):
+        # The _push() contract: a mutation that does not push never appears.
+        p = _plot()
+        seen = []
+        p._push = lambda *a, **k: seen.append(1)
+        p.set_display_window(1.0, 2.0)
+        assert seen, "set_display_window did not push"
+
+
+class TestPixelsStayPut:
+    """The defining property. If the codes move, this is just a slow set_clim."""
+
+    def test_the_encoded_pixels_are_untouched(self):
+        p = _plot()
+        before = p._state["image_b64"]
+        p.set_display_window(10.0, 40.0)
+        assert p._state["image_b64"] == before
+
+    def test_the_quantisation_band_is_untouched(self):
+        p = _plot()
+        raw_before = (p._state["raw_min"], p._state["raw_max"])
+        p.set_display_window(10.0, 40.0)
+        assert (p._state["raw_min"], p._state["raw_max"]) == raw_before
+
+    def test_set_clim_by_contrast_re_encodes_and_collapses_the_band(self):
+        # The counterpart, asserted here so the pair cannot silently converge.
+        p = _plot()
+        before = p._state["image_b64"]
+        p.set_clim(10.0, 40.0)
+        assert p._state["image_b64"] != before
+        assert p._state["raw_min"] == p._state["display_min"] == 10.0
+        assert p._state["raw_max"] == p._state["display_max"] == 40.0
+
+
+class TestHeadroomForASerialisedFigure:
+    def test_a_wide_band_keeps_room_to_window_in_both_directions(self):
+        # Quantise over the full range, then narrow: the codes still span the
+        # whole range, so a reader can widen back out. This is exactly what an
+        # exported page needs and what set_clim cannot give it.
+        data = np.arange(256, dtype=float).reshape(16, 16)
+        fig, ax = apl.subplots(1, 1)
+        p = ax.imshow(data, vmin=0.0, vmax=255.0)
+
+        p.set_display_window(100.0, 150.0)
+        assert p._state["raw_min"] == 0.0 and p._state["raw_max"] == 255.0
+        assert (p._state["display_min"], p._state["display_max"]) == (100.0, 150.0)
+
+        # …and back out past the narrow window, still against the full band.
+        p.set_display_window(0.0, 255.0)
+        assert (p._state["display_min"], p._state["display_max"]) == (0.0, 255.0)
+        assert p._state["raw_min"] == 0.0 and p._state["raw_max"] == 255.0
+
+    def test_set_clim_first_would_have_thrown_that_away(self):
+        data = np.arange(256, dtype=float).reshape(16, 16)
+        fig, ax = apl.subplots(1, 1)
+        p = ax.imshow(data, vmin=0.0, vmax=255.0)
+
+        p.set_clim(100.0, 150.0)
+        # Everything outside 100–150 is saturated in the codes now, so the band
+        # a serialised page could re-window within has collapsed to the window.
+        assert p._state["raw_min"] == 100.0 and p._state["raw_max"] == 150.0
+
+
+class TestRgbAndTile:
+    def test_an_rgb_frame_windows_the_same_way(self):
+        rgb = np.zeros((8, 8, 3), np.uint8)
+        fig, ax = apl.subplots(1, 1)
+        p = ax.imshow(rgb)
+        p.set_display_window(0.2, 0.8)
+        assert (p._state["display_min"], p._state["display_max"]) == (0.2, 0.8)
+
+    def test_it_matches_what_set_clim_already_does_in_tile_mode(self):
+        # set_clim's tile branch is this method's behaviour, inlined. Pin that
+        # they agree so the two cannot drift apart.
+        data = np.arange(256, dtype=float).reshape(16, 16)
+        fig, ax = apl.subplots(1, 1)
+        p = ax.imshow(data, vmin=0.0, vmax=255.0)
+        p._tile_on = True
+        before = p._state["image_b64"]
+
+        p.set_clim(60.0, 90.0)
+        via_clim = (p._state["display_min"], p._state["display_max"],
+                    p._state["raw_min"], p._state["raw_max"],
+                    p._state["image_b64"] == before)
+
+        p._tile_on = False
+        p.set_display_window(60.0, 90.0)
+        via_window = (p._state["display_min"], p._state["display_max"],
+                      p._state["raw_min"], p._state["raw_max"],
+                      p._state["image_b64"] == before)
+        assert via_clim == via_window