MNutils 1.2.0__py3-none-any.whl

mnutils/plotting/_widgets/image_grid.css

@@ -0,0 +1,202 @@
+/* Every size that decides how big the plot area gets, in one place and in
+   rem so a reader's font size scales the whole widget together. Override any
+   of them on the widget element to retune a page.
+
+   Nothing here may exceed the pane the widget lands in: `.mnu-viewer` clips
+   its overflow, so a layout that is too wide doesn't scroll, it disappears.
+   Widths are therefore percentages of the host, with the rem values acting as
+   caps on top of them. */
+.mnutils-image-grid {
+  --mnu-grid-max-w: 100%; /* the plot area stops growing here */
+  --mnu-grid-max-h: 50vh; /* taller than this, the panel box scrolls */
+  --mnu-panel-max-h: 17rem; /* no single panel taller than this */
+  --mnu-panel-min-h: 8rem; /* ...nor shorter than this */
+  --mnu-panel-min-w: 9rem; /* narrower than this, the row wraps instead */
+  --mnu-grid-gap: 0.7rem;
+  --mnu-panel-pad: 0.7rem;
+
+  /* How wide the panels would like to be: their height cap times their aspect
+     ratio (--mnu-aspect is set per grid by the JS once the first frame has
+     loaded), times the nominal column count, plus gaps and padding. This cap
+     is what stops a wide window stretching four 64x64 frames across the whole
+     screen -- the columns below would otherwise share out every pixel going. */
+  --mnu-panel-w-cap: calc(var(--mnu-panel-max-h) * var(--mnu-aspect, 1));
+
+  /* The floor is the same trade read from the other end. A panel is as tall as
+     its width and aspect ratio make it, so "never shorter than
+     --mnu-panel-min-h" means "never narrower than that height times the aspect
+     ratio" -- for a 5x20 frame that is four times --mnu-panel-min-h. Columns
+     take the wider of that and --mnu-panel-min-w, so a row of wide frames wraps
+     sooner rather than flattening into strips. */
+  --mnu-panel-min-w-eff: max(
+    var(--mnu-panel-min-w),
+    calc(var(--mnu-panel-min-h) * var(--mnu-aspect, 1))
+  );
+  --mnu-grid-w-cap: calc(
+    var(--mnu-grid-cols, 1) * var(--mnu-panel-w-cap) +
+      (var(--mnu-grid-cols, 1) - 1) * var(--mnu-grid-gap) + 2 *
+      var(--mnu-panel-pad)
+  );
+
+  margin: 1em 0 0 1em;
+  width: 100%;
+  max-width: min(calc(var(--mnu-grid-max-w) - 1em), var(--mnu-grid-w-cap));
+  /* The panel grid alone can size the widget narrower than its own control
+     bar needs (a single small panel, say) -- floor it at the bar's worst-case
+     width (label + a 3-digit readout + a usable slider + the border toggle)
+     so the slider stays on the bar's first line instead of wrapping under it. */
+  min-width: min(100%, 16rem);
+}
+
+.mnutils-image-grid-title {
+  padding: 0.6em 0.7em 0.2em;
+  font-size: 1.05em;
+  font-weight: 700;
+  text-align: left;
+  color: var(--mnu-fg-strong);
+}
+
+/* The bar wraps instead of pushing the slider past the clipped edge: in a
+   narrow pane the label and readout take the first line and the slider drops
+   to the second, at whatever width is left. */
+.mnutils-image-grid-bar {
+  flex-wrap: wrap;
+  justify-content: flex-start;
+  max-width: 100%;
+  border-bottom: 1px solid var(--mnu-border-soft);
+}
+
+.mnutils-image-grid-bar .mnu-lbl,
+.mnutils-image-grid-bar .mnu-readout {
+  font-size: 1.1em;
+}
+
+.mnutils-image-grid-bar .mnu-readout {
+  font-family: inherit;
+  font-weight: 700;
+  line-height: inherit;
+  min-width: 0;
+  color: var(--mnu-fg-strong);
+}
+
+.mnutils-image-grid-bar .mnu-slider {
+  flex: 1 1 8rem;
+  width: auto;
+  min-width: 0;
+  max-width: 20rem;
+  height: 1.3em;
+}
+
+/* --mnu-grid-max-h bounds *this box*, not the panels inside it: past that
+   height the grid scrolls rather than shrinking its images. Twelve 32x32
+   panels are then twelve full-size panels behind a scrollbar, instead of
+   twelve stamps -- past a handful of rows, dividing a fixed budget between
+   them makes every panel unreadable at once.
+   `scrollbar-gutter: stable` reserves the scrollbar's width whether or not it
+   is showing, so the panels don't jump sideways when a slice change is the
+   thing that makes the content overflow. */
+.mnutils-image-grid-panel {
+  padding: var(--mnu-panel-pad);
+  border-bottom: none;
+  max-height: var(--mnu-grid-max-h);
+  overflow-y: auto;
+  overscroll-behavior: auto;
+  scrollbar-gutter: stable;
+}
+
+/* `auto-fit` + `minmax(--mnu-panel-min-w-eff, 1fr)`: as many columns as fit at
+   a readable size, wrapping to a new row when they don't -- where "readable"
+   is both floors above, whichever binds. The nominal column count
+   (`GRID_MAX_COLS`, five) is enforced from above by the widget's max-width
+   rather than by a fixed track list -- a fixed list is what cut the fourth
+   panel off in a narrow editor pane, since grid columns never wrap.
+   `min(..., 100%)` keeps the minimum itself from overflowing a pane narrower
+   than a single panel. */
+.mnutils-image-grid-cells {
+  display: grid;
+  grid-template-columns: repeat(
+    auto-fit,
+    minmax(min(var(--mnu-panel-min-w-eff), 100%), 1fr)
+  );
+  gap: var(--mnu-grid-gap);
+  align-items: start;
+  justify-items: start;
+}
+
+.mnutils-image-grid-cell {
+  display: flex;
+  flex-direction: column;
+  gap: 0.35em;
+  margin: 0;
+  min-width: 0;
+  width: 100%;
+}
+
+/* Width-driven, not height-driven: a panel fills its column, and the column is
+   what shrinks when the pane narrows or the grid gains images -- so more
+   images means smaller images rather than clipped ones. Height follows from
+   the aspect ratio, capped by --mnu-panel-max-h so that a single row can't
+   render a 512-row volume at full size. How many rows there are no longer
+   enters into it: the box above scrolls instead.
+
+   The floor is enforced by the column width above rather than here, so that
+   the panel grows *wider* to reach --mnu-panel-min-h instead of being
+   letterboxed into it. `min-height` stays as a backstop for the one case the
+   columns can't fix -- a pane too narrow for even a single minimum-width
+   column -- and, with `object-fit: contain`, for a frame so tall that the
+   height cap bites before the width one. Either way the frame keeps its
+   aspect ratio; only the padding around it changes. */
+.mnutils-image-grid-image {
+  display: block;
+  width: 100%;
+  height: auto;
+  min-height: var(--mnu-panel-min-h);
+  max-height: var(--mnu-panel-max-h);
+  object-fit: contain;
+  /* Set per image by the JS: `pixelated` whenever the frame is being scaled
+     up, so a 20x20 array reads as 400 big square pixels instead of a blur,
+     and `auto` when it is being scaled down, where nearest-neighbour would
+     just alias. */
+  image-rendering: var(--mnu-image-rendering, auto);
+}
+
+/* Toggled by the bar's "Border" checkbox. `border-box` keeps the outline
+   inside the column the panel already occupies, so ticking it doesn't reflow
+   the grid. */
+.mnutils-image-grid-cells.is-bordered .mnutils-image-grid-image {
+  box-sizing: border-box;
+  border: 1px solid var(--mnu-border);
+}
+
+.mnutils-image-grid-caption {
+  font-size: 0.85em;
+  text-align: center;
+  color: var(--mnu-fg);
+}
+
+.mnutils-image-grid-cbar {
+  display: flex;
+  align-items: center;
+  gap: 0.4em;
+  width: 100%;
+}
+
+.mnutils-image-grid-cbar-shared {
+  margin: 0.7rem auto 0;
+  max-width: min(100%, 26rem);
+}
+
+.mnutils-image-grid-cbar-strip {
+  flex: 1;
+  min-width: 0;
+  height: 0.55em;
+  border: 1px solid var(--mnu-border);
+  border-radius: 2px;
+}
+
+.mnutils-image-grid-cbar-tick {
+  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+  font-size: 0.7em;
+  color: var(--mnu-muted);
+  white-space: nowrap;
+}

