anyplotlib 0.7.2__tar.gz → 0.8.0__tar.gz

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

@@ -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 9,285 lines.
+the 2-D function table). Both were last verified at 10,119 lines.
 
 Changelog entries: add a fragment file to `upcoming_changes/` (e.g.
 `123.new_feature.rst`) — towncrier assembles `CHANGELOG.rst` at release time.

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

@@ -10,6 +10,69 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.8.0 (2026-08-25)
+==================
+
+API and Behaviour Changes
+-------------------------
+
+- In tile mode, ``set_data``/``update_tile_source`` now re-derive the quantisation band
+  ``raw_min``/``raw_max`` from the incoming frame when the current band is unset or
+  degenerate (it previously stayed as first derived, even from a flat placeholder). A
+  band that is already valid is still never re-derived, so a contrast change keeps
+  re-windowing in the LUT with no pixel re-encode. One visible consequence: a tiled plot
+  born on a placeholder now quantises subsequent frames over the frame's own range
+  rather than the display window, matching what ``imshow`` of a large frame has always
+  done — so its wire bytes can differ by a rounding step from the equivalent untiled
+  plot, while the displayed image is unchanged. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+
+
+New Features
+------------
+
+- Added :meth:`~anyplotlib.plot2d.Plot2D.set_tile_band` to pin the fixed quantisation
+  band tile bytes are encoded over, for a consumer that already knows the honest range
+  (a camera's bit depth, a detector's saturation point) or whose source starts flat and
+  so has no range to auto-derive. It re-samples the overview and any active detail tile
+  over the new band in a single push, replacing the practice of reaching into
+  ``plot._state["raw_min"/"raw_max"]`` and calling ``update_tile_source()`` by hand. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+- Added :meth:`~anyplotlib.plot2d.Plot2D.set_display_window`, which moves the
+  contrast window without re-quantising the pixels — the non-destructive
+  counterpart to :meth:`~anyplotlib.plot2d.Plot2D.set_clim`, and what lets a
+  saved page be re-windowed with no Python behind it. (`#61 <https://github.com/CSSFrancis/anyplotlib/pull/61>`_)
+
+
+Bug Fixes
+---------
+
+- Fixed a tiled 2-D image rendering solid black when tile mode was entered on a flat
+  placeholder frame (e.g. ``imshow`` of zeros before real data exists). The fixed
+  quantisation band ``raw_min``/``raw_max`` was derived from that placeholder — a
+  degenerate ``(0, 0)`` — and no later ``set_data`` re-derived it, leaving the two ends
+  of the protocol disagreeing about what it meant: the Python encoder treats a
+  degenerate band as unset and quantises over the display window, while the renderer
+  honoured ``(0, 0)`` and mapped every code below the display floor. The panel rendered
+  black on the WebGPU and Canvas2D paths alike, beside perfectly healthy stats and
+  histograms, with no warning. ``set_data`` and ``update_tile_source`` now re-derive a
+  degenerate band from the incoming frame, and the renderer falls back to the display
+  window for a degenerate band in tile mode — in the image LUT and in the colorbar
+  tick placement, which read the band the same way. (`#60 <https://github.com/CSSFrancis/anyplotlib/pull/60>`_)
+
+
+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)
 ==================
 

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

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

{anyplotlib-0.7.2 → anyplotlib-0.8.0}/anyplotlib/FIGURE_ESM.md

@@ -59,20 +59,20 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 | `_createInsetDOM` / `_applyAllInsetStates` | 1129 / 1512 |
 | `_resizePanelDOM` | 2225 |
 | **2D drawing**: `_imgFitRect` | 2384 |
