anyplotlib 0.1.0b1__tar.gz → 0.3.0b1__tar.gz

{anyplotlib-0.1.0b1 → anyplotlib-0.3.0b1}/CHANGELOG.rst

@@ -10,6 +10,148 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.3.0b1 (2026-07-13)
+====================
+
+New Features
+------------
+
+- Added :class:`~anyplotlib.widgets.ArrowWidget` (draggable arrow overlay, tail
+  at ``(x, y)`` and head at ``(x + u, y + v)``) via ``Plot2D.add_arrow_widget`` /
+  ``add_widget("arrow")``, and a ``show_handles`` option (default ``True``) on
+  every 2-D overlay widget to hide the grab-handle dots without affecting drag.
+- Added figure-level edit-mode chrome to :class:`~anyplotlib.Figure`: the
+  ``edit_chrome`` and ``selected_panel`` traits (per-panel hover / selection
+  outlines), figure-background click events, and a figure-level annotation layer
+  (``set_figure_markers`` / ``figure_markers``, positioned in figure fractions and
+  always included in ``exportPNG``) with figure-level callbacks via
+  ``add_event_handler``.
+- Extended :class:`~anyplotlib.Figure` edit-mode interaction:
+
+  * Circle and rectangle overlay widgets are now **resizable via visible nodes** —
+    a circle draws a centre (move) node and an east-point radius node; a rectangle
+    draws all four corner nodes (opposite corner anchored on drag).  Drawn only
+    when ``show_handles`` is ``True``, with matching resize cursors.
+  * :class:`~anyplotlib.widgets.ArrowWidget` **tail is now a reshape node**:
+    dragging the tail moves it while the head stays anchored (dragging the shaft
+    still moves the whole arrow; the head node still re-aims it).
+  * The selected-panel and hover **outlines are fully inset** (``outline-offset:
+    -2px``) so an edge/corner panel's ring is no longer clipped at the figure's
+    right/bottom edge.
+  * **Panel drag-swap** under ``edit_chrome``: each grid panel shows a move grip
+    in its top-left corner; dragging it over a *different* panel emits a
+    figure-level ``pointer_up`` event with ``panel_swap: true`` and
+    ``source_panel_id`` / ``target_panel_id`` (new :class:`~anyplotlib.Event`
+    fields).  anyplotlib performs no layout change itself — the host swaps and
+    rebuilds.  Releasing on the source panel or empty space cancels cleanly; the
+    grip is inert when ``edit_chrome`` is off.
+  * The JS ``mount()`` embedding entry point accepts an ``onResize({width,
+    height})`` callback, fired (debounced) when the **root container resizes**, so
+    an embedding host can relayout the figure to its new box.
+
+
+0.2.0 (2026-07-10)
+==================
+
+New Features
+------------
+
+- 2-D scalar images can now render on the **GPU via WebGPU** (``imshow(...,
+  gpu="auto"|True|False)``): the image uploads as an R8 texture and a WGSL fragment
+  shader applies the colormap LUT + contrast (clim) in one draw, replacing the
+  per-pixel JavaScript colormap loop. Large images (≳1 megapixel) take the GPU path
+  automatically; everything below the threshold, RGB images, ``gpu=False``, and any
+  device without WebGPU keep the identical Canvas2D path. ``plot.gpu_active`` reports
+  which path ran. Verified on an NVIDIA Pascal GPU.
+- Arbitrarily large images can now display through **tile mode**
+  (``imshow(..., tile="auto")``): the figure shows a downsampled overview as its
+  base and, after each zoom/pan settles, samples a high-resolution detail tile of
+  just the visible region at panel resolution — deep zooms stay crisp without
+  ever shipping the full-resolution frame. ``Plot2D.enable_tile`` /
+  ``update_tile_source`` swap the underlying frame while the zoom and
+  subselection persist (live-data contract), and a pluggable ``TileBackend``
+  (default: a fast vectorised numpy box-mean) lets out-of-core or GPU sources
+  own the sampling.
+- Markers gained a ``clip_display`` option controlling whether they draw
+  outside the current axes view or are clipped to it.
+- ``set_extent`` now updates the axes state (calibrated units / scale bar), so
+  applying a calibrated extent after figure creation renders labelled axes
+  instead of bare pixels.
+- Regular ``pcolormesh`` meshes are detected and rasterized to an image for
+  display (fast IPF-style heatmaps) instead of drawing per-quad.
+
+
+Bug Fixes
+---------
+
+- Fixed a display freeze under the Electron binary pixel transport: the routing
+  layer stripped the pixel key out of the slimmed geom JSON, so the renderer's
+  "unchanged → skip re-upload" caches (Canvas2D blit cache, WebGPU texture,
+  overlay-mask cache) fell back to a 4-sampled-byte fingerprint of the buffer —
+  two frames differing anywhere else collided and the display stayed frozen on
+  the old frame (seen as a stale overview after a movie scrub). The slimmed geom
+  now carries a small ``\x00bin:<checksum>`` content token under the pixel key,
+  binary buffers are additionally stamped with an arrival sequence as a fallback
+  key, and the overlay-mask draw path now reads the binary byte side-channel
+  (it previously only decoded base64, so masks never displayed over the binary
+  transport).
+- Fixed the WebGPU 2-D image path sampling a vertically MIRRORED window when the
+  view was panned off-centre: the shader applied a global ``1 - v`` flip after
+  interpolating the ``[v0, v1]`` uv window, which sampled ``[1-v1, 1-v0]``
+  instead — correct only for a full or vertically-centred view. Symptoms: pan-y
+  moved the image the wrong way on GPU-rendered panels, and markers/widgets
+  (drawn by the shared Canvas2D overlay transform, which was always correct)
+  appeared detached from the image features they marked. The base and
+  detail-tile passes share the shader, so both are fixed. GPU-vs-CPU screenshot
+  parity tests (zoom, pan, markers, widgets, detail tile) now run on real WebGPU
+  in headless Chromium (``channel="chromium"`` + ``--enable-unsafe-webgpu``) and
+  skip on machines with no adapter.
+- ``Plot2D.set_data`` no longer makes a float64 copy of every incoming frame.
+  The float64 cast now happens lazily in the ``.data`` property (the only reader),
+  so a frame stream — e.g. scrubbing an in-situ movie — keeps the source dtype and
+  skips a ~12 ms float64 copy of a 4k frame per tick. ``.data`` still returns a
+  read-only float64 copy, unchanged for callers.
+- The Electron binary pixel transport now ships the RAW uint8 image bytes end to
+  end, instead of base64-encoding them in ``set_data`` only to base64-decode them
+  straight back in the routing layer. ``Plot2D.set_data`` stashes the raw bytes on
+  the Figure's ``_raw_pixels`` side-table and leaves a tiny content-checksum
+  change-token in ``image_b64``; ``_electron._route_change`` ships those bytes to a
+  PLOTBIN frame directly. This removes the ~20 ms base64 encode, the ~17 ms decode,
+  and the megabyte ``json.dumps`` of the pixel string from every scrub frame — a
+  2.2x faster ``set_data`` (≈98 ms → ≈44 ms on a 2048² frame) and ~25% less
+  bytes-on-wire. Non-Electron hosts (Jupyter / Pyodide / standalone / ``save_html``)
+  are unchanged: they have no PLOTBIN channel, so the token is resolved back to
+  inline base64 via ``Plot2D.resolve_pixel_tokens`` when the figure state is
+  serialised for them.
+- Tile mode: a data update while zoomed in (``update_tile_source`` with a detail
+  tile shown) refreshes only the detail tile, leaving the overview base on the
+  old frame — zooming out then flashed the pre-update frame. The skipped
+  overview is now marked stale and re-sampled once on the next view settle
+  (riding the same push as the detail/clear), preserving the per-frame skip
+  optimisation while never exposing stale base pixels.
+- Interactive zoom/pan on a 2-D image no longer re-serialises (and re-transmits)
+  the full image on every mouse tick. The wheel/pan/orbit handlers write only the
+  light *view* state back to the ``panel_<id>_json`` trait now, excluding the
+  cached geometry (pixels, colormap LUT) that ``_applyGeom`` splices into the panel
+  state for drawing. Previously the whole frame was ``JSON.stringify``-d per tick —
+  catastrophically so on the binary transport, where the pixel buffer is a
+  ``Uint8Array`` that stringifies to a ``{"0":..,"1":..}`` object with one key per
+  byte — which stalled zoom on large images.
+- Fixed a first-paint race under the Electron binary transport: binary
+  side-table bytes that arrived before ``render()`` attached its listeners were
+  stranded, leaving the first frame blank until the next update — they are now
+  spliced into the initial paint.
+
+
+Maintenance
+-----------
+
+- ``anyplotlib.__version__`` is now exposed from the package metadata.
+- Per-frame hot-path costs trimmed: the colormap LUT is cached instead of being
+  rebuilt every frame (~100 ms), and small-range data rescales in float32
+  (~60 ms → ~27 ms per 2048² frame).
+
+
 0.1.0 (2026-06-24)
 ==================
 

anyplotlib-0.3.0b1/LARGE_IMAGE_WEBGPU_PLAN.md

@@ -0,0 +1,223 @@
+# Large-image WebGPU 2D rendering + binary transport — scoping document
+
+Status: **Phase 0 + core Phase 1/2 DONE, hardware-verified** (2026-07-06). Branch:
+`feat/webgpu-2d-images`. Owner: @CSSFrancis
+
+## DONE (verified on an NVIDIA Pascal GPU via the SpyDE Electron consumer)
+- **WebGPU 2-D image render path**: a `gpuCanvas` below `plotCanvas`; the normalized
+  uint8 frame → R8 texture, the 256-entry colormap → a 256×1 RGBA LUT texture, a
+  fullscreen-quad WGSL fragment shader re-stretches by clim (dmin/dmax uniform) and
+  samples the LUT. Replaces the 64M-iteration Canvas2D atob+LUT loop with one GPU draw.
+- **Reuses the 3D contract**: the `_gpuDevice()` singleton, first-frame-canvas-then-
+  async-swap, `device.lost` → permanent Canvas2D fallback (extended to 2-D panels).
+- **API**: `imshow(..., gpu="auto"|True|False)` → `gpu_mode`; `GPU_IMAGE_THRESHOLD`
+  (~1 Mpx) auto-gate; `plot.gpu_active` echo via the `gpu_status` event.
+- **Fallback intact**: RGB images, sub-threshold images, `gpu=False`, and no-device
+  all render on Canvas2D (anyplotlib suite green; the DOM keeps `plotCanvas` first so
+  `querySelector('canvas')` still resolves the image canvas).
+- **Correctness (review-hardened)**: the shader is a plain IDENTITY LUT lookup —
+  `_buildLut32` already bakes clim + scale_mode into the LUT, so the shader must NOT
+  re-apply the window (an earlier version double-applied clim; correct only at
+  full-range, wrong for any narrowed contrast/log/symlog — fixed). A zoomed/panned
+  view falls back to Canvas2D so the base image stays registered with the axes/
+  overlays (the GPU quad is full-extent). Nearest sampling on both textures matches
+  Canvas2D's `imageSmoothingEnabled=false` pixel-for-pixel.
+- **Zoom/pan v-window fix + headless GPU parity tests (2026-07-09)**: the shader
+  applied a global `1 - v` flip AFTER interpolating the `[v0,v1]` window, sampling
+  the MIRRORED window `[1-v1, 1-v0]` — correct only when v0+v1==1 (rest / centred
+  zoom), so it survived the readback tests but inverted pan-y and detached the
+  image from markers/overlays on any vertically off-centre view (base AND detail
+  passes; fixed by interpolating v from v1 at the screen bottom to v0 at the top).
+  Guarded by `tests/test_plot2d/test_gpu_parity_playwright.py`: GPU-vs-Canvas2D
+  PNG parity (rest/zoom/pan/markers/widgets/detail-tile) on REAL WebGPU in
+  headless Chromium — `channel="chromium"` (the full build; the default headless
+  shell has no `navigator.gpu`) + `--enable-unsafe-webgpu`, skipped when no
+  adapter. NB `page.screenshot()` DOES capture the WebGPU canvas there; the
+  "swapchain reads black" caveat below applies to Electron offscreen capture.
+- **Verification**: `__apl_gpuReadback` renders the active panel to an OFFSCREEN
+  texture (the live swapchain reads black under automation) and copies it to CPU.
+  On a real 4k movie frame: min 0 / max 255 / 96% non-black / correct gray values.
+  A **narrowed clim [0.3,0.7]** matches the numpy windowed-colormap to meanDiff
+  0.65/255 (regression guard for the double-apply bug; `tests/_gpu_clim_check.cjs`).
+  Movie scrub + playback re-upload the texture per frame and stay correct (5/5
+  scrub, 5 distinct played frames). GPU resources are freed on panel close / figure
+  dispose / device loss (no leak on repeated large-image open/close).
+
+## DEFERRED (documented; not blockers now)
+- **Mipmaps** (smooth downscale-on-zoom): the sampler uses `minFilter:'linear'`
+  without a mip chain. Marginal here because LOD already caps the uploaded texture
+  near display size; matters for deep zoom-out. Needs an R8 render-based mip chain.
+- **Binary pixel transport** (base64-in-JSON → binary buffer): the Phase-0 headline,
+  but LOD decimation already cut the shipped payload ~35× (≤1536 px, ~2 MB not
+  ~85 MB) and the GPU shader removed the render cost, so this is now an incremental
+  transport optimization spanning Jupyter/Pyodide/standalone/Electron — do it with
+  the multi-environment verification it needs.
+
+Prerequisite reading: `WEBGPU_PLAN.md` (the 3D points/voxels WebGPU path this extends),
+`anyplotlib/FIGURE_ESM.md` (the `figure_esm.js` section map), `AGENTS.md` (repo conventions).
+Prerequisite reading: `WEBGPU_PLAN.md` (the 3D points/voxels WebGPU path this extends),
+`anyplotlib/FIGURE_ESM.md` (the `figure_esm.js` section map), `AGENTS.md` (repo conventions).
+
+This extends the repo's existing hardware-verified `WEBGPU_PLAN.md` (3D instanced points +
+voxels) to **2D large images**, deliberately lifting that doc's "No 2D pipeline changes"
+non-goal (§2). Motivating consumer: a SpyDE in-situ movie viewer that must scrub/play through
+8k×8k image frames smoothly.
+
+## 1. Goal
+
+Render **large 2D image frames** (up to 8k×8k) interactively — smooth scrub/playback of a
+frame stream and smooth zoom — by moving the 2D image path from Canvas2D to **WebGPU** (texture
+upload + WGSL colormap LUT + mipmap downscale) and moving the pixel bytes off **base64-in-JSON**
+onto a **binary transport**.
+
+| Workload | Today (Canvas2D) | Target (WebGPU) |
+|---|---|---|
+| 8k×8k frame colormap+draw | ~64M-iter JS LUT loop → OffscreenCanvas | shader LUT, **<5 ms** |
+| Scrub (new frame/tick) | ~85 MB base64/frame + full rebuild | binary uint8 + texture upload, **≥15–30 fps** |
+| Zoom-in on a still | re-blit from OffscreenCanvas | GPU **mipmap**, **60 fps** |
+
+## 2. Non-goals
+
+- **Not** replacing Canvas2D for images — it stays the universal baseline, the fallback, the
+  small-image path, and the fully-CI-tested path. Default behaviour for small images is
+  byte-identical to today.
+- No WebGL2, no three.js, no bundler — raw WebGPU + inline WGSL, mirroring `WEBGPU_PLAN.md`.
+- 1D lines / bars stay Canvas2D. Only the 2D **image** path is affected.
+
+## 3. Coverage & the fallback contract
+
+Inherited verbatim from `WEBGPU_PLAN.md` §3: WebGPU is a progressive enhancement. `navigator.gpu`
+present → `requestAdapter()` resolves → device created → *then* a panel may switch. Any failure at
+any point (including mid-session device loss) lands on the Canvas2D path silently and permanently
+for that session. **A figure must never render nothing because GPU was attempted.**
+
+## 4. Reuse (do NOT rebuild)
+
+- **Device singleton + fallback state machine**: `_gpuDevice()` (`figure_esm.js` ~L1955,
+  module-level `_gpuDevicePromise`), the `p._gpu ∈ {pending,active,unavailable}` per-panel state,
+  the "first frame always Canvas2D → swap on device resolve" pattern, and `device.lost` → permanent
+  per-session Canvas2D. All proven by the 3D path — the 2D image path plugs into the exact same
+  machinery.
+- **The `gpuCanvas`-below-`plotCanvas` split**: decorations (axes, ticks, colorbar, scale bar,
+  overlay mask, markers, widgets) keep drawing on the 2D `plotCanvas` **verbatim** — only the image
+  raster moves to `gpuCanvas`. Mirrors `WEBGPU_PLAN.md` §4.3.
+- **`gpu_mode` / `_gpu_active` plumbing**: the state field + echo already exist (`st.gpu_mode`,
+  ~L1998). Add an image-megapixel `GPU_IMAGE_THRESHOLD` alongside the existing point threshold.
+- **The zoom/letterbox model**: `_imgFitRect` (~L1262) — the GPU draw honors the same fit-rect /
+  `zoom` semantics; no new zoom math.
+- **The colormap LUT**: `_build_colormap_lut` (`_utils.py:118`) → `st.colormap_data`
+  ([[r,g,b]×256]) already ships to JS. Upload it as a 256×1 texture; the shader samples it.
+- **The normalized payload**: `set_data` already produces `img_u8` (single-channel uint8 via
+  `_normalize_image`, `_utils.py:82`) + `display_min/max` (clim) + `raw_min/max`. The WebGPU path
+  uploads that **same uint8** (8× smaller than raw float64; keeps current visual behaviour) as an
+  **R8 texture**; the shader does the clim re-stretch + LUT — exactly what the JS loop at
+  `draw2d` L1379–1381 does today, but on the GPU.
+
+## 5. The function being replaced
+
+`draw2d` (`figure_esm.js` ~L1344): today it `atob`-decodes `image_b64`, runs a per-pixel LUT loop
+(L1379–1381, 64M iters at 8k) into an `OffscreenCanvas` 2D context, caches the bitmap in
+`blitCache`, and `_blit2d`-down-blits to the panel. The WebGPU path replaces the decode+LUT+blit
+with: upload R8 texture → WGSL fragment shader (clim uniform + LUT texture) → mipmapped textured
+quad over the `_imgFitRect`. `blitCache`'s "bytes unchanged → reuse" logic maps to "texture
+unchanged → skip re-upload". Canvas2D `draw2d` remains as the fallback when `p._gpu !== 'active'`.
+
+## 6. Binary transport (generalize `WEBGPU_PLAN.md` §4.7 to images)
+
+Today `set_data` → `_encode_bytes(img_u8)` → `image_b64` string on the `panel_<id>_geom` trait
+(base64-in-JSON). Change: send the raw `img_u8` **bytes** as an anywidget **binary buffer**
+(`_repr_utils._widget_state` already handles `bytes`; the geom-trait split already isolates heavy
+keys — `FIGURE_ESM.md` ~L237), with a small JSON header (`image_width/height`, `display_min/max`,
+`raw_min/max`, dtype, an optional `lod` level). Keep base64 for **small images and the
+standalone/Pyodide/`save_html` paths** (no binary channel there). Keep `FigureBridge` (`embed.py`)
+transport-agnostic so an Electron embed can supply an even faster channel (shared memory / a
+transferable `ArrayBuffer`) without the library caring. JS: pick up the binary buffer, upload to
+the GPU texture; on the Canvas2D fallback, build the `ImageData` from the same bytes (no atob).
+
+## 7. API surface
+
+- `Axes.imshow(..., gpu="auto"|True|False)` and `Plot2D.set_data(..., gpu=...)` — mirror
+  `scatter3d`/`voxels`. Default `"auto"`: attempt WebGPU only above `GPU_IMAGE_THRESHOLD`
+  (initial ~4 megapixels — below it Canvas2D is already instant). `True` forces an attempt (still
+  falls back); `False` never attempts.
+- `plot.gpu_active` — bool echo after first render (reuse `_gpu_active`).
+- Optional `set_data(..., lod=k)` affordance so a consumer can mark a frame as decimated (scrub)
+  vs full-res (settle); at minimum, an uploaded full-res texture gets **free** GPU downscale-on-zoom
+  via mipmaps, so LOD-on-zoom needs no consumer work.
+
+## 8. Phases (with decision gates, mirroring WEBGPU_PLAN.md style)
+
+### Phase 0 — Binary transport + minimal GPU texture-blit (risk-retire; do first)
+
+Add the binary image trait + header (keep b64 fallback). Add a minimal WebGPU 2D image pipeline:
+R8 texture + 256×1 LUT texture + clim uniform + a textured quad over `_imgFitRect`, **no mipmaps
+yet**. Verify a single static 8k image renders identically to Canvas2D via **offscreen-texture
+readback** (the 3D path's proven test method — the WebGPU swapchain doesn't snapshot reliably under
+automation, per `FIGURE_ESM.md` ~L256).
+
+**Gate A:** GPU image matches Canvas2D within tolerance on a real GPU, and `gpu=False`/adapter-absent
+renders identically via Canvas2D (automated).
+
+### Phase 1 — Mipmaps + zoom + scrub
+
+Generate mipmaps on upload; sample with trilinear filtering so zoom-out/downscale is smooth and
+zoom-in honors `_imgFitRect`. Wire the scrub path: new bytes → texture re-upload (reuse
+`blitCache`-style "unchanged → skip").
+
+**Acceptance:** 8k still zooms at 60 fps; a frame stream scrubs ≥15–30 fps on a real GPU; benchmark
+`js_gpu_image_8k` recorded.
+
+### Phase 2 — API + fallback hardening + tests
+
+`gpu="auto"|True|False` on `imshow`/`set_data`, `GPU_IMAGE_THRESHOLD`, `plot.gpu_active`, optional
+`lod=`. Canvas2D-parity tests in the normal suite (assert `_gpu_active` false + pixel parity when
+GPU absent); flagged headless-GPU smoke job (skip-on-null-adapter); `upcoming_changes/*.rst`
+towncrier fragment.
+
+**Gate B:** full fallback matrix green (adapter-absent, mid-session device loss via forced
+`device.destroy()`, `gpu=False`) + real-GPU image benchmark, before this is released.
+
+### Phase 3 (gated) — raw-float precision path
+
+If uint8 quantization proves visibly lossy for scientific contrast adjustment, add an optional R32F
+texture upload (raw floats, 4× bytes) with the clim applied in-shader over true data range. Only
+build on a concrete need (Gate C).
+
+## 9. Biggest risks / do-not-break
+
+- **The 3D WebGPU path and the Canvas2D 2D path must not regress** — the 2D image GPU path is
+  additive and plugs into the shared `_gpuDevice()` singleton; keep the device/fallback code shared,
+  not forked.
+- **Canvas2D stays the default + fallback forever** — no figure may render nothing because GPU was
+  attempted (the `WEBGPU_PLAN.md` §3 contract).
+- **Automation can't snapshot the WebGPU swapchain** — test via offscreen-texture readback or state
+  echo, not screenshot diffing of the live canvas (per `FIGURE_ESM.md`).
+- **Small-image / standalone / Pyodide paths unchanged** — binary transport is large-image-only;
+  b64 remains for the rest.
+- Repo norms (`AGENTS.md`): OO API only, state in `_state` dicts (no new traitlets on Plot2D — the
+  Figure adds panel traits dynamically), end every `_state` mutation with `_push()`, `uv run
+  pytest`, `uv run playwright install chromium` first, add the towncrier fragment.
+
+## 10. Verify
+
+`uv run pytest` (Canvas2D parity + fallback in the normal suite); the flagged GPU smoke job;
+offscreen-readback comparison GPU-vs-Canvas2D on a large image; `js_gpu_image_8k` benchmark on a
+real-GPU machine; a manual Electron-embed pass (the real consumer) once SpyDE pins the new version.
+
+## 11. API sketch
+
+```python
+# Python
+plot = ax.imshow(frame, gpu="auto")     # auto-attempt WebGPU above GPU_IMAGE_THRESHOLD
+plot.set_data(next_frame, clim=(lo, hi))  # scrub: binary bytes → texture re-upload
+plot.set_data(decimated, lod=2)          # scrub-time LOD hint (optional)
+plot.gpu_active                          # bool, after first render echo
+```
+
+```js
+// JS internals (figure_esm.js)
+_gpuDevice()                 // existing module singleton → Promise<GPUDevice|null>
+p._gpu                       // 'pending' | 'active' | 'unavailable' (existing)
+_buildImagePipeline(device, p)   // NEW: R8 sampled texture + LUT texture + clim uniform
+_drawGpu2d(p)                    // NEW: image raster on gpuCanvas; decorations still 2D via draw2d
+```

{anyplotlib-0.1.0b1 → anyplotlib-0.3.0b1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anyplotlib
-Version: 0.1.0b1
+Version: 0.3.0b1
 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.1.0b1 → anyplotlib-0.3.0b1}/anyplotlib/FIGURE_ESM.md

@@ -63,6 +63,8 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 | `drawScaleBar2d` / `drawColorbar2d` | 1360 / 1436 |
 | `_drawAxes2d` (ticks, labels, title) | 1491 |
 | `drawOverlay2d` / `drawMarkers2d` | 1629 / 1685 |
+| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 1553 / 1577 / 1629 |
+| Binary-bytes splice: `_spliceBinaryBytes` / `_registerBinaryPixelListeners` | 675 / 706 |
 | **3D drawing**: `draw3d` | 1833 |
 | Event emission `_emitEvent` | 2031 |
 | 3D event handlers `_attachEvents3d` | 2059 |
@@ -134,7 +136,66 @@ geometry changes (visibility, label, sizes) re-layout automatically.
 #### `applyLayout()` (line 590)
 Reads `layout_json`. Builds CSS grid tracks from `panel_specs[].panel_width/height`.
 Creates panels that don't exist yet, resizes existing ones, removes stale ones.
-Also creates/updates inset panels from `inset_specs`.
+Also creates/updates inset panels from `inset_specs`, then draws region
+indications from `layout.indications` (on the next frame — see below).
+
+#### Inset placement (`_applyAllInsetStates`)
+Each `inset_specs[]` entry carries EITHER `corner` (one of the four corners;
+`anchor` is `null`) OR `anchor` (`[x_frac, y_frac]` of the inset's top-left in
+figure fraction; `corner` is `null`). Corner insets stack per-corner with
+`INSET_GAP`; anchored insets are placed directly at their fraction (clamped
+inside the figure). Minimize / maximize / restore work for both — a maximized
+inset floats centred at ~72 % (z 45); a minimized one collapses to its title
+bar in place.
+
+#### Region indications (callouts — `_drawCallouts`)
+`layout.indications` is an array of mark_inset-style callouts, each
+`{inset_id, parent_id, region:[x,y,w,h], color, linestyle, linewidth}`.
+`_drawCallouts()` renders them onto a figure-level `calloutCanvas` (z 30, above
+panels + insets, below maximized-inset float and the resize handle,
+`pointer-events:none`):
+- The **dashed source rect** maps `region` (parent DATA coords) through the
+  parent's `_imgToCanvas2d` every draw, so it tracks the parent's zoom/pan; it
+  is clipped to the parent's image area.
+- Two **leader lines** connect the rect's corners facing the inset to the
+  inset's nearest corners (loc1/loc2-auto by comparing centres); they follow
+  the inset's live DOM rect and are **hidden while the inset is minimized**.
+
+`_drawCallouts()` is called at the end of `_redrawPanel` / `redrawAll` (tracks
+zoom/pan), at the end of `_applyAllInsetStates` (inset moved), on `applyLayout`
+(deferred one rAF so `getBoundingClientRect` is real), and inside `exportPNG`
+(forced fresh draw, then `calloutCanvas` composited last). All coordinates go
+through element bounding rects relative to the callout canvas, so no layout math
+is duplicated. Cheap no-op when `indications` is empty (just clears the canvas).
+The `if (!parent || !parent.state || !inset || !inset.isInset) continue;` guard
+per indication is defensive/permanent — kept even though a foreign-figure
+`parent_plot` can no longer reach this array at all (see validation below); it
+still protects against other edge cases (e.g. a panel mid-teardown).
+
+**`InsetAxes.indicate_region(parent_plot, region, …)` validates both arguments**
+before recording an indication: `parent_plot` must be a panel registered on
+THIS inset's own `Figure` (`self._fig._plots_map.get(pid) is parent_plot` —
+not just "has some `_id`", which is the pre-existing check for "never attached
+to any figure") — a plot that belongs to a *different* `Figure` raises
+`ValueError`. `region` must be exactly 4 finite numbers `(x, y, w, h)` with
+`w > 0` and `h > 0` — `NaN`/`inf`, a degenerate/negative size, or the wrong
+number of values raises `ValueError`. A region that extends OUTSIDE the
+parent's data bounds is explicitly **allowed** (clipping is a visual concern
+handled by `_drawCallouts`'s clip-to-image-area, not a validation error). See
+`test_indicate_region_foreign_figure_parent_raises`,
+`test_indicate_region_foreign_inset_parent_raises`,
+`test_indicate_region_degenerate_region_raises`, and
+`test_indicate_region_out_of_bounds_is_allowed` in
+`tests/test_layouts/test_inset_callout.py`.
+
+**Inset removal**: as of this writing there is no `remove_inset` (or
+equivalent) API — `Figure._insets_map` / `_plots_map` are only ever appended
+to, never deleted from, so `indications` (rebuilt fresh from `_insets_map` on
+every `_push_layout()` call) cannot go stale from a removed inset today. If a
+removal API is added later, it MUST also delete the inset's entry from both
+maps — otherwise `layout.indications` would keep emitting an entry whose
+`inset_id` no longer resolves to a live panel (caught by the `_drawCallouts`
+guard above, but a dangling entry all the same).
 
 #### `_createPanelDOM(id, kind, pw, ph, spec)` (line 763)
 Builds all canvas/DOM elements for one panel (via `_buildCanvasStack`),
@@ -196,6 +257,111 @@ inverses of the blit geometry.
 
 ---
 
+## Image layers (multi-image overlay)
+
+`Plot2D.add_layer(data, cmap=, alpha=, clim=, visible=)` composites a second
+(third, …) scalar image OVER the base image in the same panel, each with its own
+colormap / clim / alpha. Distinct from `set_overlay_mask` (single-colour boolean
+mask). `Layer.set(...)`, `Layer.set_data(frame)`, `Layer.remove()`,
+`Plot2D.layers`, `Plot2D.remove_layer(layer)`. **Layers and tile mode are mutually
+exclusive** (guard raises in both directions: `add_layer` on a tiled plot, and
+`enable_tile` / `set_data(tile=True)` / auto-tile on a layered plot).
+
+**A shape-changing `Plot2D.set_data` on a plot with layers raises `ValueError`.**
+Each layer entry keeps the `(width, height)` it had at `add_layer` / its last
+`Layer.set_data` time (`_encode_layer_pixels`), but `_drawLayers2d` always fits
+every layer's bitmap into the BASE image's *current* `_imgFitRect(iw, ih, …)`
+(`iw`/`ih` = the live `image_width`/`image_height`). So a base `set_data` that
+changes shape while a stale-sized layer is still attached would silently stretch
+that layer's old pixels over the new image instead of erroring — `set_data`
+now checks `data.shape[:2]` against the current `image_height`/`image_width`
+whenever `st.layers` is non-empty and raises before touching any state if they
+differ (same-shape updates, the common live-update case, are unaffected). Remove
+all layers first (`remove_layer`), change the base shape, then re-add them at the
+new size. A layer-FREE plot's shape-changing `set_data` is unaffected and always
+refreshes `image_width`/`image_height` (they're set unconditionally in the
+pushed `fields` dict). See `TestTileGuards` / `TestShapeChangeNoLayers` in
+`tests/test_plot2d/test_layers.py`.
+
+**`Layer.set(clim=…)` has three distinct meanings** — `None` (default) leaves
+the clim UNCHANGED (a no-op on that field, not "reset to auto"); a `(vmin, vmax)`
+tuple sets an explicit range and re-quantises the cached frame over it;
+`"auto"` is the sentinel to explicitly RESET to auto — recomputes the display
+range from the layer's own current data (`self._layer_raw[layer_id]`) min/max,
+the same auto-ranging `add_layer(..., clim=None)` does at creation time, and
+re-quantises. Before this, `clim=None` was documented as "auto" but actually
+behaved as a no-op, and there was no way to get back to auto range after
+setting an explicit clim short of `remove()` + `add_layer()` again. See
+`TestSet::test_set_clim_auto_resets_to_data_range` /
+`test_set_clim_auto_matches_add_layer_auto` /
+`test_set_clim_none_is_a_noop` in `tests/test_plot2d/test_layers.py`.
+
+### State + transport (dynamic per-layer pixel keys)
+
+The layer *metadata* lives in `st.layers` (a list of small dicts on the light view
+trait):
+
+```
+st.layers = [{ id, cmap, clim_min, clim_max, alpha, visible,
+               width, height, colormap_data, image_b64 }, …]   # z-order
+```
+
+`image_b64` in each entry is the layer's pixels: a base64 string (Jupyter /
+standalone / `save_html`) OR a `"\x00bin:<adler32>"` change-token (Electron binary
+transport). The JS reads pixels from this entry field on the base64 path.
+
+The *heavy pixel bytes* additionally ride a **DYNAMIC geometry key**
+`layer_<id>_b64` — one per layer — mirroring how the base image `image_b64` rides
+the geom channel. The dynamic-key mechanism:
+
+- **`Plot2D._GEOM_KEYS` is a PROPERTY** (not a plain frozenset): it returns the
+  fixed base set (`image_b64`, `colormap_data`, `overlay_mask_b64`, `detail_b64`)
+  UNION the current `layer_<id>_b64` keys. So `Figure._push` splits every layer's
+  pixels off the light view trait onto `panel_<id>_geom` and dedup-caches them
+  exactly like the base image; a removed layer's key drops out automatically.
+- **`_electron._route_change`** ships each layer key as its own PLOTBIN frame:
+  `_is_binary_pixel_key(k)` matches `k in _BINARY_KEYS` OR `layer_*_b64`. The
+  binary frame header carries `{"geom": "panel_<id>_geom"}` and `key=layer_<id>_b64`,
+  so the receiver builds slot `panel_<id>_geom::layer_<id>_b64` (the same
+  `awi_state_binary` handler as the base image — already generic on `hdr.geom` +
+  `e.data.key`, no change needed there).
+- **`resolve_pixel_tokens`** (cold path: `save_html` / standalone) materialises
+  real base64 for every `layer_<id>_b64` key AND the entry `image_b64` mirror, so a
+  snapshot is self-contained.
+- **JS `_spliceBinaryBytes`** scans `__apl_pixbytes` by the `panel_<id>_geom::`
+  PREFIX (not the old hardcoded 3-key list) so it splices any `layer_<id>_b64_bytes`
+  into `p2._geomCache`. The per-slot binary listeners are registered only for the
+  fixed keys (`_registerBinaryPixelListeners`); dynamic layer bytes are consumed by
+  the **geom-JSON change handler**, which now also calls `_spliceBinaryBytes` — the
+  geom trait always re-pushes when layers change, so a layer's bytes converge into
+  the cache regardless of trait arrival order.
+
+### JS compositing (`_drawLayers2d`, called from `draw2d`)
+
+After the base image (Canvas2D blit OR WebGPU) and the overlay mask, and BEFORE
+`_drawAxes2d` / markers / widgets, `_drawLayers2d(p, st, imgW, imgH, ctx, iw, ih)`
+draws each **visible** layer bottom-up on `plotCanvas`:
+
+- `_layerBytes(st, layer)` prefers `layer_<id>_b64_bytes` (binary) over the entry
+  `image_b64` base64;
+- `_layerBitmap(p, st, layer)` builds a LUT-colormapped RGBA `OffscreenCanvas`,
+  **cached per layer id** by `(pixel key, cmap, clim)` — rebuilt only when the
+  layer's data or appearance changes (a live scrub that only swaps one layer's
+  data rebuilds just that layer);
+- it blits with the SAME fit-rect + zoom/pan transform as the base blit
+  (`_imgFitRect` + the `zoom>=1` window math) at `ctx.globalAlpha = layer.alpha`,
+  so zoom/pan track the base exactly.
+
+Because layers draw on `plotCanvas`, they sit UNDER `markersCanvas` /
+`overlayCanvas` (z-order) and are captured by `exportPNG` for free (plotCanvas is
+z1 in the composite). Over a WebGPU base the layers still composite in Canvas2D on
+`plotCanvas` (which sits above the transparent `gpuCanvas`) — verified by
+`test_layers_playwright.py::TestGpuBaseWithLayer`. Per-move perf: only the changed
+layer's LUT bitmap is rebuilt (the box-loop is ~one pass over H×W uint8 → uint32,
+comparable to the base image's `_buildLut32` blit).
+
+---
+
 ## 3D drawing (line ~1840)
 Orthographic projection; geometry b64-decoded and cached.  `draw3d` sorts
 triangles, draws axes with per-axis `_drawTex` labels (`x/y/z_label_size`).
