Interactive Widgets#

anyplotlib.widgets — interactive overlay widget classes.

Base Class

Widget

Base class for all overlay widgets.

Concrete Widgets

`RectangleWidget`	Draggable rectangle overlay widget for 2-D plots.
`CircleWidget`	Draggable circle overlay widget for 2-D plots.
`AnnularWidget`	Draggable annular (ring) overlay widget for 2-D plots.
`CrosshairWidget`	Draggable crosshair overlay widget for 2-D plots.
`PolygonWidget`	Draggable polygon overlay widget for 2-D plots.
`BrushWidget`	Freehand paint-brush overlay widget for 2-D plots.
`LabelWidget`	Text label overlay widget for 2-D plots.
`VLineWidget`	Draggable vertical line overlay widget for 1-D plots.
`HLineWidget`	Draggable horizontal line overlay widget for bar charts.
`RangeWidget`	Draggable range selection widget.

Full Reference

class anyplotlib.widgets.Widget(wtype, push_fn, **kwargs)[source]

Bases: _EventMixin

Base class for all overlay widgets.

Provides attribute-based state access, callbacks for interaction events, and automatic synchronization with the JavaScript renderer.

Parameters:

wtype (str) – Widget type (e.g., ‘rectangle’, ‘circle’, ‘crosshair’).
push_fn (Callable) – Zero-arg callback to send position updates to the JavaScript renderer.
**kwargs (dict) – Initial widget state (position, size, color, etc.).

callbacks

Event callback registry. Register handlers via widget.add_event_handler(fn, "pointer_move") or as a decorator: @widget.add_event_handler("pointer_move").

Common event types:

"pointer_move" — fires on every drag frame
"pointer_up" — fires once when drag settles
"pointer_down" — fires on click/press event

Type:: CallbackRegistry

set(_push=True, _notify=True, **kwargs)[source]

Update properties and send targeted update to JavaScript.

Parameters:

_push (bool, optional) – Whether to push update to renderer. Default True. Set to False internally to avoid echo loops.
_notify (bool, optional) –
Whether to fire pointer_move callbacks. Default True.

A set() from Python is otherwise indistinguishable from a user drag: handlers that react to the widget moving will run, and one that writes back to the widget feeds into itself. Pass _notify=False when you are the one moving the widget and the handlers are only meant to hear about user input:
```
widget.set(_notify=False, x=new_x)
```
This supersedes wrapping the call in pause_events(), which suppresses every event type for the duration rather than just this update’s echo.
**kwargs (dict) – Properties to update (e.g., x=100, y=50, radius=20).

Return type:

None

Notes

Both flags are spelled with a leading underscore so they can never collide with a widget property of the same name in **kwargs.

Updates are sent as targeted widget updates, not full panel re-renders. This is more efficient for frequent updates during dragging.

get(key, default=None)[source]

Get a widget property by name.

Parameters:

key (str) – Property name.
default (optional) – Default value if property not found.

Returns:

The property value.

Return type:

object

to_dict()[source]

Return a dict copy of the widget state.

Returns:: All widget properties including id and type.
Return type:: dict

property visible: bool: True if the widget is rendered; False if hidden.

show()[source]

Show the widget. Does not fire pointer_move callbacks.

Return type:: None

hide()[source]

Hide the widget without removing it or its callbacks.

Call show() to make it visible again. Does not fire pointer_move callbacks.

Return type:: None

remove()[source]

Remove this widget from the plot that owns it.

Equivalent to plot.remove_widget(widget), but callable when you only hold the widget — handle-based APIs otherwise have to re-derive the owning plot to delete something they already have.

Removing a widget that is not attached to a plot, or removing twice, is a no-op.

Return type:: None

property id: str: Return the widget’s unique identifier.

class anyplotlib.widgets.RectangleWidget(push_fn, *, x, y, w, h, color='#00e5ff', linewidth=2, show_handles=True, max_extent=None)[source]

Bases: Widget

Draggable rectangle overlay widget for 2-D plots.

Parameters:

push_fn (Callable) – Update callback.
x (float) – Top-left corner position in pixel/data coordinates.
y (float) – Top-left corner position in pixel/data coordinates.
w (float) – Width and height in pixel/data coordinates.
h (float) – Width and height in pixel/data coordinates.
color (str, optional) – CSS colour for the rectangle outline. Default "#00e5ff".
linewidth (float, optional) – Outline stroke width in px. Default 2.
show_handles (bool, optional) – Draw the corner grab handles. Default True.
max_extent (float or (float, float), optional) –
Maximum width/height in the widget’s coordinates. A scalar caps both axes; a (max_w, max_h) pair caps them separately. When set, the rectangle physically stops growing at the cap while dragging — the dragged corner pins and the opposite corner stays put. None (default) leaves it unbounded.

Use this when the rectangle’s area costs real work downstream — e.g. an integrating ROI whose size is a number of frames to read.

class anyplotlib.widgets.CircleWidget(push_fn, *, cx, cy, r, color='#00e5ff', linewidth=2, show_handles=True)[source]

Bases: Widget

Draggable circle overlay widget for 2-D plots.

Parameters:

push_fn (Callable) – Update callback.
cx (float) – Center position in pixel/data coordinates.
cy (float) – Center position in pixel/data coordinates.
r (float) – Radius in pixel/data coordinates.
color (str, optional) – CSS colour for the circle outline. Default "#00e5ff".
linewidth (float, optional) – Outline stroke width in px. Default 2.
show_handles (bool, optional) – Draw the radius grab handle. Default True.