-| `draw2d` | 2692 |
-| `drawScaleBar2d` / `drawColorbar2d` | 2887 / 3125 |
-| **Floating keys**: `_keyEnsure` / `_keyRect` / `drawKeys` | 2986 / 3009 / 3022 |
-| `_drawAxes2d` (ticks, labels, title) | 3180 |
-| `drawOverlay2d` / `drawMarkers2d` | 3333 / 3497 |
-| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2512 / 2536 / 2597 |
+| `draw2d` | 2713 |
+| `drawScaleBar2d` / `drawColorbar2d` | 2908 / 3188 |
+| **Floating keys**: `_keyEnsure` / `_keyRect` / `drawKeys` | 3007 / 3030 / 3043 |
+| `_drawAxes2d` (ticks, labels, title) | 3242 |
+| `drawOverlay2d` / `drawMarkers2d` | 3395 / 3559 |
+| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2533 / 2557 / 2618 |
 | Binary-bytes splice: `_spliceBinaryBytes` / `_registerBinaryPixelListeners` | 730 / 761 |
-| **3D drawing**: `draw3d` | 5236 |
-| Event emission `_emitEvent` | 6073 |
-| 3D event handlers `_attachEvents3d` | 6125 |
-| **1D drawing**: `draw1d` | 6346 |
-| `_drawLine` (1D series + markers) | 6499 |
-| `drawOverlay1d` / `drawMarkers1d` | 6792 / 6876 |
-| Marker hit-test `_markerHitTest2d` | 7144 |
+| **3D drawing**: `draw3d` | 5298 |
+| Event emission `_emitEvent` | 6135 |
+| 3D event handlers `_attachEvents3d` | 6187 |
+| **1D drawing**: `draw1d` | 6408 |
+| `_drawLine` (1D series + markers) | 6561 |
+| `drawOverlay1d` / `drawMarkers1d` | 6854 / 6938 |
+| Marker hit-test `_markerHitTest2d` | 7206 |
 
 > **`raster` marker (1D/PlotXY)** — `drawMarkers1d` has a `type==='raster'`
 > branch that blits a single RGBA image across data-coord `extent` (the fast
@@ -81,16 +81,16 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 > redraws never re-transmit them; the decoded `OffscreenCanvas` is cached on
 > the marker set (`ms._rasterBmp`/`_rasterKey`). The shared `clip_path` block
 > clips it to a curved sector.
-| Panel event dispatch `_attachPanelEvents` | 7401 |
-| 2D events `_attachEvents2d` | 7443 |
-| 1D events `_attachEvents1d` | 7827 |
-| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 8099 / 8372 |
-| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8285 / 8299 / 8328 / 8363 |
-| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8495 / 8568 |
-| Shared-axis propagation `_getShareGroups` | 8639 |
-| Figure resize `_applyFigResizeDOM` | 8703 |
-| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8894 / 8957 / 9333 |
-| Generic redraw `_redrawPanel` | 9523 |
+| Panel event dispatch `_attachPanelEvents` | 7463 |
+| 2D events `_attachEvents2d` | 7505 |
+| 1D events `_attachEvents1d` | 7889 |
+| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 8161 / 8440 |
+| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8353 / 8367 / 8396 / 8431 |
+| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8565 / 8638 |
+| Shared-axis propagation `_getShareGroups` | 8709 |
+| Figure resize `_applyFigResizeDOM` | 8773 |
+| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8964 / 9027 / 9403 |
+| Generic redraw `_redrawPanel` | 9593 |
 
 > **`brush` widget (2-D)** — the one widget whose drag is *modal*, and the one
 > that must NOT write the model per tick. `_ovHitTest2d` takes an extra `mods`
@@ -269,12 +269,13 @@ st.colorbar_label_size            (label font sizes; optional)
 
 | Function | Line | Purpose |
 |----------|------|---------|
-| **`_imgFitRect(iw,ih,cw,ch)`** | **2372** | Largest rect of aspect `iw:ih` centred in `cw×ch`; all 2-D coordinate functions derive from this |
-| `draw2d(p)` | 2680 | Main render: `_resizePanelDOM` → decode → LUT → ImageBitmap → blit; then mask, axes, scale bar, colorbar, overlay, markers |
-| `drawScaleBar2d(p)` | 2875 | Physical scale bar |
-| `drawColorbar2d(p)` | 2961 | Gradient strip + min/max marks + rotated label centred in the `_cbWidth` gutter |
-| `_drawAxes2d(p)` | 3016 | Ticks (edge labels nudged inward both axes), axis labels + title via `_drawTex` |
-| `drawOverlay2d(p)` / `drawMarkers2d(p)` | 3169 / 3333 | Widgets / marker groups |
+| **`_imgFitRect(iw,ih,cw,ch)`** | **2384** | Largest rect of aspect `iw:ih` centred in `cw×ch`; all 2-D coordinate functions derive from this |
+| `draw2d(p)` | 2713 | Main render: `_resizePanelDOM` → decode → LUT → ImageBitmap → blit; then mask, axes, scale bar, colorbar, overlay, markers |
+| `drawScaleBar2d(p)` | 2908 | Physical scale bar |
+| `_rawBand(st)` / `_buildLut32(st)` | 2433 / 2440 | The quantisation band the u8 bytes were encoded over, then the 256-entry LUT built from it. `_rawBand` mirrors Python `_tile_quant_clim`: a DEGENERATE band (`raw_max <= raw_min`) is UNSET and falls back to `display_min/max`. Both render paths and the colorbar go through it — honouring a `(0, 0)` band paints solid black |
+| `drawColorbar2d(p)` | 3188 | Gradient strip + min/max marks (band-relative, via `_rawBand`) + rotated label centred in the `_cbWidth` gutter |
+| `_drawAxes2d(p)` | 3242 | Ticks (edge labels nudged inward both axes), axis labels + title via `_drawTex` |
+| `drawOverlay2d(p)` / `drawMarkers2d(p)` | 3395 / 3559 | Widgets / marker groups |
 
 Zoom model: at `zoom=1` the whole image fills the fit-rect; at `zoom=Z>1` a
 `1/Z` region fills it.  `_imgToCanvas2d` / `_canvasToImg2d` must stay exact

{anyplotlib-0.7.2 → anyplotlib-0.8.0}/anyplotlib/figure_esm.js

@@ -2415,10 +2415,31 @@ function render({ model, el, onResize }) {
     };
   }
 
