anyplotlib 0.8.0__tar.gz → 0.10.0__tar.gz

{anyplotlib-0.8.0 → anyplotlib-0.10.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,407 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.10.0}/CHANGELOG.rst

@@ -10,6 +10,139 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.10.0 (2026-09-14)
+===================
+
+API and Behaviour Changes
+-------------------------
+
+- 2-D pointer events (``pointer_down``, ``double_click``, ``pointer_settled``, ``key_down``) and the hover readout now report ``img_x``/``img_y`` in the pixel-centre convention that markers, widgets and :meth:`~anyplotlib.Plot2D.display_to_data` already used — they read half a pixel right and down before — so ``round(event.img_x)`` names the clicked pixel (``int()`` no longer does), brush strokes land under the cursor, and an ``imshow`` event's ``xdata``/``ydata`` is exactly the axis value of the pixel centre it hits (``pcolormesh`` values are unchanged). (`#73 <https://github.com/CSSFrancis/anyplotlib/pull/73>`_)
+- 2-D tick labels now sit on the pixels they name: ``imshow`` axis values are placed at pixel centres (the image extends half a pixel past the first and last value, as matplotlib's ``imshow`` extent does) through the same transform markers and pointer events use, so ticks also follow a letterboxed image instead of spanning the whole gutter, and an ``origin='lower'`` image gets y ticks at all; :meth:`~anyplotlib.Plot2D.set_view` / ``set_xlim`` / ``set_ylim`` read the axis the same way — ``set_xlim(-0.5, n - 0.5)`` is the whole image, ``set_xlim(0, n - 1)`` now crops the outer half pixels — and accept a descending ``origin='lower'`` y axis. (`#74 <https://github.com/CSSFrancis/anyplotlib/pull/74>`_)
+
+
+New Features
+------------
+
+- The 2-D colorbar now writes its display minimum and maximum beside the strip — both ends in one format, and the strip itself coloured through the display window (saturated beyond it, the way the image is) and spanning the image rather than the whole panel — so a labelled scale says how much and not only which way; the image gives up a value gutter budgeted for the numbers (fixed for ordinary values so a contrast drag never moves the image, wider for the rare long ones, dropped in a cell too narrow to keep 40 px of image, and mirrored in :meth:`plot_box`) so they never clip. (`#71 <https://github.com/CSSFrancis/anyplotlib/pull/71>`_)
+- Text markers (:meth:`~anyplotlib.Plot2D.add_texts`, :meth:`~anyplotlib.Plot1D.add_texts` and ``add_text``) gained ``fontweight`` for bold labels and ``outline_color`` / ``outline_width`` for a halo stroked under the text, which keeps a label legible over both light and dark parts of an image. (`#73 <https://github.com/CSSFrancis/anyplotlib/pull/73>`_)
+
+
+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.10.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.10.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.10.0}/PKG-INFO

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