class anyplotlib.widgets.AnnularWidget(push_fn, *, cx, cy, r_outer, r_inner, color='#00e5ff', linewidth=2, show_handles=True)[source]

Bases: Widget

Draggable annular (ring) overlay widget for 2-D plots.

Parameters:

push_fn (Callable) – Update callback.
cx (float) – Center position in pixel/data coordinates.
cy (float) – Center position in pixel/data coordinates.
r_outer (float) – Outer and inner radii in pixel/data coordinates. Inner radius must be less than outer radius.
r_inner (float) – Outer and inner radii in pixel/data coordinates. Inner radius must be less than outer radius.
color (str, optional) – CSS colour for the ring outline. Default "#00e5ff".
linewidth (float, optional) – Outline stroke width in px. Default 2.
show_handles (bool, optional) – Draw the inner/outer radius grab handles. Default True.

Raises:

ValueError – If r_inner >= r_outer.

class anyplotlib.widgets.CrosshairWidget(push_fn, *, cx, cy, color='#00e5ff', linewidth=2, show_handles=True)[source]

Bases: Widget

Draggable crosshair overlay widget for 2-D plots.

Parameters:

push_fn (Callable) – Update callback.
cx (float) – Center position in pixel/data coordinates.
cy (float) – Center position in pixel/data coordinates.
color (str, optional) – CSS colour for the crosshair. Default "#00e5ff".
linewidth (float, optional) – Line stroke width in px. Default 2.
show_handles (bool, optional) – Draw the centre dot handle. Default True.

class anyplotlib.widgets.PolygonWidget(push_fn, *, vertices, color='#00e5ff', linewidth=2, show_handles=True)[source]

Bases: Widget

Draggable polygon overlay widget for 2-D plots.

Parameters:

push_fn (Callable) – Update callback.
vertices (list of tuple) – Polygon vertices [(x0, y0), (x1, y1), ...] in pixel/data coordinates. Must have at least 3 vertices.
color (str, optional) – CSS colour for the polygon outline. Default "#00e5ff".
linewidth (float, optional) – Outline stroke width in px. Default 2.
show_handles (bool, optional) – Draw the per-vertex grab handles. Default True.

Raises:

ValueError – If fewer than 3 vertices provided.

class anyplotlib.widgets.BrushWidget(push_fn, *, radius=8.0, color='#00e5ff', colors=None, class_id=0, strokes=None, stroke_classes=None, alpha=0.6, active=True, erase=False)[source]

Bases: Widget

Freehand paint-brush overlay widget for 2-D plots.

Shift-drag on the image to paint a stroke; every stroke is a polyline of image-pixel points, stroked with round caps and joins at a width of 2 * radius image pixels. Built for labelling regions — painting training scribbles for a pixel classifier, marking a defect, masking a beam stop — where a polygon or a rectangle is the wrong shape.

Two gates govern the painting so a brush can coexist with pan / click / other widgets on the same panel:

active — Python-side arming. False keeps the strokes drawn but ignores all input, which is how you park the tool without losing work.
Shift — the drag modifier. A bare drag still pans the image and still drags other widgets; only Shift + drag paints. A brush that claimed a plain drag would hit-test as “anywhere in the image” and kill panning and click-to-select outright.

Painting is modal: while a brush is armed, a Shift-press that starts over the image is consumed by the brush and no longer produces a panel pointer_down. If the host binds Shift-click to something else (multi-select is the common one), give it a different modifier or set active=False while that mode is on. A Shift-drag beginning outside the image — in the axis margin — is not a brush gesture and pans as usual.

While the stroke is being drawn the points accumulate in the browser and only the finished stroke reaches Python, once, as a pointer_up event. So pointer_move does not fire for a brush stroke — register on pointer_up:

brush = plot.add_brush_widget(radius=6, colors=["#f44", "#4f4"])

@brush.add_event_handler("pointer_up")
def stroke_done(event):
    update_labels(brush.strokes, brush.stroke_classes)

Parameters:

push_fn (Callable) – Update callback.
radius (float, optional) – Brush radius in image pixels — the painted band is 2 * radius wide, and an erase drag removes stroke points within this distance. Default 8.
color (str, optional) – CSS colour used when colors has no entry for a stroke’s class. Default "#00e5ff".
colors (list of str, optional) – Per-class CSS colours, indexed by class_id. Lets one brush carry several label classes at once. Default None (every class draws in color).
class_id (int, optional) – Label class new strokes are tagged with. Default 0.
strokes (list, optional) – Pre-existing strokes, [[[x, y], ...], ...] in image-pixel coordinates. Default None (empty).
stroke_classes (list of int, optional) – Class id per entry of strokes; must be the same length. Default None (every seeded stroke takes class_id).
alpha (float, optional) – Stroke opacity in [0, 1]. Default 0.6 — a scribble you can see the image through, since the point is to label what is underneath.
active (bool, optional) – Accept Shift-drag painting. Default True.
erase (bool, optional) – When True an armed drag removes stroke points within radius instead of painting. Default False.

strokes

Painted strokes, [[[x, y], ...], ...] in image pixels. Read-only in practice — mutating the list in place does not reach the renderer; use add_stroke() / set_strokes() / clear_strokes().

Type:: list

stroke_classes

Class id of each stroke, parallel to strokes.

Type:: list of int

Raises:: ValueError – If radius <= 0, class_id < 0, alpha is outside [0, 1], colors is not a sequence of strings, a stroke is malformed, or stroke_classes does not match strokes in length.