mnutils/plotting/_widgets/image_grid.js

@@ -0,0 +1,212 @@
+/**
+ * Grid of pre-rendered image panels driven by one shared slice slider.
+ *
+ * The frames are bare rasters straight from PIL; the figure title, panel
+ * captions and colorbar are built here instead of being baked into the pixels
+ * (see `image_grid.py`). Frames are slice-major -- `frames[slice][panel]` --
+ * so moving the slider swaps every panel's `src` in one pass.
+ */
+
+/** Format a colorbar tick the way a reader expects to see a data value. */
+function formatTick(value) {
+  if (!Number.isFinite(value)) return String(value);
+  const magnitude = Math.abs(value);
+  if (value === 0) return "0";
+  if (magnitude >= 1e4 || magnitude < 1e-2) return value.toExponential(1);
+  return String(Number(value.toPrecision(3)));
+}
+
+/**
+ * Build a colorbar: a `linear-gradient` strip flanked by its two bounds.
+ *
+ * The gradient is the matplotlib colormap sampled to hex stops in Python, so
+ * the bar and the pixels it explains come from one colormap and can't drift.
+ * Returns the wrapper plus a `setBounds` that rewrites only the tick text --
+ * `colorbar_mode="each"` autoscales per slice, so those two nodes change on
+ * every slider move while the gradient never does.
+ */
+function makeColorbar(stops) {
+  const wrap = document.createElement("div");
+  wrap.className = "mnutils-image-grid-cbar";
+
+  const lo = document.createElement("span");
+  lo.className = "mnutils-image-grid-cbar-tick";
+
+  const strip = document.createElement("div");
+  strip.className = "mnutils-image-grid-cbar-strip";
+  strip.style.background = `linear-gradient(to right, ${stops.join(", ")})`;
+
+  const hi = document.createElement("span");
+  hi.className = "mnutils-image-grid-cbar-tick";
+
+  wrap.append(lo, strip, hi);
+
+  return {
+    wrap,
+    setBounds: ([low, high]) => {
+      lo.textContent = formatTick(low);
+      hi.textContent = formatTick(high);
+    },
+  };
+}
+
+function renderWidget(data, el) {
+  const {
+    frames,
+    bounds,
+    colormap_stops: stops,
+    n_slices: nSlices,
+    num_panels: numPanels,
+    num_cols: numCols,
+    titles,
+    fig_title: figTitle,
+    colorbar_mode: colorbarMode,
+    initial_index: initialIndex,
+    slice_label: sliceLabel,
+  } = data;
+
+  // WebP with an alpha channel: values the colormap marks "bad" (NaN, and so
+  // anything masked out by `zeros_as_nan`) are transparent rather than a
+  // colour, so the panel background shows through in both light and dark.
+  const urls = frames.map((slice) =>
+    slice.map((b64) => URL.createObjectURL(new Blob([b64ToBytes(b64)], { type: "image/webp" }))),
+  );
+
+  const viewer = document.createElement("div");
+  viewer.className = "mnu-viewer mnutils-image-grid";
+
+  if (figTitle) {
+    const heading = document.createElement("div");
+    heading.className = "mnutils-image-grid-title";
+    heading.textContent = figTitle;
+    viewer.append(heading);
+  }
+
+  const panel = document.createElement("div");
+  panel.className = "mnu-panel mnutils-image-grid-panel";
+
+  const grid = document.createElement("div");
+  grid.className = "mnutils-image-grid-cells";
+  // The column count is nominal: the CSS wraps to fewer columns when the pane
+  // is too narrow for them, and caps the widget's width so a wide pane doesn't
+  // fit more. Rows are not counted -- however many they come to, the panel box
+  // scrolls once they outgrow it.
+  const cols = Math.min(numCols, numPanels);
+  viewer.style.setProperty("--mnu-grid-cols", String(cols));
+
+  const images = [];
+  const colorbars = [];
+  for (let p = 0; p < numPanels; p++) {
+    const cell = document.createElement("figure");
+    cell.className = "mnutils-image-grid-cell";
+
+    const img = document.createElement("img");
+    img.className = "mnutils-image-grid-image";
+    img.src = urls[initialIndex][p];
+    img.alt = titles[p] ? `Panel: ${titles[p]}` : `Panel ${p + 1}`;
+    images.push(img);
+    cell.append(img);
+
+    if (titles[p]) {
+      const caption = document.createElement("figcaption");
+      caption.className = "mnutils-image-grid-caption";
+      caption.textContent = titles[p];
+      cell.append(caption);
+    }
+
+    if (colorbarMode === "each") {
+      const cbar = makeColorbar(stops);
+      colorbars.push(cbar);
+      cell.append(cbar.wrap);
+    }
+
+    grid.append(cell);
+  }
+
+  panel.append(grid);
+
+  if (colorbarMode === "single") {
+    const cbar = makeColorbar(stops);
+    cbar.wrap.classList.add("mnutils-image-grid-cbar-shared");
+    colorbars.push(cbar);
+    panel.append(cbar.wrap);
+  }
+
+  // Low-resolution data should look like the grid of values it is. Once a
+  // frame is drawn wider than its own pixel count the browser's smooth
+  // upscaling turns a 20x20 array into a blur, so those get `pixelated`;
+  // frames being scaled *down* keep the smooth default, where nearest
+  // -neighbour would only alias. Rechecked on resize, since which side of
+  // 1:1 a panel falls on depends on the width it ends up with.
+  const syncPixelation = () => {
+    for (const img of images) {
+      if (!img.naturalWidth) continue;
+      img.style.setProperty(
+        "--mnu-image-rendering",
+        img.getBoundingClientRect().width > img.naturalWidth ? "pixelated" : "auto",
+      );
+    }
+  };
+
+  // The frames' aspect ratio decides how wide the panels want to be, and so
+  // how wide the whole widget is allowed to grow (see --mnu-panel-w-cap).
+  // Only measurable once a frame has decoded, hence the load handler.
+  const syncAspect = () => {
+    const img = images.find((candidate) => candidate.naturalWidth);
+    if (img) viewer.style.setProperty("--mnu-aspect", String(img.naturalWidth / img.naturalHeight));
+  };
+
+  for (const img of images) {
+    img.addEventListener("load", () => {
+      syncAspect();
+      syncPixelation();
+    });
+  }
+  if (typeof ResizeObserver === "function") new ResizeObserver(syncPixelation).observe(grid);
+
+  const showSlice = (idx) => {
+    for (let p = 0; p < numPanels; p++) images[p].src = urls[idx][p];
+    // "single" has one bar for the whole grid, so panel 0's bounds are the
+    // grid's bounds -- with a shared colorbar every panel shares them anyway.
+    colorbars.forEach((cbar, i) => cbar.setBounds(bounds[idx][colorbarMode === "each" ? i : 0]));
+  };
+  showSlice(initialIndex);
+
+  // A panel's edge is invisible wherever the data is NaN, since those pixels
+  // are transparent -- which makes a mostly-masked image look like it has an
+  // arbitrary shape. The border draws the frame's real extent back in, off by
+  // default because it is clutter on an image that fills its own bounds.
+  const { toggle } = makeToggle({
+    label: "Border",
+    checked: false,
+    onChange: (on) => grid.classList.toggle("is-bordered", on),
+  });
+
+  // A single-slice stack has nothing to scrub, so it gets a bar with just the
+  // toggle rather than a disabled slider whose only honest readout is "0 of 0".
+  const controls = [];
+  if (nSlices > 1) {
+    const { lbl, slider, readout } = makeSliceSlider({
+      min: 0,
+      max: nSlices - 1,
+      value: initialIndex,
+      label: sliceLabel,
+      formatReadout: (idx) => String(idx),
+      onInput: showSlice,
+    });
+    // Reserve the readout's full width up front, sized to the largest index
+    // it will ever show -- otherwise a 3-digit slice count only grows the bar
+    // past its wrap threshold once the slider is dragged there, so the layout
+    // shifts mid-scrub instead of on load.
+    readout.style.minWidth = `${String(nSlices - 1).length}ch`;
+    controls.push(makeGroup(lbl, readout), slider);
+  }
+  const bar = makeBar(...controls, toggle);
+  bar.classList.add("mnutils-image-grid-bar");
+  viewer.append(bar);
+
+  viewer.append(panel);
+  el.append(viewer);
+}
+
+export default renderWidget;