+  // The quantisation band the uint8 image bytes were encoded over, as [lo, hi].
+  // A DEGENERATE band (raw_max <= raw_min) means DIFFERENT things on the two
+  // encoder paths, and the LUT has to read it the way the bytes were written:
+  //
+  //   plain (_normalize_image): a constant frame quantises to ALL-ZERO bytes and
+  //     reports (c, c) — the band NAMES the single value code 0 stands for, and
+  //     hMin + raw/255 * (range||1) reconstructs it. Keep honouring it.
+  //   tile (_tile_quant_clim): a degenerate band is treated as UNSET and the
+  //     bytes are quantised over the DISPLAY window instead — so they are already
+  //     display-mapped and the LUT must be the identity window over them.
+  //
+  // Reading a tiled degenerate band the plain way is GH #60: a plot that entered
+  // tile mode on a flat placeholder carries the band (0, 0), every code maps to
+  // hMin + raw/255 * 1 in [0, 1], lands below any sane display floor, and the
+  // panel renders solid black beside perfectly healthy stats.
+  function _rawBand(st) {
+    const lo=st.raw_min, hi=st.raw_max;
+    if(lo==null||hi==null) return [st.display_min, st.display_max];
+    if(hi>lo) return [lo,hi];
+    return st.tile_enabled ? [st.display_min, st.display_max] : [lo,hi];
+  }
+
   function _buildLut32(st) {
     const dMin=st.display_min, dMax=st.display_max;
-    const hMin=st.raw_min!=null?st.raw_min:dMin;
-    const hMax=st.raw_max!=null?st.raw_max:dMax;
+    const [hMin,hMax]=_rawBand(st);
     const mode=st.scale_mode||'linear';
     const range=hMax-hMin||1;
     const cmapData=st.colormap_data||[];
@@ -3198,8 +3219,7 @@ function render({ model, el, onResize }) {
 
     // display_min / display_max tick marks
     const dMin=st.display_min, dMax=st.display_max;
-    const hMin=st.raw_min!=null?st.raw_min:dMin;
-    const hMax=st.raw_max!=null?st.raw_max:dMax;
+    const [hMin,hMax]=_rawBand(st);
     const vRange=(hMax-hMin)||1;
     function _vToY(v){return imgH-1-((v-hMin)/vRange)*(imgH-1);}
     ctx.strokeStyle='rgba(255,255,255,0.85)'; ctx.lineWidth=1.5;
@@ -8182,7 +8202,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 +8467,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.2 → anyplotlib-0.8.0}/anyplotlib/plot2d/_plot2d.py

@@ -507,11 +507,7 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         # (raw_min/raw_max fixed, display_min/display_max move) with NO pixel re-encode
         # or re-transfer — set_clim just moves the display window (see set_clim). Set
         # once from the full-res range; keep any existing band on a re-enable.
-        if (self._state.get("raw_min") is None
-                or not (self._state.get("raw_max", 0) > self._state.get("raw_min", 0))):
-            rng = self._backend_display_range(self._tile_backend)
-            if rng is not None:
-                self._state["raw_min"], self._state["raw_max"] = rng
+        self._ensure_tile_band()
         _was_on = self._tile_on
         if not self._tile_on:
             self._tile_on = True
@@ -561,6 +557,13 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             setter = getattr(self._tile_backend, "set_array", None)
             if setter is not None:
                 setter(array)
+        # The quantisation band is derived ONCE (enable_tile) and then held fixed, so
+        # a contrast change re-windows in the LUT with no pixel re-encode. But if it
+        # was never VALIDLY derived — tile mode started on a flat placeholder, so the
+        # probe refused and the band stayed degenerate — the new data in the backend
+        # is the first chance to get it right. Must run BEFORE the overview/detail are
+        # re-sampled below so they quantise over the corrected band in the SAME push.
+        self._ensure_tile_band()
         reg = self._state.get("detail_region") or []
         has_detail = len(reg) == 4
         # Refresh the overview base ONLY when no detail tile is shown (zoomed out) —
@@ -622,6 +625,70 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         except Exception as e:
             _TLOG.warning("[TILEDBG] overview refresh FAILED: %s", e)
 
+    def _ensure_tile_band(self) -> bool:
+        """Derive the fixed quantisation band (raw_min/raw_max) from the CURRENT tile
+        backend when it is unset or DEGENERATE, by the same rule _tile_quant_clim
+        uses to read it back. Returns True iff the band was (re-)derived.
+
+        The degenerate case is the one that bites: a plot that entered tile mode on a
+        flat placeholder (e.g. zeros before real data exists) probes a range of
+        (0, 0) — _backend_display_range refuses it, so the band keeps the
+        constructor's raw min/max, which for zeros is also (0, 0). Every later
+        set_data then re-sampled the overview against a band the encoder treated as
+        unset (quantising over the display window) while the frontend LUT honoured
+        (0, 0) literally and painted the panel solid black. Calling this on each data
+        swap re-derives the band as soon as a frame with real range arrives, so the
+        two ends of the protocol agree on what the bytes mean.
+        """
+        lo, hi = self._state.get("raw_min"), self._state.get("raw_max")
+        if lo is not None and hi is not None and hi > lo:
+            return False                      # a valid band is kept, never re-derived
+        if self._tile_backend is None:
+            return False
+        rng = self._backend_display_range(self._tile_backend)
+        if rng is None:
+            # Still flat (an all-constant frame): leave the band unset/degenerate —
+            # _tile_quant_clim and the JS LUT both fall back to the display window.
+            return False
+        self._state["raw_min"], self._state["raw_max"] = rng
+        _TLOG.debug("[TILEDBG] tile band (re-)derived from backend → raw=(%s,%s)",
+                    *rng)
+        return True
+
+    def set_tile_band(self, vmin: float, vmax: float) -> None:
+        """PIN the fixed quantisation band the tile bytes are encoded over.
+
+        Tile mode normally derives this band once, from the full-res data (see
+        ``enable_tile``), and then holds it: a contrast change re-windows in the LUT
+        with no pixel re-encode or re-transfer. A live consumer that already KNOWS the
+        honest range — a camera's bit depth, a detector's saturation point — can pin
+        it here instead of letting the first frame decide, so the contrast doesn't
+        shift when a later frame happens to contain a brighter pixel.
+
+        Pinning also survives what auto-derivation cannot: a source whose first frames
+        are flat (a placeholder, a closed shutter) has no range to derive from, and
+        the band stays unset until a frame with real content arrives.
+
+        Re-samples the overview (and any active detail tile) over the new band in a
+        single push, so the pixels and the band the renderer reads them with never
+        disagree. Raises if the plot is not in tile mode or the range is degenerate."""
+        if not self._tile_on:
+            raise RuntimeError(
+                "set_tile_band requires tile mode — the band is the quantisation "
+                "range for the TILE bytes. Call enable_tile() first (or use "
+                "set_clim() to change the display window on a plain plot).")
+        lo, hi = float(vmin), float(vmax)
+        if not (hi > lo):
+            raise ValueError(
+                f"set_tile_band requires vmax > vmin, got ({lo}, {hi}). A degenerate "
+                f"band is what 'unset' means here — both the encoder and the "
+                f"renderer then fall back to the display window.")
+        self._state["raw_min"], self._state["raw_max"] = lo, hi
+        # Re-encode over the new band. update_tile_source() with no array re-samples
+        # from the backend in place (keeping zoom/center and the detail region) and
+        # pushes — so the band and the bytes it describes ship together.
+        self.update_tile_source()
+
     def _tile_quant_clim(self):
         """The FIXED quantisation band (raw_min/raw_max) the tile bytes are encoded
         over, so a contrast change re-windows in the LUT without re-encoding pixels.
@@ -1470,7 +1537,11 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
         raw frame, not merely re-windowing the existing codes (which are saturated
         outside the previous band and so couldn't widen past it). For an RGB frame
         (no scalar quantisation) or when no raw frame is cached, fall back to a pure
-        display-window update."""
+        display-window update.
+
+        See :meth:`set_display_window` for the non-destructive counterpart — the
+        one to reach for when the pixels must not move (a tiled plot, or a
+        serialised figure being re-windowed with no Python behind it)."""
         new_min = float(vmin) if vmin is not None else self._state.get("display_min")
         new_max = float(vmax) if vmax is not None else self._state.get("display_max")
 
@@ -1512,6 +1583,40 @@ class Plot2D(_BasePlot, _PanelMixin, _MarkerMixin):
             self._state["display_max"] = float(vmax)
         self._push()
 
+    def set_display_window(self, vmin=None, vmax=None) -> None:
+        """Move the display window WITHOUT re-quantising the pixels.
+
+        The non-destructive counterpart to :meth:`set_clim`. Both change the
+        contrast; they differ in what they do to the data behind it:
+
+        ``set_clim``
+            re-encodes the cached raw frame over the new range, so the codes
+            always span exactly the visible band — maximum precision for what is
+            on screen, but the pixels are re-encoded and re-sent, and the old
+            band is gone.
+        ``set_display_window``
+            leaves the codes and their ``raw_min``/``raw_max`` band alone and
+            moves only the window the LUT maps through it. Nothing is re-encoded
+            and nothing travels but two floats.
+
+        Use it when the pixels must stay put: a tiled plot, where re-quantising
+        would re-encode the full-res frame on every drag tick (``set_clim``
+        already routes there internally), or a figure that has been serialised
+        and is being re-windowed with no Python behind it — which is how a saved
+        page gets a working contrast control at all.
+
+        The trade is precision. Quantisation spans ``[raw_min, raw_max]``, so a
+        window much narrower than that band resolves in coarse steps, and one
+        WIDER than it recovers nothing: values outside the band were saturated
+        to 0/255 when the frame was encoded. Quantise over the range you want to
+        be able to reach.
+        """
+        if vmin is not None:
+            self._state["display_min"] = float(vmin)
+        if vmax is not None:
+            self._state["display_max"] = float(vmax)
+        self._push()
+
     def set_detail(self, tile=None, x0=None, x1=None, y0=None, y1=None) -> None:
         """Upload a HIGH-RES detail tile covering the LOGICAL image-pixel rectangle
         ``[x0:x1, y0:y1]`` of the base image (in the SAME orientation as the frame
@@ -1731,15 +1836,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.8.0/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]}"