anyplotlib 0.7.1__tar.gz → 0.7.3__tar.gz

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

@@ -10,6 +10,38 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.7.3 (2026-08-13)
+==================
+
+New Features
+------------
+
+- ``Plot2D.add_circle_widget`` gains ``lock_center``: the centre is pinned and
+  only the radius is draggable. A grab on the ring body is refused at hit-test
+  time and falls through to the plot's own pan, so the hover cursor never
+  promises a move and the centre cannot drift. Use it when the centre is fixed by
+  the data — a ring on a power spectrum is centred on the DC term, and one nudged
+  off-centre silently corrupts every radius measured from it.
+
+
+0.7.2 (2026-08-03)
+==================
+
+Bug Fixes
+---------
+
+- ``Plot2D.set_overlay_mask`` now works in TILE mode. The renderer sizes the mask
+  against ``base_width || image_width`` -- the tile overview grid -- but tile mode
+  sets ``image_width`` to the full native frame, so the shape check accepted only
+  the one shape the renderer silently discards (``maskCache = null``, no error) and
+  rejected the one that actually renders. On a 4096x4096 tiled plot neither a
+  1024x1024 nor a 4096x4096 mask could be drawn: the first raised ``ValueError``,
+  the second encoded 22.4 MB the renderer dropped. Both shapes are now accepted and
+  a full-resolution mask is reduced to the overview grid with a block ANY -- never
+  a subsample, so an object a few pixels across cannot vanish into a skipped
+  sample.
+
+
 0.7.1 (2026-08-02)
 ==================
 

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

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

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

@@ -8182,7 +8182,13 @@ fn fs(in : VsOut) -> @location(0) vec4<f32> {
         // outer radius handle
         if (Math.hypot(mx - (ccx + cr), my - ccy) <= HR)
           return { idx:i, mode:'resize_r', snapW:{...w}, startMX:mx, startMY:my };
-        // body (inside ring ± tolerance)
+        // body (inside ring ± tolerance). `lock_center` refuses the grab
+        // outright rather than letting the drag run and correcting afterwards:
+        // a centre snapped back on release still tracks the cursor for the
+        // whole drag, which reads as a broken lock. Refusing here also leaves
+        // the hover cursor at 'default' and lets the drag fall through to the
+        // plot's own pan, so the ring is simply not a handle any more.
+        if (w.lock_center) continue;
         if (Math.abs(Math.hypot(mx-ccx, my-ccy) - cr) <= Math.max(HR, cr*0.18) ||
             Math.hypot(mx-ccx, my-ccy) <= HR)
           return { idx:i, mode:'move', snapW:{...w}, startMX:mx, startMY:my };
@@ -8441,7 +8447,9 @@ fn fs(in : VsOut) -> @location(0) vec4<f32> {
     }
 
     if (w.type === 'circle') {
-      if (d.mode === 'move') {
+      // A drag already in flight when `lock_center` is turned on must not keep
+      // translating the widget: the hit-test gate only runs at grab time.
+      if (d.mode === 'move' && !w.lock_center) {
         w.cx = s.cx + dix; w.cy = s.cy + diy;
       } else if (d.mode === 'resize_r') {
         // distance from centre in image-px

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

@@ -45,6 +45,40 @@ def _binary_transport_active() -> bool:
     return os.environ.get("APL_BINARY_TRANSPORT") == "1"
 
 
+def _reduce_mask_any(mask, out_h: int, out_w: int):
+    """Reduce a boolean *mask* to ``(out_h, out_w)`` with a block ANY.
+
+    A block of the source is True in the output if ANY of its pixels is. For a
+    mask that is the only defensible reduction: it marks *where objects are*,
+    and an object smaller than one output block must not vanish because the
+    sampled pixel happened to miss it.
+
+    The tail rows/columns that do not divide evenly are folded into the last
+    block rather than cropped, so an object at the right or bottom edge is kept.
+    """
+    import numpy as _np
+
+    src_h, src_w = mask.shape
+    if (src_h, src_w) == (out_h, out_w):
+        return mask
+    ys = max(1, src_h // out_h)
+    xs = max(1, src_w // out_w)
+    keep_h, keep_w = (src_h // ys) * ys, (src_w // xs) * xs
+    small = mask[:keep_h, :keep_w].reshape(
+        keep_h // ys, ys, keep_w // xs, xs).any(axis=(1, 3))
+    out = _np.zeros((out_h, out_w), bool)
+    sh, sw = min(out_h, small.shape[0]), min(out_w, small.shape[1])
+    out[:sh, :sw] = small[:sh, :sw]
+    # Fold any cropped tail into the final block so edge objects survive.
+    if keep_h < src_h and sh > 0:
+        out[sh - 1, :sw] |= mask[keep_h:, :keep_w].reshape(
+            1, src_h - keep_h, keep_w // xs, xs).any(axis=(1, 3))[0, :sw]
+    if keep_w < src_w and sw > 0:
+        out[:sh, sw - 1] |= mask[:keep_h, keep_w:].reshape(
+            keep_h // ys, ys, 1, src_w - keep_w).any(axis=(1, 3))[:sh, 0]
+    return out
+
+
 class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
     """2-D image plot panel.
 
@@ -1115,6 +1149,13 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             Boolean array aligned to the image data.  ``True`` / non-zero
             pixels are filled with *color* at transparency *alpha*.
             Pass ``None`` to clear the overlay.
+
+            In TILE mode pass the mask at the FULL image resolution: the
+            renderer composites the mask against the OVERVIEW texture, so it
+            is reduced to the base grid here.  A mask already at the base grid
+            is accepted unchanged.  (Both are accepted because neither is
+            wrong; what was wrong was accepting only the full-resolution one
+            and then shipping bytes the renderer silently discards.)
         color : str, optional
             CSS hex colour for the overlay, e.g. ``"#ff4444"``.  Default red.
             Must be in ``#RRGGBB`` format.
@@ -1137,14 +1178,32 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             self._state["overlay_mask_alpha"] = alpha
         else:
             arr = np.asarray(mask)
-            if arr.shape != (self._state["image_height"], self._state["image_width"]):
-                raise ValueError(
-                    f"mask shape {arr.shape} does not match image "
-                    f"({self._state['image_height']} x {self._state['image_width']})"
-                )
+            ih, iw = self._state["image_height"], self._state["image_width"]
+            bh = int(self._state.get("base_height") or 0)
+            bw = int(self._state.get("base_width") or 0)
+            # THE TILE-MODE SHAPE TRAP. The renderer sizes the mask against
+            # `base_width || image_width` -- the OVERVIEW grid -- but tile mode
+            # sets image_width/height to the FULL native frame. So validating
+            # only against the image shape rejected the one shape that renders
+            # and accepted the one the renderer drops on the floor
+            # (`mBytes.length===iw*ih` else `maskCache=null`, silently). Both
+            # shapes are legal here; the overview is what actually ships.
+            tiled = bw > 0 and bh > 0 and (bh, bw) != (ih, iw)
+            if arr.shape != (ih, iw) and not (tiled and arr.shape == (bh, bw)):
+                want = f"({ih} x {iw})"
+                if tiled:
+                    want += f" or the tile overview ({bh} x {bw})"
+                raise ValueError(f"mask shape {arr.shape} does not match image {want}")
             # For origin='lower' the image data was flipped; flip mask to match.
             if self._origin == "lower":
                 arr = np.flipud(arr)
+            if tiled and arr.shape == (ih, iw):
+                # Block ANY, never a subsample: a mask marks objects that are
+                # often only a few pixels across, and striding a 4096² mask
+                # down to 1024² drops three quarters of them at random. ANY
+                # keeps every object visible at the cost of fattening it, which
+                # is the right trade for an overlay you are looking at.
+                arr = _reduce_mask_any(np.asarray(arr, dtype=bool), bh, bw)
             # Convert to uint8: True/non-zero → 255, False/zero → 0
             u8 = (np.asarray(arr, dtype=bool).view(np.uint8) * 255).astype(np.uint8)
             self._state["overlay_mask_b64"]   = base64.b64encode(u8.tobytes()).decode("ascii")
@@ -1672,15 +1731,24 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
     def add_circle_widget(self, cx: float | None = None, cy: float | None = None,
                           r: float | None = None, color: str = "#00e5ff",
                           linewidth: float = 2,
-                          show_handles: bool = True) -> CircleWidget:
-        """Add a draggable circle overlay."""
+                          show_handles: bool = True,
+                          lock_center: bool = False) -> CircleWidget:
+        """Add a draggable circle overlay.
+
+        ``lock_center`` pins the centre and leaves only the radius draggable —
+        a grab on the ring body is refused and pans the plot instead. Use it
+        when the centre is fixed by the data (a ring on a power spectrum is
+        centred on the DC term), so it cannot be nudged off and silently
+        corrupt every radius measured from it.
+        """
         iw, ih = self._state["image_width"], self._state["image_height"]
         widget = CircleWidget(lambda: None,
                               cx=float(cx) if cx is not None else iw / 2,
                               cy=float(cy) if cy is not None else ih / 2,
                               r=float(r) if r is not None else iw * 0.1,
                               color=color, linewidth=linewidth,
-                              show_handles=show_handles)
+                              show_handles=show_handles,
+                              lock_center=lock_center)
         widget._push_fn = self._make_widget_push_fn(widget)
         self._widgets[widget.id] = widget
         self._push()

anyplotlib-0.7.3/anyplotlib/tests/test_interactive/test_circle_lock_center.py

@@ -0,0 +1,160 @@
+"""
+tests/test_interactive/test_circle_lock_center.py
+=================================================
+
+``lock_center`` — a circle whose centre is fixed by the data.
+
+Why it exists: a ring measured on a power spectrum is centred on the DC term.
+Its centre is not a free parameter, so a draggable one is a control that can
+only ever be wrong — and a ring nudged off-centre silently corrupts every
+radius measured from it.
+
+Why it is enforced in the HIT-TEST and not afterwards. The obvious
+implementation is a Python handler that watches the widget and snaps the centre
+back when the drag settles. It cannot work: ``_doDrag2d`` recomputes the
+position every frame from its own grab-time snapshot, so a pushed-back centre
+is overwritten on the next mousemove. The ring tracks the cursor for the whole
+drag and jumps back on release, which reads as a broken lock rather than a
+locked ring. Refusing the grab is the only place the constraint holds.
+
+Coordinate system mirrors figure_esm.js — see ``_img_to_page``.
+"""
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+import anyplotlib as apl
+from anyplotlib.widgets import CircleWidget
+from anyplotlib.tests.test_interactive._event_test_utils import (
+    _collect_events, _get_events,
+)
+
+FIG_W, FIG_H = 400, 300
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 1. Python API — the flag has to reach the JS renderer to do anything
+# ═══════════════════════════════════════════════════════════════════════════
+
+class TestLockCenterAttribute:
+    def test_defaults_to_unlocked(self):
+        w = CircleWidget(lambda: None, cx=16, cy=16, r=6)
+        assert w.lock_center is False
+
+    def test_stores_the_flag(self):
+        w = CircleWidget(lambda: None, cx=16, cy=16, r=6, lock_center=True)
+        assert w.lock_center is True
+
+    def test_reaches_the_state_dict(self):
+        """JS reads the widget dict, so the flag has to survive to_dict()."""
+        w = CircleWidget(lambda: None, cx=16, cy=16, r=6, lock_center=True)
+        assert w.to_dict()["lock_center"] is True
+
+    def test_add_circle_widget_passes_it_through(self):
+        fig, ax = apl.subplots(1, 1, figsize=(FIG_W, FIG_H))
+        v = ax.imshow(np.zeros((32, 32), dtype=np.float32))
+        w = v.add_circle_widget(cx=16, cy=16, r=6, lock_center=True)
+        assert w.lock_center is True
+
+    def test_add_circle_widget_defaults_to_unlocked(self):
+        fig, ax = apl.subplots(1, 1, figsize=(FIG_W, FIG_H))
+        v = ax.imshow(np.zeros((32, 32), dtype=np.float32))
+        assert v.add_circle_widget(cx=16, cy=16, r=6).lock_center is False
+
+
+# ═══════════════════════════════════════════════════════════════════════════
+# 2. Real drags in a real browser — the only place the constraint is enforced
+# ═══════════════════════════════════════════════════════════════════════════
+
+_OVERLAY_RECT_JS = """() => {
+    for (const cv of document.querySelectorAll('canvas')) {
+        if (getComputedStyle(cv).pointerEvents === 'all') {
+            const r = cv.getBoundingClientRect();
+            return {left:r.left, top:r.top, w:r.width, h:r.height};
+        }
+    }
+    return null;
+}"""
+
+
+def _img_to_page(page, ix, iy, iw=32, ih=32):
+    """Image px → page coords, for an overlay laid out 'contain' with no zoom."""
+    r = page.evaluate(_OVERLAY_RECT_JS)
+    assert r is not None, "overlay canvas not found"
+    s = min(r["w"] / iw, r["h"] / ih)
+    ox = (r["w"] - iw * s) / 2.0
+    oy = (r["h"] - ih * s) / 2.0
+    return r["left"] + ox + ix * s, r["top"] + oy + iy * s
+
+
+def _setup(interact_page, lock_center):
+    fig, ax = apl.subplots(1, 1, figsize=(FIG_W, FIG_H))
+    v = ax.imshow(np.zeros((32, 32), dtype=np.float32))
+    v.add_circle_widget(cx=16, cy=16, r=6, color="#ff0000",
+                        lock_center=lock_center)
+    page = interact_page(fig)
+    _collect_events(page)
+    return page
+
+
+def _drag(page, frm, to, steps=8):
+    page.mouse.move(*_img_to_page(page, *frm))
+    page.mouse.down()
+    page.mouse.move(*_img_to_page(page, *to), steps=steps)
+    page.mouse.up()
+    page.wait_for_timeout(80)
+
+
+@pytest.mark.usefixtures("interact_page")
+class TestLockedCentreDrag:
+    def test_body_drag_does_not_move_a_locked_circle(self, interact_page):
+        """THE regression. Grab the centre and pull: nothing about the widget
+        may change — not even transiently, which is why the assertion is on
+        every event and not only the last one."""
+        page = _setup(interact_page, lock_center=True)
+
+        _drag(page, (16, 16), (24, 24))
+
+        moved = [e for e in _get_events(page)
+                 if e.get("cx") is not None
+                 and (abs(e["cx"] - 16.0) > 0.5 or abs(e["cy"] - 16.0) > 0.5)]
+        assert not moved, (
+            f"a locked circle's centre moved during the drag: {moved[:3]}")
+
+    def test_an_unlocked_circle_still_moves(self, interact_page):
+        """The counterpart, so a lock that accidentally applied to every circle
+        would fail here rather than passing the whole file."""
+        page = _setup(interact_page, lock_center=False)
+
+        _drag(page, (16, 16), (20, 22))
+
+        last = _get_events(page, "pointer_up")[-1]
+        assert last["cx"] > 16.0 and last["cy"] > 16.0
+        assert last["r"] == pytest.approx(6.0, abs=0.5)
+
+    def test_the_radius_handle_still_drags_when_locked(self, interact_page):
+        """A locked centre must not cost the measurement. The handle sits at
+        the east point (cx+r, cy) = (22, 16); drag it out to (26, 16)."""
+        page = _setup(interact_page, lock_center=True)
+
+        _drag(page, (22, 16), (26, 16))
+
+        ups = _get_events(page, "pointer_up")
+        assert ups, "the radius drag should still emit a pointer_up"
+        last = ups[-1]
+        assert last["r"] > 6.0, "the radius handle stopped working under the lock"
+        assert last["cx"] == pytest.approx(16.0, abs=0.5)
+        assert last["cy"] == pytest.approx(16.0, abs=0.5)
+
+    def test_a_locked_ring_band_is_not_grabbable_either(self, interact_page):
+        """Not just the centre hotspot: the ring BAND is the circle's move
+        target, and it is the part a user actually grabs. (22, 16) is the
+        handle, so aim at the west point (10, 16) — same band, no handle."""
+        page = _setup(interact_page, lock_center=True)
+
+        _drag(page, (10, 16), (4, 16))
+
+        moved = [e for e in _get_events(page)
+                 if e.get("cx") is not None and abs(e["cx"] - 16.0) > 0.5]
+        assert not moved, f"the ring band dragged the locked circle: {moved[:3]}"

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/anyplotlib/tests/test_plot2d/test_imshow.py

@@ -575,6 +575,60 @@ class TestImshowOverlayMask:
         with pytest.raises(ValueError, match="mask shape"):
             plot.set_overlay_mask(bad_mask)
 
+    def test_overlay_mask_in_TILE_mode_ships_the_overview_size(self):
+        """The mask must be sized for what the RENDERER checks.
+
+        The renderer sizes the mask against ``base_width || image_width`` — the
+        OVERVIEW grid — and on a mismatch sets ``maskCache=null``: no error, no
+        overlay, nothing in the log. Tile mode sets ``image_width`` to the FULL
+        native frame, so validating a mask only against the image shape both
+        rejected the one shape that renders and accepted the one the renderer
+        drops. A caller that did the reduction itself got a ValueError; one that
+        did not got 22 MB of bytes silently discarded.
+
+        Either shape in, overview-sized bytes out.
+        """
+        import base64
+
+        plot = apl.subplots(1, 1)[1].imshow(
+            np.zeros((2048, 2048), np.uint8), tile="auto")
+        st = plot._state
+        bw, bh = st.get("base_width"), st.get("base_height")
+        assert bw and bh and (bw, bh) != (st["image_width"], st["image_height"]), \
+            "this test needs a genuinely tiled plot with a smaller base grid"
+
+        for shape in [(st["image_height"], st["image_width"]), (bh, bw)]:
+            mask = np.zeros(shape, bool)
+            mask[::5, ::5] = True
+            plot.set_overlay_mask(mask)
+            sent = base64.b64decode(st["overlay_mask_b64"])
+            assert len(sent) == bw * bh, (
+                f"a {shape} mask shipped {len(sent)} bytes; the renderer "
+                f"expects {bw * bh} and drops anything else silently")
+            assert any(sent), "the reduction emptied the mask"
+
+    def test_overlay_mask_reduction_is_block_ANY_not_a_subsample(self):
+        """A single-pixel object 4 blocks in must survive the reduction.
+
+        Objects here are often a few pixels across; a strided sample of a 2048²
+        mask at 512² keeps one pixel in sixteen and drops them at random.
+        """
+        import base64
+
+        plot = apl.subplots(1, 1)[1].imshow(
+            np.zeros((2048, 2048), np.uint8), tile="auto")
+        st = plot._state
+        bw, bh = st["base_width"], st["base_height"]
+        mask = np.zeros((st["image_height"], st["image_width"]), bool)
+        # Deliberately NOT on a block boundary — a subsample would miss it.
+        mask[537, 921] = True
+        plot.set_overlay_mask(mask)
+        sent = np.frombuffer(base64.b64decode(st["overlay_mask_b64"]), np.uint8)
+        # Bytes are 0/255, so COUNT the lit ones rather than summing them.
+        assert np.count_nonzero(sent.reshape(bh, bw)) == 1, (
+            "the single lit pixel did not survive the reduction — this is a "
+            "subsample, not a block ANY")
+
     def test_set_overlay_mask_alpha_boundary(self):
         plot = _img(n=16)
         mask = np.zeros((16, 16), dtype=bool)

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/anyplotlib/widgets/_widgets2d.py

@@ -74,13 +74,29 @@ class CircleWidget(Widget):
         Outline stroke width in px. Default 2.
     show_handles : bool, optional
         Draw the radius grab handle. Default ``True``.
+    lock_center : bool, optional
+        Pin ``cx, cy`` and let only the radius change. Default ``False``.
+
+        The centre is refused at HIT-TEST time, not corrected afterwards: a
+        grab on the ring body is simply not a widget grab, so it falls through
+        to the plot's own pan and the hover cursor never promises a move.
+        Enforcing it from Python instead — snapping the centre back when the
+        drag settles — cannot work, because the JS drag recomputes the position
+        from its own grab-time snapshot on every frame; the ring tracks the
+        cursor for the whole drag and only jumps back on release.
+
+        Use it when the centre is not a free parameter — a ring on a power
+        spectrum is centred on the DC term, so a draggable centre is a control
+        that can only ever be wrong, and one nudged off-centre silently
+        corrupts every radius measured from it.
     """
     def __init__(self, push_fn, *, cx, cy, r, color="#00e5ff",
-                 linewidth=2, show_handles=True):
+                 linewidth=2, show_handles=True, lock_center=False):
         super().__init__("circle", push_fn,
                          cx=float(cx), cy=float(cy), r=float(r), color=color,
                          linewidth=float(linewidth),
-                         show_handles=bool(show_handles))
+                         show_handles=bool(show_handles),
+                         lock_center=bool(lock_center))
 
 
 class AnnularWidget(Widget):

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/docs/_root/index.html

@@ -4,12 +4,12 @@
     <meta charset="utf-8" />
     <title>anyplotlib – redirecting…</title>
     <!-- Redirect to the latest dev docs. -->
-    <meta http-equiv="refresh" content="0; url=v0.7.1/" />
-    <link rel="canonical" href="v0.7.1/" />
+    <meta http-equiv="refresh" content="0; url=v0.7.3/" />
+    <link rel="canonical" href="v0.7.3/" />
   </head>
   <body>
     <p>
-      Redirecting to <a href="v0.7.1/">v0.7.1 documentation</a>…
+      Redirecting to <a href="v0.7.3/">v0.7.3 documentation</a>…
     </p>
   </body>
 </html>

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/docs/_root/switcher.json

@@ -4,6 +4,16 @@
     "version": "dev",
     "url": "https://cssfrancis.github.io/anyplotlib/dev/"
   },
+  {
+    "name": "v0.7.3 (stable)",
+    "version": "v0.7.3",
+    "url": "https://cssfrancis.github.io/anyplotlib/v0.7.3/"
+  },
+  {
+    "name": "v0.7.2 (stable)",
+    "version": "v0.7.2",
+    "url": "https://cssfrancis.github.io/anyplotlib/v0.7.2/"
+  },
   {
     "name": "v0.7.1 (stable)",
     "version": "v0.7.1",

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/docs/conf.py

@@ -17,7 +17,7 @@ from _sg_html_scraper import ViewerScraper  # noqa: E402
 project = "anyplotlib"
 copyright = "2026, anyplotlib contributors"
 author = "anyplotlib contributors"
-release = "0.7.1"
+release = "0.7.3"
 
 # When built in CI the workflow sets DOCS_VERSION to the tag name (e.g.
 # "v0.1.0") or "dev".  Fall back to "dev" for local builds.

{anyplotlib-0.7.1 → anyplotlib-0.7.3}/pyproject.toml

@@ -13,7 +13,7 @@ exclude = [
 
 [project]
 name = "anyplotlib"
-version = "0.7.1"
+version = "0.7.3"
 description = "A plotting library using python, javascript and anywidget for performant in browser plotting."
 readme = "README.md"
 license = { text = "MIT" }