Figure Plots#

figure_plots.py#

Pure-Python plot objects returned by Axes.imshow() / Axes.plot().

These are NOT anywidget subclasses. They hold all state in plain dicts and push changes into the parent Figure’s per-panel traitlet via _push().

Public classes#

GridSpec – describes a grid layout (nrows x ncols, ratios). SubplotSpec – a slice of a GridSpec (row/col spans). Axes – a grid cell; .imshow() / .plot() return a plot object. Plot2D – 2-D image panel, full Viewer2D-compatible API. Plot1D – 1-D line panel, full Viewer1D-compatible API.

Axes

Axes

A single grid cell in a Figure.

InsetAxes

A floating inset sub-plot that overlays the main Figure grid.

Plot Classes

Plot1D

1-D line plot panel returned by Axes.plot().

Plot2D

2-D image plot panel.

PlotMesh

2-D mesh plot panel created by Axes.pcolormesh().

Plot3D

3-D plot panel.

PlotBar

Bar-chart plot panel.

Layout

GridSpec

Define a grid of subplot cells.

SubplotSpec

Describes which grid cells a subplot occupies.

Full Reference

class anyplotlib.figure_plots.Axes(fig, spec)[source]

Bases: object

A single grid cell in a Figure.

Returned by Figure.add_subplot() and Figure.subplots(). Call .imshow() or .plot() to attach a data plot and get back a Plot2D or Plot1D object.

Parameters:
imshow(data, axes=None, units='px', cmap=None, vmin=None, vmax=None, origin='upper')[source]

Attach a 2-D image to this axes cell.

Parameters:

  • data (np.ndarray, shape (H, W) or (H, W, C)) – Image data. RGB/RGBA arrays use only the first channel.

  • axes ([x_axis, y_axis], optional) – Physical coordinate arrays for each axis.

  • units (str, optional) – Axis units label. Default "px".

  • cmap (str, optional) – Colormap name (e.g. "viridis", "inferno"). Defaults to "gray".

  • vmin (float, optional) – Colormap clipping limits in data units. Values outside this range are clamped to the colormap endpoints. Defaults to the data min / max.

  • vmax (float, optional) – Colormap clipping limits in data units. Values outside this range are clamped to the colormap endpoints. Defaults to the data min / max.

  • origin ("upper" | "lower", optional) – Where row 0 of the array is placed. "upper" (default) puts row 0 at the top, matching the usual image convention. "lower" puts row 0 at the bottom, matching the matplotlib convention for matrices / scientific plots.

Return type:

Plot2D

pcolormesh(data, x_edges=None, y_edges=None, units='')[source]

Attach a 2-D mesh to this axes cell using edge coordinates.

Follows the matplotlib pcolormesh convention: x_edges and y_edges are the cell edge coordinates, so they have length N+1 and M+1 respectively for an (M, N) data array.

Parameters:

  • data (np.ndarray shape (M, N))

  • x_edges (array-like, length N+1, optional) – Column edge coordinates. Defaults to np.arange(N+1).

  • y_edges (array-like, length M+1, optional) – Row edge coordinates. Defaults to np.arange(M+1).

  • units (str, optional)

Return type:

PlotMesh

plot_surface(X, Y, Z, *, colormap='viridis', x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]

Attach a 3-D surface to this axes cell.