@@ -309,3 +475,61 @@ Python → JS (set widget position from Python):
   widget.set(…) → Figure._push_widget → event_json with source:'python'
   → model.on('change:event_json') patches overlay_widgets + redraws
 ```
+
+---
+
+## PNG export (`exportPNG`)
+
+`render()` now RETURNS an internal API object `{ panels, exportPNG,
+_gpuDisposeImagePanel, _gpuDisposePanel }` (anywidget ignores render()'s return;
+`mount()` captures it — this also fixed a latent bug where the old
+mount-handle `dispose()` referenced `panels`/`_gpuDispose*` from module scope,
+which are inside `render`'s closure, and silently threw). The mount handle
+exposes `handle.exportPNG({scale=1, includeWidgets=false}) →
+Promise<{dataUrl,width,height}>`.
+
+`exportPNG(opts)` (inside `render`, near `redrawAll`) composites the WHOLE
+figure onto one offscreen canvas at `devicePixelRatio × scale`:
+
+- **WebGPU hazard first**: a WebGPU canvas's drawing buffer is only valid right
+  after its render pass, so exportPNG force-calls `draw2d(p)` on every
+  active-GPU 2-D panel (`p._gpu==='active' && p.gpuCanvas` visible) to re-submit
+  its pass, THEN composites in the SAME synchronous task — so
+  `drawImage(gpuCanvas,…)` reads live pixels, not a blank buffer.
+- **Extent**: `fig_width/height + 2×8 px` gridDiv padding (NOT the measured
+  `gridDiv` width — a bare `mount()` page has no `.apl-outer` inline-block CSS,
+  so the grid container can stretch to the viewport). **Origin**: `gridDiv`'s
+  top-left (grid tracks are fixed-px + left-anchored, so panels sit correctly).
+- **Per-panel z-order** (`_drawEl` positions each canvas by its
+  `getBoundingClientRect()` relative to the root): gpuCanvas (z0) → plotCanvas
+  (z1) → x/yAxisCanvas → cbCanvas → [overlayCanvas z5 only if `includeWidgets`]
+  → markersCanvas (z6) → scaleBar (z7) → titleCanvas (z8). Grid panels first,
+  then insets (`p.isInset`) on top — **each titled inset's title bar text is
+  drawn directly onto the output canvas right after its canvas stack**
+  (`_drawInsetTitle`; the title bar is plain DOM — a `<div>`/`<span>`, not a
+  canvas — so `_drawEl` alone never captures it; approximates the on-screen
+  CSS: 11px sans-serif, `theme.tickText` colour, left-padded to the titleBar's
+  rect) — then the figure-level `calloutCanvas` (region indications) composited
+  LAST. Status bars / stats overlays are excluded.
+- **Coordinate snapping** (`_drawEl`): `dx`/`dy` are `Math.round()`ed from the
+  element's `left`/`top`, and `dw`/`dh` are the ROUNDED `right`/`bottom` edge
+  minus the rounded `dx`/`dy` — never `Math.round(width)` directly. This makes
+  two elements that share a CSS edge (e.g. adjacent grid panels, or a
+  panel's axis-gutter canvas against its plotCanvas) round that shared edge to
+  the *same* output pixel on both sides. Without it, at a fractional effective
+  scale (`devicePixelRatio × opts.scale` — e.g. a real 150% Windows display, or
+  `scale: 1.25`), each element's `dx`/`dw` were computed independently as raw
+  floats, and adjacent elements could round their common boundary to different
+  output pixels — a 1px background-coloured seam (or overlap) exactly at the
+  join. See `TestExportMultiPanel::test_fractional_scale_no_seam_between_panels`
+  in `tests/test_embed/test_export_png.py` (reproduced with
+  `device_scale_factor=1.5`).
+- Ends with `out.toDataURL('image/png')`; rejects the promise with a message on
+  failure (no 2-D context, `toDataURL` throw).
+
+The standalone HTML template (`_repr_utils.build_standalone_html`) captures
+render()'s api into `_aplRenderApi` and adds a `message` listener:
+`{type:'anyplotlib_export_png', requestId, opts}` → `exportPNG(opts)` → replies
+`{type:'anyplotlib_export_png_result', requestId, dataUrl, width, height}` (or
+`{…, error}`) to `event.source` (targetOrigin `'*'`) — the same channel the
+`awi_state` postMessages ride. Tests: `tests/test_embed/test_export_png.py`.