mnutils/plotting/_widgets/image_grid.py

@@ -0,0 +1,86 @@
+import base64
+from pathlib import Path
+from typing import Any
+
+from ._html import render_html
+from ._shared import load_css, load_esm
+
+_DIR = Path(__file__).parent
+_JS = load_esm(_DIR / "image_grid.js")
+_CSS = load_css(_DIR / "image_grid.css")
+
+
+class ImageGridWidget:
+    """Grid of pre-rendered image panels with one shared slice slider.
+
+    The panels arrive as bare rasters -- no titles, no colorbar, no axes --
+    because they were produced by `plotting.images` straight from PIL rather
+    than from a matplotlib `Figure`. Everything that used to be drawn *around*
+    the pixels is rebuilt here as DOM: the figure title as a heading, each
+    panel's title as a `<figcaption>`, and the colorbar as a CSS gradient
+    strip with text ticks. That keeps the text sharp at any zoom and lets a
+    slice change rewrite a couple of text nodes instead of a whole raster.
+
+    Like every widget in this package the payload is baked in at construction,
+    so the slider keeps working in a statically built docs page with no kernel
+    behind it.
+
+    Parameters
+    ----------
+    frames : list[list[bytes]]
+        Encoded panel images, slice-major: ``frames[slice_idx][panel_idx]``.
+    bounds : list[list[tuple[float, float]]]
+        The ``(vmin, vmax)`` the matching frame was normalised with, same
+        indexing as `frames`. Only read when a colorbar is shown, but always
+        per slice, since ``colorbar_mode="each"`` autoscales every panel on
+        every slice.
+    colormap_stops : list[str]
+        The colormap sampled to CSS hex colors, low to high; interpolated into
+        a `linear-gradient` for the colorbar strip.
+    num_cols : int
+        Panels per row.
+    titles : list[str]
+        Per-panel captions. May be shorter than the number of panels (a panel
+        without a title simply gets none).
+    fig_title : str
+        Heading above the whole grid; omitted when empty.
+    colorbar_mode : str
+        ``"single"`` for one strip under the grid, ``"each"`` for a strip per
+        panel, ``""`` for none.
+    initial_index : int, optional
+        Slice shown on first display, by default 0.
+    slice_label : str, optional
+        Label next to the slider, by default ``"Slice"``.
+    """
+
+    def __init__(
+        self,
+        frames: list[list[bytes]],
+        bounds: list[list[tuple[float, float]]],
+        colormap_stops: list[str],
+        num_cols: int,
+        titles: list[str] | None = None,
+        fig_title: str = "",
+        colorbar_mode: str = "",
+        initial_index: int = 0,
+        slice_label: str = "Slice",
+    ) -> None:
+        self._data: dict[str, Any] = {
+            "frames": [
+                [base64.b64encode(panel).decode("ascii") for panel in slice_frames]
+                for slice_frames in frames
+            ],
+            "bounds": [[list(panel) for panel in slice_bounds] for slice_bounds in bounds],
+            "colormap_stops": colormap_stops,
+            "n_slices": len(frames),
+            "num_panels": len(frames[0]) if frames else 0,
+            "num_cols": num_cols,
+            "titles": titles if titles else [],
+            "fig_title": fig_title,
+            "colorbar_mode": colorbar_mode,
+            "initial_index": initial_index,
+            "slice_label": slice_label,
+        }
+
+    def _repr_html_(self) -> str:
+        return render_html(_JS, _CSS, self._data)