Parameters:

  • X (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.

  • Y (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.

  • Z (array-like) – 2-D grid arrays of the same shape (e.g. from np.meshgrid), or 1-D centre arrays for X/Y with a 2-D Z.

  • colormap (str, optional Matplotlib colormap name. Default 'viridis'.)

  • x_label (str, optional Axis labels.)

  • y_label (str, optional Axis labels.)

  • z_label (str, optional Axis labels.)

  • azimuth (float, optional Initial camera angles in degrees.)

  • elevation (float, optional Initial camera angles in degrees.)

  • zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

scatter3d(x, y, z, *, color='#4fc3f7', point_size=4.0, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]

Attach a 3-D scatter plot to this axes cell.

Parameters:

  • x (array-like, shape (N,) Point coordinates.)

  • y (array-like, shape (N,) Point coordinates.)

  • z (array-like, shape (N,) Point coordinates.)

  • color (str, optional CSS colour for all points.)

  • point_size (float, optional Radius of each point in pixels.)

  • x_label (str, optional Axis labels.)

  • y_label (str, optional Axis labels.)

  • z_label (str, optional Axis labels.)

  • azimuth (float, optional Initial camera angles in degrees.)

  • elevation (float, optional Initial camera angles in degrees.)

  • zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

plot3d(x, y, z, *, color='#4fc3f7', linewidth=1.5, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]

Attach a 3-D line plot to this axes cell.

Parameters:

  • x (array-like, shape (N,) Point coordinates along the line.)

  • y (array-like, shape (N,) Point coordinates along the line.)

  • z (array-like, shape (N,) Point coordinates along the line.)

  • color (str, optional CSS colour.)

  • linewidth (float, optional Stroke width in pixels.)

  • x_label (str, optional Axis labels.)

  • y_label (str, optional Axis labels.)

  • z_label (str, optional Axis labels.)

  • azimuth (float, optional Initial camera angles in degrees.)

  • elevation (float, optional Initial camera angles in degrees.)

  • zoom (float, optional Initial zoom factor.)

Return type:

Plot3D

plot(data, axes=None, units='px', y_units='', color='#4fc3f7', linewidth=1.5, linestyle='solid', ls=None, alpha=1.0, marker='none', markersize=4.0, label='')[source]

Attach a 1-D line to this axes cell.

Parameters:

  • data (array-like, shape (N,)) – Y values. Must be 1-D.

  • axes (list, optional) – [x_axis] — a one-element list containing the x-coordinates (shape (N,)). If omitted the x-axis defaults to 0, 1, …, N-1.

  • units (str, optional) – Label for the x-axis (e.g. "eV", "s"). Default "px".

  • y_units (str, optional) – Label for the y-axis. Default "" (no label).

  • color (str, optional) – CSS colour string for the line (hex, rgb(), named colour, etc.). Default "#4fc3f7".

  • linewidth (float, optional) – Stroke width in pixels. Default 1.5.

  • linestyle (str, optional) – Dash pattern. Accepted values: "solid" ("-"), "dashed" ("--"), "dotted" (":"), "dashdot" ("-.") . Default "solid".

  • ls (str, optional) – Short alias for linestyle. Takes precedence if both are given.

  • alpha (float, optional) – Line opacity in the range 0–1. Default 1.0 (fully opaque).

  • marker (str, optional) – Per-point marker symbol. Supported values: "o" (circle), "s" (square), "^" (triangle-up), "v" (triangle-down), "D" (diamond), "+" (plus), "x" (cross), "none" (no markers). Default "none".

  • markersize (float, optional) – Marker radius / half-side in pixels. Default 4.0.

  • label (str, optional) – Legend label. A legend is only drawn when at least one line has a non-empty label. Default "" (no legend entry).

Returns:

Live plot object. Call methods on it to update data, add overlays, register callbacks, etc.

Return type:

Plot1D

Examples

Basic sine wave with a physical x-axis:

import numpy as np
import anyplotlib as vw

x = np.linspace(0, 4 * np.pi, 512)
fig, ax = vw.subplots(1, 1, figsize=(620, 320))
v = ax.plot(np.sin(x), axes=[x], units="rad",
            color="#ff7043", linewidth=2, label="sin")
v  # display in a Jupyter cell

Dashed line with semi-transparent markers:

v = ax.plot(data, linestyle="dashed", alpha=0.7,
            marker="o", markersize=4)

Overlay a second curve with Plot1D.add_line():

v.add_line(np.cos(x), x_axis=x, color="#aed581", label="cos")
bar(x, height=None, width=0.8, bottom=0.0, *, align='center', color='#4fc3f7', colors=None, orient='v', log_scale=False, group_labels=None, group_colors=None, show_values=False, units='', y_units='', x_labels=None, x_centers=None, bar_width=None, baseline=None, values=None)[source]

Attach a bar chart to this axes cell.

Signature mirrors matplotlib.pyplot.bar:

ax.bar(x, height, width=0.8, bottom=0.0, ...)
Parameters:

  • x (x_labels → strings passed via) – Bar positions. Strings become category labels with auto-numeric centres; numbers are used directly as bar centres.

  • height (values →) – Bar heights. Pass a 2-D array to draw G grouped bars per category. If omitted x is treated as the heights and positions are generated automatically (backward-compatible call form).

  • width (bar_width →) – Bar width as a fraction of the category slot (0–1). Default 0.8.

  • bottom (baseline →) – Value at which bars are rooted (baseline). Default 0.

  • align ("center" | "edge", optional) – Alignment of the bar relative to its x position. Currently only "center" is rendered; stored for future use.

  • color (str, optional) – Single CSS colour applied to every bar. Default "#4fc3f7".

  • colors (list of str, optional) – Per-bar colour list (ungrouped) or ignored when group_colors is set.

  • orient ("v" | "h", optional) – Vertical (default) or horizontal orientation.

  • log_scale (bool, optional) – Use a logarithmic value axis. Non-positive values are clamped to 1e-10 for display. Default False.

  • group_labels (list of str, optional) – Legend labels for each group in a grouped bar chart.

  • group_colors (list of str, optional) – CSS colours per group. Defaults to a built-in palette.

  • show_values (bool, optional) – Draw the numeric value above / beside each bar.

  • units (str, optional) – Label for the categorical axis.

  • y_units (str, optional) – Label for the value axis.

  • aliases (Backward-compatible keyword)

  • ------------------------------------

  • height

  • x

  • width

  • bottom

  • x

Return type:

PlotBar

class anyplotlib.figure_plots.InsetAxes(fig, w_frac, h_frac, *, corner='top-right', title='')[source]

Bases: Axes

A floating inset sub-plot that overlays the main Figure grid.

Created via Figure.add_inset(). Supports the same plot-factory methods as Axes (imshow, plot, pcolormesh, etc.).

The inset is positioned at a corner of the figure and can be minimized (title bar only), maximized (expanded to fill ~72% of the figure), or restored to its normal size.

Parameters:

  • fig (Figure)

  • w_frac (float) – Width and height as fractions of the figure dimensions (0–1).

  • h_frac (float) – Width and height as fractions of the figure dimensions (0–1).

  • corner (str, optional) – One of "top-right", "top-left", "bottom-right", "bottom-left". Default "top-right".

  • title (str, optional) – Text shown in the inset title bar. Default "".

Examples

>>> fig, ax = apl.subplots(1, 1, figsize=(640, 480))
>>> ax.imshow(data)
>>> inset = fig.add_inset(0.3, 0.25, corner="top-right", title="Zoom")
>>> inset.imshow(data[64:128, 64:128])
property inset_state: str

"normal", "minimized", or "maximized".

Type:

Current state

minimize()[source]

Collapse the inset to its title bar only (idempotent).

Return type:

None

maximize()[source]

Expand the inset to ~72 % of the figure, centred (idempotent).

Return type:

None

restore()[source]

Return the inset to its normal corner position (idempotent).

Return type:

None

class anyplotlib.figure_plots.Plot1D(data, x_axis=None, units='px', y_units='', color='#4fc3f7', linewidth=1.5, linestyle='solid', alpha=1.0, marker='none', markersize=4.0, label='')[source]

Bases: object

1-D line plot panel returned by Axes.plot().

All display state is stored in a plain _state dict. Every mutation ends with _push(), which serialises the state to the parent Figure trait so the JS renderer picks up the change immediately.

Supported line properties#

Set at construction time via Axes.plot() or updated afterwards with the corresponding setter:

Parameter

Default

Description

color

"#4fc3f7"

CSS colour string for the primary line.

linewidth

1.5

Stroke width in pixels.

linestyle (ls)

"solid"

Dash pattern: "solid", "dashed", "dotted", "dashdot". Shorthands "-", "--", ":", "-." also accepted.

alpha

1.0

Line opacity (0 = transparent, 1 = fully opaque).

marker

"none"

Per-point symbol: "o" (circle), "s" (square), "^"/"v" (triangles), "D" (diamond), "+"/"x" (stroke-only), or "none".

markersize

4.0

Marker radius / half-side in pixels.

label

""

Legend label (empty string = no legend entry).

Public API summary#

Data

update() — replace y-data (and optionally the x-axis / units) without recreating the panel.

Overlay lines

add_line() / remove_line() / clear_lines() — overlay additional curves on the same axes.

Shaded spans

add_span() / remove_span() / clear_spans() — highlight a region along the x- or y-axis.

View control

set_view() / reset_view() — programmatic pan/zoom (users can also pan/zoom interactively with the mouse; press R to reset).

Interactive widgets

add_vline_widget() / add_hline_widget() / add_range_widget() — draggable overlays that report their position back to Python via callbacks. Manage them with get_widget(), remove_widget(), list_widgets(), and clear_widgets().

Static marker collections

add_points() / add_circles() / add_vlines() / add_hlines() / add_arrows() / add_ellipses() / add_lines() / add_rectangles() / add_squares() / add_polygons() / add_texts() — fixed overlays positioned at explicit data coordinates. Access them via plot.markers[type][name] and manage with remove_marker(), clear_markers(), and list_markers().

Callbacks

on_changed() / on_release() / on_click() / on_key() — react to pan/zoom frames, mouse clicks, and key-presses. Remove a handler with disconnect().

to_state_dict()[source]
Return type:

dict

property line: Line1D

Handle for the primary line, enabling per-line callbacks.

Returns a Line1D with id=None so you can register hover / click handlers scoped to just the primary line:

@plot.line.on_click
def on_primary_click(event):
    print(f"primary line clicked at x={event.x:.3f}")
property data: ndarray

The primary line’s y-data (read-only).

Returns a float64 copy with writeable=False. To replace the data call set_data().

set_data(data, x_axis=None, units=None, y_units=None)[source]

Replace the primary line’s y-data and optionally its x-axis / units.

The y-axis range (data_min / data_max) is recomputed automatically. The viewport is not reset — call reset_view() explicitly if needed.

Parameters:

  • data (array-like, shape (N,)) – New y values. Must be 1-D.

  • x_axis (array-like, shape (N,), optional) – New x coordinates. If omitted and the length of data matches the current x-axis, the existing x-axis is reused; otherwise it is reset to 0, 1, …, N-1.

  • units (str, optional) – New x-axis label. Unchanged if not supplied.

  • y_units (str, optional) – New y-axis label. Unchanged if not supplied.

Return type:

None

add_line(data, x_axis=None, color='#ffffff', linewidth=1.5, linestyle='solid', ls=None, alpha=1.0, marker='none', markersize=4.0, label='')[source]

Overlay an additional curve on this panel.

The y-axis range is automatically expanded to include the new data so all lines remain fully visible.

Parameters:

  • data (array-like, shape (N,)) – Y values for the new line. Must be 1-D.

  • x_axis (array-like, shape (N,), optional) – X coordinates. Defaults to the primary line’s x-axis.

  • color (str, optional) – CSS colour string. Default "#ffffff".

  • linewidth (float, optional) – Stroke width in pixels. Default 1.5.

  • linestyle (str, optional) – Dash pattern: "solid", "dashed", "dotted", "dashdot" (or shorthands). Default "solid".

  • ls (str, optional) – Short alias for linestyle.

  • alpha (float, optional) – Line opacity (0–1). Default 1.0.

  • marker (str, optional) – Per-point marker symbol (see Plot1D). Default "none".

  • markersize (float, optional) – Marker radius / half-side in pixels. Default 4.0.

  • label (str, optional) – Legend label. Default "" (no legend entry).

Returns:

A handle to the new overlay line. Use it to register per-line hover/click callbacks or to remove the line later:

line = v.add_line(fit, color="#ffcc00", label="fit")
line.remove()                     # remove it
@line.on_click                    # per-line click handler
def clicked(event): ...

Return type:

Line1D

remove_line(lid)[source]

Remove an overlay line by its ID or Line1D handle.

The y-axis range is recomputed after removal.

Parameters:

lid (str or Line1D) – The value returned by add_line().

Raises:

KeyError – If lid does not match any overlay line.

Return type:

None

clear_lines()[source]

Remove all overlay lines, leaving the primary line intact.

The y-axis range is recomputed after clearing.

Return type:

None

add_span(v0, v1, axis='x', color=None)[source]

Add a shaded span along the x- or y-axis.

Parameters:

  • v0 (float) – Start and end of the span in data coordinates.

  • v1 (float) – Start and end of the span in data coordinates.

  • axis ("x" | "y", optional) – Which axis the span runs along. Default "x".

  • color (str, optional) – CSS colour string (supports alpha, e.g. "rgba(255,200,0,0.2)"). Defaults to a theme-appropriate yellow tint.

Returns:

Span ID for use with remove_span().

Return type:

str

remove_span(sid)[source]

Remove a shaded span by its ID.

Parameters:

sid (str) – The ID returned by add_span().

Raises:

KeyError – If sid does not match any span.

Return type:

None

clear_spans()[source]

Remove all shaded spans.

Return type:

None

add_vline_widget(x, color='#00e5ff')[source]

Add a draggable vertical-line overlay.

Parameters:

  • x (float) – Initial x position in data coordinates.

  • color (str, optional) – CSS colour string. Default "#00e5ff".

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

VLineWidget

add_hline_widget(y, color='#00e5ff')[source]

Add a draggable horizontal-line overlay.

Parameters:

  • y (float) – Initial y position in data coordinates.

  • color (str, optional) – CSS colour string. Default "#00e5ff".

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

HLineWidget

add_range_widget(x0, x1, color='#00e5ff', style='band', y=0.0, _push=True)[source]

Add a draggable range overlay to this panel.

Parameters:

  • x0 (float) – Initial left and right edges in data coordinates.

  • x1 (float) – Initial left and right edges in data coordinates.

  • color (str, optional) – CSS colour string. Default "#00e5ff".

  • style ({'band', 'fwhm'}, optional) – Visual style. 'band' (default) draws two vertical lines with a translucent fill. 'fwhm' draws two draggable circles connected by a dashed horizontal line at y (the half-maximum level), giving an o-------o FWHM indicator.

  • y (float, optional) – Y-coordinate (data space) for the connecting line when style='fwhm'. Ignored when style='band'. Default 0.

  • _push (bool, optional) – Push state to JS immediately. Set to False when adding several widgets at once; call _push() manually afterward.

Returns:

Widget object. Register position callbacks with on_changed() / on_release().

Return type:

RangeWidget

add_point_widget(x, y, color='#00e5ff', show_crosshair=True, _push=True)[source]

Add a freely-draggable control point to this panel.

Parameters:

  • x (float) – Initial x position in data coordinates.

  • y (float) – Initial y position in data coordinates (value axis).

  • color (str, optional) – CSS colour string. Default "#00e5ff".

  • show_crosshair (bool, optional) – Draw dashed guide lines through the handle. Default True. Pass False for a plain dot with no guide lines.

  • _push (bool, optional) – Push state to JS immediately. Set to False when adding several widgets at once; call _push() manually afterward.

Return type:

PointWidget

get_widget(wid)[source]

Return the Widget object by ID string or Widget instance.

Return type:

Widget

remove_widget(wid)[source]

Remove a widget by ID string or Widget instance.

Return type:

None

list_widgets()[source]

Return a list of all active widget objects on this panel.

Return type:

list

clear_widgets()[source]

Remove all interactive overlay widgets from this panel.

Return type:

None

on_changed(fn)[source]

Decorator: fires on every drag/zoom frame on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_release(fn)[source]

Decorator: fires once when drag/zoom settles on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_click(fn)[source]

Decorator: fires on click on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_key(key_or_fn=None)[source]

Register a key-press handler for this panel.

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, phys_x, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:

Callable

disconnect(cid)[source]

Remove the callback registered under integer cid.

Parameters:

cid (int)

Return type:

None

on_line_hover(fn)[source]

Decorator: fires when the cursor moves over any line on this panel.

The event carries event.line_id (None = primary line, str = overlay), event.x, and event.y in data coordinates. For per-line filtering use Line1D.on_hover() instead.

Parameters:

fn (Callable)

Return type:

Callable

on_line_click(fn)[source]

Decorator: fires when the user clicks any line on this panel.

The event carries the same fields as on_line_hover(). For per-line filtering use Line1D.on_click() instead.

Parameters:

fn (Callable)

Return type:

Callable

set_view(x0=None, x1=None)[source]

Programmatically set the visible x range.

Parameters:

  • x0 (float, optional) – Left edge of the view in data coordinates. None keeps the current left edge.

  • x1 (float, optional) – Right edge of the view in data coordinates. None keeps the current right edge.

Return type:

None

reset_view()[source]

Reset the view to show the full x range of the primary line.

Return type:

None

set_color(color)[source]

Set the primary line colour.

Parameters:

color (str) – Any CSS colour string (hex, rgb(), named colour, etc.).

Return type:

None

set_linewidth(linewidth)[source]

Set the primary line stroke width.

Parameters:

linewidth (float) – Stroke width in pixels.

Return type:

None

set_linestyle(linestyle)[source]

Set the primary line dash pattern.

Parameters:

linestyle (str) – "solid" ("-"), "dashed" ("--"), "dotted" (":"), or "dashdot" ("-.")

Return type:

None

set_alpha(alpha)[source]

Set the primary line opacity.

Parameters:

alpha (float) – Opacity in the range 0 (transparent) to 1 (fully opaque).

Return type:

None

set_marker(marker, markersize=None)[source]

Set the primary line per-point marker symbol.

Parameters:

  • marker (str) – "o", "s", "^", "v", "D", "+", "x", or "none".

  • markersize (float, optional) – Marker radius / half-side in pixels. Unchanged if not supplied.

Return type:

None

add_circles(offsets, name=None, *, radius=5, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add circle markers at explicit (x, y) positions.

On 1-D panels circles are rendered as filled/stroked discs; radius is in canvas pixels (not data units).

Parameters:

  • offsets (array-like, shape (N, 2)) – Marker positions as [[x0, y0], [x1, y1], …] in data coordinates.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • radius (float or array-like, optional) – Radius in pixels. Scalar or per-marker array. Default 5.

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • edgecolors (str, optional) – Stroke colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-marker tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Returns:

Live group object. Call .set(**kwargs) to update in place.

Return type:

MarkerGroup

add_points(offsets, name=None, *, sizes=5, color='#ff0000', facecolors=None, linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add point markers at (x, y) positions in data coordinates.

Parameters:

  • offsets (array-like, shape (N, 2)) – Marker positions as [[x0, y0], [x1, y1], …].

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • sizes (float or array-like, optional) – Radius in pixels. Scalar or per-marker array. Default 5.

  • color (str, optional) – Stroke colour. Default "#ff0000".

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-marker tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_hlines(y_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add static horizontal lines spanning the full x range.

Parameters:

  • y_values (array-like, shape (N,)) – Y positions of each line in data coordinates.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • color (str, optional) – Line colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • hover_edgecolors (str, optional) – Colour override applied on mouse-hover.

  • labels (list of str, optional) – Per-line tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_vlines(x_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add static vertical lines spanning the full y range.

Parameters:

  • x_values (array-like, shape (N,)) – X positions of each line in data coordinates.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • color (str, optional) – Line colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • hover_edgecolors (str, optional) – Colour override applied on mouse-hover.

  • labels (list of str, optional) – Per-line tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_arrows(offsets, U, V, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add arrow markers at explicit (x, y) positions.

Parameters:

  • offsets (array-like, shape (N, 2)) – Arrow tail positions as [[x0, y0], …] in data coordinates.

  • U (array-like, shape (N,)) – X and Y components of each arrow vector (in data units).

  • V (array-like, shape (N,)) – X and Y components of each arrow vector (in data units).

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • edgecolors (str, optional) – Arrow colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • hover_edgecolors (str, optional) – Colour override applied on mouse-hover.

  • labels (list of str, optional) – Per-arrow tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_ellipses(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add ellipse markers at explicit (x, y) positions.

Parameters:

  • offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.

  • widths (float or array-like) – Full width and height of each ellipse in canvas pixels.

  • heights (float or array-like) – Full width and height of each ellipse in canvas pixels.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • edgecolors (str, optional) – Stroke colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-marker tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_lines(segments, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add line-segment markers (static, not draggable).

Parameters:

  • segments (array-like, shape (N, 2, 2)) – Each segment is [[x0, y0], [x1, y1]] in data coordinates.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • edgecolors (str, optional) – Line colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • hover_edgecolors (str, optional) – Colour override applied on mouse-hover.

  • labels (list of str, optional) – Per-segment tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_rectangles(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add rectangle markers at explicit (x, y) positions.

Parameters:

  • offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.

  • widths (float or array-like) – Full width and height of each rectangle in canvas pixels.

  • heights (float or array-like) – Full width and height of each rectangle in canvas pixels.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • edgecolors (str, optional) – Stroke colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-marker tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_squares(offsets, widths, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add square markers at explicit (x, y) positions.

Parameters:

  • offsets (array-like, shape (N, 2)) – Centre positions in data coordinates.

  • widths (float or array-like) – Side length of each square in canvas pixels.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • angles (float or array-like, optional) – Rotation angle(s) in degrees. Default 0.

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • edgecolors (str, optional) – Stroke colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-marker tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_polygons(vertices_list, name=None, *, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add polygon markers defined by explicit vertex lists.

Parameters:

  • vertices_list (list of array-like, each shape (K, 2)) – One polygon per element; each is a list of [x, y] vertices in data coordinates.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • facecolors (str or None, optional) – Fill colour. None = no fill.

  • edgecolors (str, optional) – Stroke colour. Default "#ff0000".

  • linewidths (float, optional) – Stroke width in pixels. Default 1.5.

  • alpha (float, optional) – Fill opacity (0–1). Default 0.3.

  • hover_edgecolors (str, optional) – Colour overrides applied on mouse-hover.

  • hover_facecolors (str, optional) – Colour overrides applied on mouse-hover.

  • labels (list of str, optional) – Per-polygon tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

add_texts(offsets, texts, name=None, *, color='#ff0000', fontsize=12, hover_edgecolors=None, labels=None, label=None)[source]

Add text annotations at explicit (x, y) positions.

Parameters:

  • offsets (array-like, shape (N, 2)) – Anchor positions in data coordinates.

  • texts (list of str) – One string per position.

  • name (str, optional) – Registry key. Auto-generated if omitted.

  • color (str, optional) – Text colour. Default "#ff0000".

  • fontsize (int, optional) – Font size in pixels. Default 12.

  • hover_edgecolors (str, optional) – Colour override applied on mouse-hover.

  • labels (list of str, optional) – Per-annotation tooltip labels.

  • label (str, optional) – Collection-level tooltip label.

Return type:

MarkerGroup

remove_marker(marker_type, name)[source]

Remove a named marker collection by type and name.

Parameters:

  • marker_type (str) – Collection type, e.g. "points", "vlines".

  • name (str) – The name used when the collection was created.

Return type:

None

clear_markers()[source]

Remove all marker collections from this panel.

Return type:

None

list_markers()[source]

Return a summary list of all marker collections on this panel.

Returns:

Each dict has keys "type", "name", and "n" (number of markers in the collection).

Return type:

list of dict

Parameters:
class anyplotlib.figure_plots.Plot2D(data, x_axis=None, y_axis=None, units='px', cmap=None, vmin=None, vmax=None, origin='upper')[source]

Bases: object

2-D image plot panel.

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

The marker API follows matplotlib conventions:

plot.add_circles(offsets, name=”g1”, facecolors=”#f00”, radius=5) plot.markers[“circles”][“g1”].set(radius=8)

Parameters:

  • data (np.ndarray)

  • units (str)

  • cmap (str | None)

  • vmin (float | None)

  • vmax (float | None)

  • origin (str)

to_state_dict()[source]

Return a JSON-serialisable copy of the current state.

Return type:

dict

property data: ndarray

The image data in the original user coordinate system (read-only).

Returns a float64 copy with writeable=False. To replace the data call set_data().

set_data(data, x_axis=None, y_axis=None, units=None)[source]

Replace the image data.

The origin supplied at construction is automatically re-applied so the new data is displayed with the same orientation.

Parameters:
Return type:

None

set_overlay_mask(mask, color='#ff4444', alpha=0.4)[source]

Set (or clear) a transparent boolean mask drawn over the image.

The mask is composited client-side in the browser at alpha opacity using color for all True pixels. Call with mask=None to remove any existing overlay.

Parameters:

  • mask (ndarray of shape (H, W), bool or uint8, or None) – Boolean array aligned to the image data. True / non-zero pixels are filled with color at transparency alpha. Pass None to clear the overlay.

  • color (str, optional) – CSS hex colour for the overlay, e.g. "#ff4444". Default red. Must be in #RRGGBB format.

  • alpha (float, optional) – Opacity in [0, 1]. Default 0.4 (40 % opaque).

Return type:

None

set_colormap(name)[source]
Parameters:

name (str)

Return type:

None

set_clim(vmin=None, vmax=None)[source]
Return type:

None

set_scale_mode(mode)[source]
Parameters:

mode (str)

Return type:

None

property colormap_name: str
add_widget(kind, color='#00e5ff', **kwargs)[source]
Parameters:
Return type:

Widget

get_widget(wid)[source]

Return the Widget object by ID string or Widget instance.

Return type:

Widget

remove_widget(wid)[source]

Remove a widget by ID string or Widget instance.

Return type:

None

list_widgets()[source]
Return type:

list

clear_widgets()[source]
Return type:

None

on_changed(fn)[source]

Decorator: fires on every pan/zoom/drag frame on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_release(fn)[source]

Decorator: fires once when pan/zoom/drag settles on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_click(fn)[source]

Decorator: fires on click on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_key(key_or_fn=None)[source]

Register a key-press handler for this panel.

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, phys_x, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:

Callable

disconnect(cid)[source]

Remove the callback registered under integer cid.

Parameters:

cid (int)

Return type:

None

set_view(x0=None, x1=None, y0=None, y1=None)[source]

Set the viewport to a data-space rectangle.

Parameters:

  • x0 (float, optional) – Horizontal data-space range to show. If omitted the full x-extent is used for zoom calculation.

  • x1 (float, optional) – Horizontal data-space range to show. If omitted the full x-extent is used for zoom calculation.

  • y0 (float, optional) – Vertical data-space range to show. If omitted the full y-extent is used for zoom calculation.

  • y1 (float, optional) – Vertical data-space range to show. If omitted the full y-extent is used for zoom calculation.

  • center_x (Translates the requested rectangle into the zoom /)

  • renderer. (/ center_y state values used by the 2-D JS)

Return type:

None

reset_view()[source]

Reset pan and zoom to show the full image.

Return type:

None

add_circles(offsets, name=None, *, radius=5, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add circle markers at (x, y) positions in data coordinates.

Return type:

MarkerGroup

add_points(offsets, name=None, *, sizes=5, color='#ff0000', facecolors=None, linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]

Add point markers at (x, y) positions in data coordinates.

Return type:

MarkerGroup

add_hlines(y_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add static horizontal lines at the given y positions.

Return type:

MarkerGroup

add_vlines(x_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]

Add static vertical lines at the given x positions.

Return type:

MarkerGroup

add_arrows(offsets, U, V, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_ellipses(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_lines(segments, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_rectangles(offsets, widths, heights, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_squares(offsets, widths, name=None, *, angles=0, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_polygons(vertices_list, name=None, *, facecolors=None, edgecolors='#ff0000', linewidths=1.5, alpha=0.3, hover_edgecolors=None, hover_facecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

add_texts(offsets, texts, name=None, *, color='#ff0000', fontsize=12, hover_edgecolors=None, labels=None, label=None)[source]
Return type:

MarkerGroup

remove_marker(marker_type, name)[source]

Remove a named marker collection by type and name.

Parameters:

  • marker_type (str) – Collection type, e.g. "points", "vlines".

  • name (str) – The name used when the collection was created.

Return type:

None

clear_markers()[source]

Remove all marker collections from this panel.

Return type:

None

list_markers()[source]

Return a summary list of all marker collections on this panel.

Returns:

Each dict has keys "type", "name", and "n" (number of markers in the collection).

Return type:

list of dict

class anyplotlib.figure_plots.PlotMesh(data, x_edges=None, y_edges=None, units='')[source]

Bases: Plot2D

2-D mesh plot panel created by Axes.pcolormesh().

Accepts cell edge arrays (length N+1 / M+1) rather than centre arrays, matches matplotlib’s pcolormesh convention. Only 'circles' and 'lines' markers are supported.

Parameters:

  • data (np.ndarray)

  • units (str)

set_data(data, x_edges=None, y_edges=None, units=None)[source]

Replace the mesh data (and optionally the edge arrays).

Parameters:
Return type:

None

class anyplotlib.figure_plots.Plot3D(geom_type, x, y, z, *, colormap='viridis', color='#4fc3f7', point_size=4.0, linewidth=1.5, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0)[source]

Bases: object

3-D plot panel.

Supports three geometry types matching matplotlib’s 3-D Axes API:

  • 'surface' – triangulated surface, Z-coloured via colormap.

  • 'scatter' – point cloud, single colour.

  • 'line' – connected line through 3-D points.

Created by Axes.plot_surface(), Axes.scatter3d(), and Axes.plot3d().

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

Parameters:
to_state_dict()[source]
Return type:

dict

on_changed(fn)[source]

Decorator: fires on every rotation/zoom frame.

Parameters:

fn (Callable)

Return type:

Callable

on_release(fn)[source]

Decorator: fires once when rotation/zoom settles.

Parameters:

fn (Callable)

Return type:

Callable

on_click(fn)[source]

Decorator: fires on click on this panel.

Parameters:

fn (Callable)

Return type:

Callable

on_key(key_or_fn=None)[source]

Register a key-press handler for this panel.

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, and last_widget_id.

Note

Registered keys take priority over the built-in r (reset view) shortcut.

Return type:

Callable

disconnect(cid)[source]

Remove the callback registered under integer cid.

Parameters:

cid (int)

Return type:

None

set_colormap(name)[source]

Set the surface colormap (ignored for scatter/line).

Parameters:

name (str)

Return type:

None

set_view(azimuth=None, elevation=None)[source]

Set the camera azimuth (°) and/or elevation (°).

Parameters:
Return type:

None

set_zoom(zoom)[source]
Parameters:

zoom (float)

Return type:

None

set_data(x, y, z)[source]

Replace the geometry data.

Return type:

None

class anyplotlib.figure_plots.PlotBar(x, height=None, width=0.8, bottom=0.0, *, align='center', color='#4fc3f7', colors=None, orient='v', log_scale=False, group_labels=None, group_colors=None, show_values=False, units='', y_units='', x_labels=None, x_centers=None, bar_width=None, baseline=None, values=None)[source]

Bases: object

Bar-chart plot panel.

Not an anywidget. Holds state in _state dict; every mutation calls _push() which writes to the parent Figure’s panel trait.

Supports grouped bars (pass a 2-D height array with shape (N, G)), log-scale value axis, draggable overlay widgets, and hover/click callbacks.

Created by Axes.bar().

Parameters:
to_state_dict()[source]
Return type:

dict

set_data(height, x=None, x_labels=None, *, x_centers=None)[source]

Replace bar heights; recalculates the value-axis range automatically.

Parameters:

  • height (array-like, shape (N,) or (N, G)) – New bar heights. For grouped charts the group count G must match the original.

  • x (array-like of numeric, optional) – New bar positions (replaces the stored x_centers). Also accepts the legacy keyword alias x_centers.

  • x_labels (list of str, optional) – New category labels.

Return type:

None

set_color(color)[source]

Set a single colour for all bars.

Parameters:

color (str)

Return type:

None

set_colors(colors)[source]

Set per-bar colours (list of CSS colour strings, length N).

Return type:

None

set_show_values(show)[source]

Show or hide in-bar value annotations.

Parameters:

show (bool)

Return type:

None

set_log_scale(log_scale)[source]

Enable or disable a logarithmic value axis.

When log_scale is True any non-positive values are clamped to 1e-10 for display; the data-range bounds are recalculated in log-space automatically.

Parameters:

log_scale (bool)

Return type:

None

add_vline_widget(x, color='#00e5ff')[source]

Add a draggable vertical line at data position x.

Parameters:
Return type:

VLineWidget

add_hline_widget(y, color='#00e5ff')[source]

Add a draggable horizontal line at value-axis position y.

Parameters:
Return type:

HLineWidget

add_range_widget(x0, x1, color='#00e5ff', style='band', y=0.0, _push=True)[source]

Add a draggable range overlay. See Plot1D.add_range_widget() for full docs.

Parameters:
Return type:

RangeWidget

add_point_widget(x, y, color='#00e5ff', show_crosshair=True, _push=True)[source]

Add a freely-draggable control point to this panel.

Parameters:
Return type:

PointWidget

get_widget(wid)[source]

Return the Widget object by ID string or Widget instance.

Return type:

Widget

remove_widget(wid)[source]

Remove a widget by ID string or Widget instance.

Return type:

None

list_widgets()[source]
Return type:

list

clear_widgets()[source]
Return type:

None

on_click(fn)[source]

Decorator: fires when the user clicks a bar.

The Event has bar_index, value, x_center, and x_label.

Parameters:

fn (Callable)

Return type:

Callable

on_changed(fn)[source]

Decorator: fires on every drag frame (widget drag or hover).

Parameters:

fn (Callable)

Return type:

Callable

on_release(fn)[source]

Decorator: fires once when a widget drag settles.

Parameters:

fn (Callable)

Return type:

Callable

on_key(key_or_fn=None)[source]

Register a key-press handler for this panel.

Two call forms are supported:

@plot.on_key('q')          # fires only when 'q' is pressed
def handler(event): ...

@plot.on_key               # fires for every registered key
def handler(event): ...

The event carries: key, mouse_x, mouse_y, and last_widget_id.

Return type:

Callable

disconnect(cid)[source]
Parameters:

cid (int)

Return type:

None

class anyplotlib.figure_plots.GridSpec(nrows, ncols, *, width_ratios=None, height_ratios=None)[source]

Bases: object

Define a grid of subplot cells.

Parameters:

  • nrows (int) – Grid dimensions.

  • ncols (int) – Grid dimensions.

  • width_ratios (list of float, optional) – Relative column widths (length ncols). Defaults to equal widths.

  • height_ratios (list of float, optional) – Relative row heights (length nrows). Defaults to equal heights.

Examples

>>> gs = GridSpec(2, 3, width_ratios=[2, 1, 1])
>>> spec = gs[0, :]          # top row spanning all columns
>>> spec = gs[1, 1:3]        # bottom-right 2 columns
class anyplotlib.figure_plots.SubplotSpec(gs, row_start, row_stop, col_start, col_stop)[source]

Bases: object

Describes which grid cells a subplot occupies.

Parameters: