anyplotlib 0.8.0__tar.gz → 0.9.0__tar.gz

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

@@ -7,7 +7,7 @@
 - **`Figure`** (`anyplotlib/figure/_figure.py`) — the only `anywidget.AnyWidget` subclass. Owns all traitlets and is the Python↔JS bridge.
 - **Plot objects** (`plot1d/`, `plot2d/`, `plot3d/`) — `Plot1D`, `PlotBar`, `Plot2D`, `PlotMesh`, `Plot3D` are **plain Python classes**, not widgets. They hold state in `_state` dicts and push to the Figure. Shared behaviour lives in `_base_plot.py` (`_BasePlot`, `_PanelMixin`, `_MarkerMixin`).
 - **`Axes`** (`axes/_axes.py`) — grid-cell container; factory methods (`imshow`, `plot`, `bar`, `pcolormesh`, `plot_surface`, …) create plot objects and attach them.
-- **`figure_esm.js`** — pure-JS canvas renderer (~9,300 lines); all rendering logic lives here. **Read `anyplotlib/FIGURE_ESM.md` first** — it is the section map.
+- **`figure_esm.js`** — pure-JS canvas renderer (~12,210 lines); all rendering logic lives here. **Read `anyplotlib/FIGURE_ESM.md` first** — it is the section map.
 - **`markers.py`** — static visual overlays (circles, arrows, lines, etc.) with a two-level dict registry: `plot.markers[type][name]`.
 - **`widgets/`** — interactive draggable overlays (`RectangleWidget`, `CrosshairWidget`, etc.) that receive JS position updates.
 - **`callbacks.py`** — event system: `Event` dataclass, `CallbackRegistry` (priority ordering, wildcard, pause/hold), `_EventMixin` (`add_event_handler`).
@@ -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 10,119 lines.
+the 2-D function table). Both were last verified at 12,211 lines.
 
 Changelog entries: add a fragment file to `upcoming_changes/` (e.g.
 `123.new_feature.rst`) — towncrier assembles `CHANGELOG.rst` at release time.
@@ -129,7 +129,7 @@ Use `api_change` when existing behaviour changes, even if the change is a fix.
 | `anyplotlib/figure/_gridspec.py` | `GridSpec`, `SubplotSpec` |
 | `anyplotlib/figure/_subplots.py` | `subplots()` factory |
 | `anyplotlib/axes/_axes.py` | `Axes` — plot factory methods |
-| `anyplotlib/figure_esm.js` | All JS canvas rendering (~9,300 lines) |
+| `anyplotlib/figure_esm.js` | All JS canvas rendering (~12,210 lines) |
 | `anyplotlib/FIGURE_ESM.md` | Section map for `figure_esm.js` — read this before editing the JS |
 | `anyplotlib/markers.py` | Static marker collections; `to_wire()` translation |
 | `anyplotlib/widgets/` | Interactive overlay widgets |

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

@@ -10,6 +10,122 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.9.0 (2026-09-11)
+==================
+
+New Features
+------------
+
+- A self-contained HTML page can now navigate its own data.
+  ``anyplotlib.embed.navigated_html`` writes a figure, the dataset it navigates
+  and a list of bindings into one file: drag the navigator's crosshair and the
+  signal panel shows that position's frame, its overlays follow, and a detector
+  drawn on the signal panel re-maps the navigator.  Data travels as *blocks*:
+  dense arrays, or ``Ragged`` row-pointer blocks for a variable number of rows
+  per position, packed by ``pack_blocks`` into one byte string the page decodes
+  once.
+
+  The JS mount handle gained the pieces that make that fast: ``setImage`` pushes
+  raw pixel bytes straight to the renderer's draw path (a fraction of a
+  millisecond at 2048², against 129-136 ms through the panel state),
+  ``patchPanel`` merges a partial state, and ``panelIds`` lists the panels.  The
+  runtime and its readers (``mountNavigated``, ``dense``, ``ragged``,
+  ``maskFromWidget``, ``rasterDisks``, ``robustLevels``, ``toU8``) are exported
+  from ``figure_esm.js`` for hosts that already own their data. (`#69 <https://github.com/CSSFrancis/anyplotlib/pull/69>`_)
+- Figures can now be **saved and copied as PNG images**. Right-click any plot for a
+  menu offering *Copy image*, *Save PNG…*, *Save full view…* and *Save at native
+  resolution…* for the panel you clicked, the same for the whole figure, and a
+  sticky **Theme** choice (*Current* / *Light* / *Dark*) so a dark-themed notebook
+  can still produce a light figure for a paper. ``Ctrl+C`` (``Cmd+C`` on macOS)
+  copies the plot under the cursor to the clipboard, with a brief
+  *"Image copied to clipboard"* confirmation; with no plot hovered it copies the
+  whole figure. Inside JupyterLab, PyCharm and VS Code the badge is the reliable
+  route: those hosts install their own ``contextmenu`` and keyboard handlers and
+  may swallow a right-click or ``Cmd+C`` before the figure ever sees it. *Save PNG…* downloads without any permission prompt; a separate *Save as…*
+  entry opens a real system file dialog where the browser supports one
+  (Chromium), at the cost of Chrome's file-editing permission prompt. Hosts that
+  block script-started downloads get an in-figure preview instead.
+  The three sources are *current view* (zoom, pan and contrast
+  exactly as displayed), *full view* (the whole data extent at the panel's
+  on-screen resolution) and *native resolution* (one output pixel per data pixel,
+  with the axes, colorbar, title, markers and widgets all redrawn at that size).
+
+  The same thing is available from Python as :meth:`~anyplotlib.Figure.savefig`::
+
+      fig.savefig("figure.png")                                # as displayed
+      fig.savefig("paper.png", theme="light", scale=2)         # light, 2x
+      fig.savefig("data.png", source="native", panel=plot)     # 1:1 with the data
+
+  ``savefig`` renders through the real JavaScript renderer in a headless browser,
+  so the output is exactly what the figure looks like on screen — it needs
+  Playwright (``pip install "anyplotlib[docs]"`` then
+  ``playwright install chromium``). ``source="native"`` works even for a **tiled**
+  plot, whose full-resolution array normally never leaves Python: the backend is
+  re-sampled at full resolution for the export only, leaving the live figure
+  untouched. In the browser that case is offered but disabled, with a tooltip
+  pointing at ``savefig``, because the page only ever holds a downsampled
+  overview.
+
+  Downstream applications can add their own entries to the menu through the
+  embedding handle, so a host can save formats anyplotlib knows nothing about::
+
+      handle.registerExportAction({
+        id: 'save-tiff', label: 'Save as TIFF…', scope: 'panel',
+        handler: (ctx) => host.writeTiff(ctx.panelId, ctx.exportCanvas().canvas),
+      })
+
+  The handler receives the clicked panel, its state, the chosen theme, and bound
+  ``exportPNG`` / ``exportCanvas`` / ``downloadPNG`` / ``copyPNG`` / ``toast``
+  helpers. See :doc:`exporting` for the full reference.
+- The 2-D hover readout now also names the **value** of the pixel under the
+  cursor — ``v:<value>`` for a colourmapped image, ``rgb:r,g,b`` for a true-colour
+  one — alongside the existing physical and pixel coordinates. It is exact:
+  integer data whose range fits the 256 transferred codes is inverted locally,
+  and for anything wider the renderer asks Python for the true value once the
+  cursor dwells on a pixel (``imshow(..., probe_exact=True)`` by default, tunable
+  via :meth:`~anyplotlib.Plot2D.set_value_probe`), falling back to the quantised
+  estimate when no kernel can answer. Zoomed into a detail tile the value comes
+  from the tile's native pixels rather than the coarser overview.
+  The **v** key toggles the on-image pill, and
+  :meth:`~anyplotlib.Plot2D.set_readout_visible` turns it off from Python while
+  keeping the readout live: embedding hosts receive every update through
+  ``mount()``'s ``opts.onReadout`` callback and an ``apl:readout`` DOM event — so
+  an Electron app can render position and value in its own status bar instead,
+  where it covers no data. 2-D pointer events also carry ``img_x``/``img_y`` now,
+  the cursor's position in image pixels.
+
+
+Bug Fixes
+---------
+
+- Fixed a tiled :meth:`~anyplotlib.Axes.imshow` of a **signed** integer frame
+  displaying wrapped values: a ``uint32`` accumulator in the overview box-mean read
+  an ``int16`` ``-100`` as ``+1073741696``, raised
+  ``_UFuncOutputCastingError`` on a non-divisible grid, and overflowed on any dtype
+  wider than 16 bits; the accumulator is now sized to the data, which also makes the
+  overview up to 4x faster on large float frames. (`#65 <https://github.com/CSSFrancis/anyplotlib/pull/65>`_)
+- :meth:`~anyplotlib.Figure.save_html`, :func:`~anyplotlib.embed.to_html` and
+  :func:`~anyplotlib.embed.figure_state` now capture the view the reader is
+  actually looking at. Zoom, pan, orbit and the colorbar / scale-mode shortcuts
+  are applied in the browser and written back to the panel traits, but nothing on
+  the Python side read them back, so every snapshot silently reset the figure to
+  the view it was created with. Those keys are now reconciled into the plot state
+  before a snapshot is taken.
+- Fixed PNG export producing a mostly-blank image when the figure is wider than
+  the notebook cell. In that case the renderer shrinks the figure with a CSS
+  ``transform: scale()``, which makes element rectangles report *visual* pixels
+  while the export sized its canvas in *native* pixels — so the panels were
+  composited into the top-left corner and the remainder was filled with the
+  background colour. Export coordinates are now un-scaled by the live transform.
+- Modified key presses no longer trigger a plot's single-letter shortcuts. The
+  panel key handlers matched on the bare letter without checking modifiers, so
+  ``Ctrl+C`` toggled the colorbar instead of copying, and ``Cmd+S`` — JupyterLab's
+  *save notebook* — silently flipped a 2-D plot's colour scale to symlog. Keys
+  pressed with ``Ctrl``, ``Cmd`` or ``Alt`` are now left to the host. They are
+  still reported to Python ``key_down`` callbacks exactly as before, so nothing
+  that observes the full keystroke changes.
+
+
 0.8.0 (2026-08-25)
 ==================
 

anyplotlib-0.9.0/Examples/PlotTypes/plot_aspect_ratio.py

@@ -0,0 +1,77 @@
+"""
+Aspect Ratio Control
+====================
+
+:meth:`~anyplotlib.Plot2D.set_aspect` constrains the displayed image canvas so
+that one unit on the x-axis occupies the same number of pixels as one unit on
+the y-axis.
+
+Three modes are shown:
+
+1. **Default** — the image fills the panel exactly (no constraint).
+2. ``set_aspect("equal")`` — forces a 1 : 1 pixel-per-unit ratio.  A square
+   array is displayed as a square image regardless of panel dimensions.
+3. ``set_aspect(2.0)`` — makes the canvas twice as wide as it is tall.
+
+The scale bar, axis ticks, and colorbar all update automatically when the
+canvas is resized by ``set_aspect``.
+"""
+import numpy as np
+import anyplotlib as apl
+
+rng = np.random.default_rng(0)
+
+# ── Synthetic calibrated image ────────────────────────────────────────────────
+N = 64
+x = np.linspace(0, 10, N)   # nm
+y = np.linspace(0, 10, N)
+XX, YY = np.meshgrid(x, y)
+data = (np.sin(XX) * np.cos(YY) + 0.2 * rng.standard_normal((N, N))).astype(np.float32)
+
+# ── 1. Default (no aspect constraint) ────────────────────────────────────────
+# %%
+# Default — no aspect constraint
+# --------------------------------
+# The image stretches to fill the full panel area.
+
+fig1, ax1 = apl.subplots(1, 1, figsize=(420, 340))
+plot1 = ax1.imshow(data, axes=[x, y], units="nm", cmap="viridis")
+plot1.set_title("Default (no constraint)")
+plot1.set_xlabel("x (nm)")
+plot1.set_ylabel("y (nm)")
+
+fig1  # Interactive
+
+# ── 2. Equal aspect ratio ─────────────────────────────────────────────────────
+# %%
+# Equal aspect ratio
+# ------------------
+# ``set_aspect("equal")`` (or equivalently ``set_aspect(1.0)``) ensures that
+# one nm on the x-axis occupies the same number of canvas pixels as one nm on
+# the y-axis.  The canvas height adjusts to be equal to the canvas width.
+
+fig2, ax2 = apl.subplots(1, 1, figsize=(420, 340))
+plot2 = ax2.imshow(data, axes=[x, y], units="nm", cmap="viridis")
+plot2.set_aspect("equal")
+plot2.set_title("set_aspect('equal')")
+plot2.set_xlabel("x (nm)")
+plot2.set_ylabel("y (nm)")
+
+fig2  # Interactive
+
+# ── 3. Explicit ratio ─────────────────────────────────────────────────────────
+# %%
+# Explicit ratio (2 : 1)
+# -----------------------
+# ``set_aspect(2.0)`` makes the canvas twice as wide as it is tall.  Useful
+# when the physical x and y scales differ (e.g. a time-series scan where one
+# axis is faster than the other).
+
+fig3, ax3 = apl.subplots(1, 1, figsize=(420, 340))
+plot3 = ax3.imshow(data, axes=[x, y], units="nm", cmap="inferno")
+plot3.set_aspect(2.0)
+plot3.set_title("set_aspect(2.0)")
+plot3.set_xlabel("x (nm)")
+plot3.set_ylabel("y (nm)")
+
+fig3  # Interactive

anyplotlib-0.9.0/Examples/PlotTypes/plot_subplots_adjust.py

@@ -0,0 +1,90 @@
+"""
+Subplot Spacing with subplots_adjust
+=====================================
+
+:meth:`~anyplotlib.Figure.subplots_adjust` controls the gap between panels in
+a multi-panel figure.
+
+* **hspace** — vertical gap as a fraction of the mean row height.
+  ``hspace=0.15`` adds 15 % of the average row height as space between rows.
+* **wspace** — horizontal gap as a fraction of the mean column width.
+  ``wspace=0.10`` adds 10 % of the average column width as space between
+  columns.
+
+Both values default to ``0.0`` (panels are flush with no gap).
+
+The examples below compare default flush spacing against adjusted spacing on
+the same 2 × 2 grid.
+"""
+import numpy as np
+import anyplotlib as apl
+
+rng = np.random.default_rng(42)
+t   = np.linspace(0, 2 * np.pi, 512)
+
+COLORS  = ["#4fc3f7", "#ff7043", "#aed581", "#ffd54f"]
+LABELS  = ["α", "β", "γ", "δ"]
+SIGNALS = [
+    np.sin(t * (i + 1)) + rng.normal(scale=0.08, size=len(t))
+    for i in range(4)
+]
+
+
+def _fill_grid(fig):
+    """Add four 1-D spectra to a 2×2 Figure."""
+    import anyplotlib as _apl
+    gs = _apl.GridSpec(2, 2)
+    positions = [(0, 0), (0, 1), (1, 0), (1, 1)]
+    for idx, (r, c) in enumerate(positions):
+        ax = fig.add_subplot(gs[r, c])
+        ax.plot(SIGNALS[idx], color=COLORS[idx], label=LABELS[idx])
+
+
+# ── 1. Default spacing (flush) ────────────────────────────────────────────────
+# %%
+# Default spacing — panels flush
+# --------------------------------
+# Without calling ``subplots_adjust`` the panels abut each other with no gap.
+
+fig1 = apl.Figure(2, 2, figsize=(680, 480))
+_fill_grid(fig1)
+
+fig1  # Interactive
+
+# ── 2. Vertical gap only (hspace) ────────────────────────────────────────────
+# %%
+# Vertical gap only — hspace=0.15
+# ---------------------------------
+# ``subplots_adjust(hspace=0.15)`` inserts a vertical gap equal to 15 % of
+# the mean row height between the two rows.
+
+fig2 = apl.Figure(2, 2, figsize=(680, 480))
+_fill_grid(fig2)
+fig2.subplots_adjust(hspace=0.15)
+
+fig2  # Interactive
+
+# ── 3. Horizontal gap only (wspace) ──────────────────────────────────────────
+# %%
+# Horizontal gap only — wspace=0.10
+# -----------------------------------
+# ``subplots_adjust(wspace=0.10)`` inserts a horizontal gap equal to 10 % of
+# the mean column width between the two columns.
+
+fig3 = apl.Figure(2, 2, figsize=(680, 480))
+_fill_grid(fig3)
+fig3.subplots_adjust(wspace=0.10)
+
+fig3  # Interactive
+
+# ── 4. Both gaps ─────────────────────────────────────────────────────────────
+# %%
+# Both hspace and wspace
+# -----------------------
+# Combine both arguments to add space in both directions.
+
+fig4 = apl.Figure(2, 2, figsize=(680, 480))
+_fill_grid(fig4)
+fig4.subplots_adjust(hspace=0.15, wspace=0.10)
+
+fig4  # Interactive

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: anyplotlib
-Version: 0.8.0
+Version: 0.9.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