Axes, Plots & Layout#

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()`.
`Line1D`	Handle to a single line on a `Plot1D` panel.
`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.axes.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:

fig (Figure)
spec (SubplotSpec)

imshow(data, axes=None, units='px', cmap=None, vmin=None, vmax=None, origin='upper', gpu='auto', tile='auto', integration_method='mean', overview_method='mean', tile_backend=None)[source]

Attach a 2-D image to this axes cell.

Parameters:

data (np.ndarray, shape (H, W) or (H, W, 3|4)) – Image data. 2-D arrays are colormapped. (H, W, 3) / (H, W, 4) arrays render as true-colour RGB(A): uint8 values are used directly; floats are interpreted as 0–1 (or 0–255 when the max exceeds 1). cmap/vmin/vmax and the colorbar do not apply to RGB images.
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.
gpu (str | bool)
tile (str | bool)
integration_method (str)
overview_method (str)

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, bounds=None, texture=None, gpu='auto')[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.)
bounds (((xmin, xmax), (ymin, ymax), (zmin, zmax)), optional) – Fix the axes bounds instead of fitting them to the data. Pass ((-1, 1),) * 3 for a unit sphere so it projects as a true circle rather than being stretched to fill the panel.
texture (array-like, bytes, or path, optional) – Image to wrap around the surface — shorthand for set_texture(), which takes the mapping, shading, and culling options.
gpu ("auto" | bool, optional) – WebGPU acceleration policy for a textured surface (a colormapped one always renders on Canvas2D). "auto" (default) uses the GPU when available above ~2k triangles; True always attempts it; False forces Canvas2D. Falls back silently when WebGPU is unavailable — check Plot3D.gpu_active.

Return type:

Plot3D

scatter3d(x, y, z, *, color='#4fc3f7', colors=None, point_size=4.0, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0, bounds=None, gpu='auto')[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.)
colors (list of "#rrggbb" or (N, 3) array, optional) – Per-point colours (overrides color). Floats are 0–1.
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.)
bounds (((xmin, xmax), (ymin, ymax), (zmin, zmax)), optional) – Fix the axes bounds instead of fitting them to the data — keeps the origin and scale stable, e.g. ((-1, 1),) * 3 for unit vectors on a sphere.
gpu ("auto" | bool, optional) – WebGPU acceleration policy. "auto" (default) renders on the GPU when available and the cloud exceeds ~20k points, else Canvas2D; True always attempts GPU; False forces Canvas2D. Falls back silently when WebGPU is unavailable — check Plot3D.gpu_active for the actual path.

Return type:

Plot3D

voxels(x, y, z, *, colors=None, color='#4fc3f7', size=1.0, alpha=0.3, x_label='x', y_label='y', z_label='z', azimuth=-60.0, elevation=30.0, zoom=1.0, bounds=None, gpu='auto')[source]

Attach a 3-D voxel plot: shaded translucent cubes at the centres.

Designed for volumetric grain/label maps. Add draggable PlaneWidget slice selectors with plot.add_widget("plane", axis=..., position=...) — voxels lying on a plane render at voxel_slice_alpha (more opaque) so the selected slice pops out of the translucent volume.

Large volumes With WebGPU (gpu="auto", the default, active above ~1k cubes when a GPU is present) hundreds of thousands of voxels render interactively via instancing. On the Canvas2D fallback the budget is ~20k cubes (~3–6 µs each); a warning is emitted above that only when gpu=False. For volumes too large even for the GPU (e.g. a 512 × 512 × 300 tomogram = 78M voxels), downsample with stride slicing (vol[::s, ::s, ::s]) or draw only grain-boundary voxels, and pair the 3-D overview with linked full-resolution 2-D slice panels — the voxel grain explorer example demonstrates this pattern.

Parameters:

x (array-like, shape (N,)) – Voxel centre coordinates.
y (array-like, shape (N,)) – Voxel centre coordinates.
z (array-like, shape (N,)) – Voxel centre coordinates.
colors (list of "#rrggbb" or (N, 3) array, optional) – Per-voxel colours (overrides color). Floats are 0–1.
color (str, optional Single CSS colour when colors is omitted.)
size (float, optional Cube edge length in data units. Default 1.)
alpha (float, optional) – Base voxel opacity (0–1). Default 0.3. See also Plot3D.set_voxel_alpha().
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.)
bounds (((xmin, xmax), (ymin, ymax), (zmin, zmax)), optional) – Fix the axes bounds instead of fitting them to the data.
gpu ("auto" | bool, optional) – WebGPU acceleration policy. "auto" (default) renders cubes on the GPU when available and the set exceeds ~1k; True always attempts GPU; False forces Canvas2D. Falls back silently when WebGPU is unavailable — see Plot3D.gpu_active.

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='', yscale='linear')[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" ("-."), or "none" to draw no connecting line at all — pair it with marker for a scatter. 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).
yscale (str)

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 apl

x = np.linspace(0, 4 * np.pi, 512)
fig, ax = apl.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")

semilogy(data, axes=None, **kwargs)[source]

Attach a 1-D line with a logarithmic y-axis.

Parameters:

data (ndarray)
axes (list | None)

Return type:

Plot1D

axes2d(*, xlim=(0.0, 1.0), ylim=(0.0, 1.0), aspect=None, units='', y_units='')[source]

Attach a blank data-coordinate 2-D axis (PlotXY).

Unlike plot() (a curve over a monotonic x-axis), this is a coordinate canvas: set xlim / ylim (+ optional aspect="equal") and draw scatter() / plot / fill / text as collection-style artists in data coordinates — matplotlib’s transData + PathCollection model. Suits stereographic / IPF / pole-figure style plots.

Examples

>>> import anyplotlib as apl
>>> fig, ax = apl.subplots()
>>> xy = ax.axes2d(xlim=(-1, 1), ylim=(-1, 1), aspect="equal")
>>> xy.fill([0, 1, 0.5], [0, 0, 0.9], facecolor="#eee")   # triangle
>>> xy.scatter([0.3], [0.3], c="#f00", s=10)
>>> xy.text(0.5, 0.95, r"$[111]$")

Parameters:

units (str)
y_units (str)

Return type:

PlotXY

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.axes.InsetAxes(fig, w_frac, h_frac, *, corner='top-right', anchor=None, 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". Mutually exclusive with anchor — pass exactly one.
anchor ((x_frac, y_frac), optional) – Position of the inset’s TOP-LEFT corner as fractions of the figure size (0–1), measured from the figure’s top-left. When given, the inset floats freely at that anchor instead of snapping to a corner (corner is then ignored / None). Minimize / maximize / restore all still work: a minimized anchored inset collapses to its title bar in place, a maximized one floats centred, and restore returns it to the anchor.
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])
>>> # arbitrary placement:
>>> free = fig.add_inset(0.3, 0.25, anchor=(0.55, 0.1), title="Callout")
>>> free.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

set_geometry(*, anchor=None, w_frac=None, h_frac=None)[source]

Move and/or resize the inset in figure-fraction coordinates.

This is the Python-side counterpart to the interactive drag / resize of an inset in the renderer’s edit mode: the inset_geometry_change event dispatches here so the authoritative Python state converges with what the user did on screen. It is also callable directly to place or size an inset programmatically.

Passing anchor switches the inset to free (anchor) placement and drops any corner snapping (corner becomes None), mirroring the renderer’s corner-to-anchor conversion on drag start.

Parameters:

anchor ((x_frac, y_frac), optional) – New position of the inset’s TOP-LEFT corner as fractions of the figure size (0–1), measured from the figure’s top-left. Each component is clamped into [0, 1]. When given, corner is set to None (free placement). When omitted, the current placement (corner or existing anchor) is left unchanged.
w_frac (float, optional) – New width / height as fractions of the figure size. Each is clamped into (0, 1] (must be positive, at most the full figure). When omitted, the corresponding dimension is unchanged.
h_frac (float, optional) – New width / height as fractions of the figure size. Each is clamped into (0, 1] (must be positive, at most the full figure). When omitted, the corresponding dimension is unchanged.

Returns:

self, for chaining.

Return type:

InsetAxes

Raises:

ValueError – If anchor is not a pair of finite numbers, or w_frac / h_frac is not a finite number.

indicate_region(parent_plot, region, *, color='#ff9800', linestyle='dashed', linewidth=1.5)[source]

Draw a callout tying this inset to a region of parent_plot.

Renders — on the parent panel’s overlay — a rectangle around region (in the parent image’s DATA coordinates) plus two leader lines joining the rectangle’s corners that face the inset to the inset’s nearest corners, the classic matplotlib mark_inset look. The rectangle tracks the parent’s zoom / pan and the leaders follow the inset as it moves or minimizes (leaders hide while the inset is minimized).

Calling indicate_region again REPLACES any previous indication for this inset. Remove it with clear_indication().

Parameters:

parent_plot (Plot2D) – The parent image plot the region lives on. Must be a 2-D image panel in the SAME figure as this inset (typically the panel the inset overlays) — a plot registered on a different Figure raises ValueError.
region (tuple of float) – The source rectangle in the parent image’s data coordinates, as (x, y, w, h): top-left (x, y) plus width and height. The values follow the same convention as the parent’s axes (pixel indices for an uncalibrated image; physical units when the axes are calibrated). All four must be finite; w and h must be strictly positive. The rectangle MAY extend outside the parent’s data bounds (e.g. a region near an edge) — that is allowed by design and simply clips visually; only degenerate/non-finite values are rejected.
color (str, optional) – Stroke colour of both the rectangle and the leader lines. Default warm orange "#ff9800".
linestyle (str, optional) – "dashed" (default), "solid", or "dotted".
linewidth (float, optional) – Stroke width in CSS px. Default 1.5.

Returns:

self, for chaining.

Return type:

InsetAxes

Raises:

ValueError – If parent_plot has no panel id, is not registered on this inset’s Figure, or region is not 4 finite numbers with w > 0 and h > 0.

indicate_point(parent_plot, point, *, color='#ff9800', linestyle='dashed', linewidth=1.5, marker_size=5.0)[source]

Draw a callout tying this inset to a single POINT of parent_plot.

The point sibling of indicate_region(): renders a small circular marker (with a centre cross) at point — in the parent image’s DATA coordinates — plus ONE leader line joining the marker to the inset’s nearest corner. The marker tracks the parent’s zoom / pan and the leader follows the inset as it moves (the leader hides while the inset is minimized), exactly like the region callout.

Calling indicate_point (or indicate_region) again REPLACES any previous indication for this inset — an inset carries at most one. Remove it with clear_indication().

Parameters:

parent_plot (Plot2D) – The parent image plot the point lives on. Must be a 2-D image panel registered on the SAME figure as this inset.
point (tuple of float) – The source point in the parent image’s data coordinates, as (x, y) — same convention as indicate_region()’s region origin. Both values must be finite; a point outside the parent’s data bounds is allowed (it simply clips visually).
color (str, optional) – Stroke colour of the marker and the leader line. Default warm orange "#ff9800".
linestyle (str, optional) – Leader style — "dashed" (default), "solid", or "dotted". The marker itself is always drawn solid.
linewidth (float, optional) – Stroke width in CSS px. Default 1.5.
marker_size (float, optional) – Marker circle radius in CSS px. Default 5.0. Must be > 0.

Returns:

self, for chaining.

Return type:

InsetAxes

Raises:

ValueError – If parent_plot has no panel id, is not registered on this inset’s Figure, point is not 2 finite numbers, or marker_size is not > 0.

clear_indication()[source]

Remove any region/point indication attached to this inset (idempotent).

Return type:: None

property indication: dict | None: The current indication spec (dict with either a region or a point key) or None.

class anyplotlib.plot1d.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='', yscale='linear')[source]

Bases: _BasePlot, _PanelMixin, _MarkerMixin

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, as is `"none"` (markers only, no connecting line).
`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='#4fc3f7', linewidth=1.5, linestyle='solid', ls=None, alpha=1.0, marker='none', markersize=4.0, label='', axis='left')[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 "#4fc3f7".
linewidth (float, optional) – Stroke width in pixels. Default 1.5.
linestyle (str, optional) – Dash pattern: "solid", "dashed", "dotted", "dashdot" (or shorthands), or "none" for markers only with no connecting line. 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).
axis (str)

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', linewidth=2, snap_values=None)[source]

Add a draggable vertical-line overlay.

Parameters:

x (float) – Initial x position in data coordinates.
color (str, optional) – CSS colour string. Default "#00e5ff".
linewidth (float, optional) – Line stroke width in px. Default 2.

Returns:

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

Return type:

VLineWidget

add_hline_widget(y, color='#00e5ff', linewidth=2, snap_values=None)[source]

Add a draggable horizontal-line overlay.

Parameters:

y (float) – Initial y position in data coordinates.
color (str, optional) – CSS colour string. Default "#00e5ff".
linewidth (float, optional) – Line stroke width in px. Default 2.

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, linewidth=2, max_extent=None, orientation='horizontal', snap_values=None, _push=True)[source]

Add a draggable range overlay to this panel.

Parameters:

x0 (float) – The two edges of the range, in data coordinates along the selection axis: x positions when horizontal (default), y values when orientation="vertical".
x1 (float) – The two edges of the range, in data coordinates along the selection axis: x positions when horizontal (default), y values when orientation="vertical".
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.
linewidth (float, optional) – Line stroke width in px. Default 2.
max_extent (float, optional) – Maximum span width in data units. The span physically stops growing at this width while dragging (the dragged edge pins, the opposite edge stays put). None (default) leaves it unbounded.
orientation ({'horizontal', 'vertical'}, optional) – Which axis the range selects along. "vertical" draws a band spanning the plot width that selects a range of values — an intensity window rather than a spectral one. Default "horizontal".
snap_values (sequence of float, optional) – Allowed edge positions. Each edge follows the cursor while dragging but lands only on the nearest of these values (matplotlib’s SpanSelector.snap_values). None (default) drags continuously.
_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, linewidth=2, _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.
linewidth (float, optional) – Guide-line stroke width in px. Default 2.
_push (bool, optional) – Push state to JS immediately. Set to False when adding several widgets at once; call _push() manually afterward.

Return type:

PointWidget

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_legend_fontsize(size)[source]

Set the legend text font size.

Parameters:: size (float) – Legend font size in CSS pixels. Must be a positive number.
Raises:: ValueError – If size is not a positive, finite number.
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" (":"), "dashdot" ("-."), or "none" to suppress the connecting line and draw only the markers.
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

property color: str

property x: ndarray

property y: ndarray

set_xlabel(label, fontsize=None)[source]

Set the x-axis label.

Parameters:

label (str) – Label text. Supports the mini-TeX subset for scientific notation, e.g. r"Energy ($10^{-3}$ eV)" or r"$\Delta t$ (s)" — see _BasePlot notes.
fontsize (float, optional) – Font size in CSS pixels. Default 9. None keeps the current size.

Return type:

None

set_ylabel(label, fontsize=None)[source]

Set the y-axis label. Same semantics as set_xlabel().

Parameters:

label (str)
fontsize (float | None)

Return type:

None

set_yscale(scale)[source]

Set the y-axis scale: 'linear' or 'log'.

Parameters:: scale (str)
Return type:: None

set_xlim(xmin, xmax)[source]

Parameters:

xmin (float)
xmax (float)

Return type:

None

set_ylim(ymin, ymax)[source]

Parameters:

ymin (float)
ymax (float)

Return type:

None

get_ylim()[source]

Return type:: tuple

add_right_axis(color='#000000')[source]

Enable a secondary y-axis on the right-hand side of the panel.

Lines added with add_line(..., axis="right") are scaled against and labelled by this axis, independently of the left y-axis. Calling this more than once just updates the axis colour.

Parameters:: color (str, optional) – Tick and label colour for the right axis. Default "#000000".
Return type:: None

remove_right_axis()[source]

Remove the secondary y-axis and any lines anchored to it.

This is a full teardown: a pinned range (set_right_ylim()), the label, and the axis colour all reset to their defaults, mirroring matplotlib where a removed twin axis is gone entirely. A subsequent add_right_axis() therefore starts fresh (auto-scaled, no label).

Return type:: None

set_right_ylabel(label)[source]

Set the label (units) shown on the secondary y-axis.

Parameters:: label (str)
Return type:: None

set_right_ylim(ymin, ymax)[source]

Pin the secondary y-axis range explicitly (overrides auto-scaling).

Parameters:

ymin (float)
ymax (float)

Return type:

None

get_right_ylim()[source]

Return type:: tuple

get_xlim()[source]

Return type:: tuple

get_xbound()[source]

Return type:: tuple

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, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

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, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_hlines(y_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_vlines(x_values, name=None, *, color='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_arrows(offsets, U, V, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

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, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_lines(segments, name=None, *, edgecolors='#ff0000', linewidths=1.5, hover_edgecolors=None, labels=None, label=None, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

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, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

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, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

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, clip_path=None, transform='data', clip_display=True)[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.
clip_path (array-like, shape (K, 2), optional) – Data-coordinate polygon the group is clipped to (matplotlib set_clip_path) — e.g. a curved sector boundary so a mesh’s edge cells don’t overflow it. None = no clip.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_raster(rgba, *, extent, name=None, clip_path=None, smooth=False, transform='data', clip_display=True)[source]

Add an RGBA image drawn between data-coordinate extent corners.

A single-drawImage raster — the fast path for a dense regular grid (e.g. an orientation-density heatmap) that would otherwise be thousands of individual polygons. The image bytes travel on the deduped geometry channel, so re-aiming the view never re-transmits them.

Parameters:

rgba (array-like, shape (H, W, 3|4)) – Image data. Coerced to uint8 RGBA via the usual rules (floats in 0–1 scaled ×255, missing alpha → 255). Alpha 0 = transparent cell.
extent ((x0, x1, y0, y1)) – Data-coordinate bounding box the image is stretched across.
name (str, optional) – Registry key. Auto-generated if omitted.
clip_path (array-like, shape (K, 2), optional) – Data-coordinate polygon the image is clipped to (matplotlib set_clip_path) — e.g. a curved fundamental-sector boundary. None = no clip.
smooth (bool, optional) – If True, the image is bilinearly interpolated when stretched (a smooth heat field). Default False keeps crisp nearest-neighbour cells (matplotlib interpolation="nearest").
transform (str)
clip_display (bool)

Return type:

MarkerGroup

add_texts(offsets, texts, name=None, *, color='#ff0000', fontsize=12, hover_edgecolors=None, labels=None, label=None, transform='data', clip_display=True)[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.
transform (str)
clip_display (bool)

Return type:

MarkerGroup

Parameters:

data (np.ndarray)
units (str)
y_units (str)
color (str)
linewidth (float)
linestyle (str)
alpha (float)
marker (str)
markersize (float)
label (str)
yscale (str)

class anyplotlib.plot1d.Line1D(plot, lid)[source]

Bases: object

Handle to a single line on a Plot1D panel.

Returned by Plot1D.add_line(). Use it to update the line data, register event handlers scoped to just that line, or to remove it later.

Parameters:

plot (Plot1D)
lid (str | None)

id

None for the primary line; an 8-character UUID string for overlay lines added with Plot1D.add_line().

Type:: str | None

property id: str | None

add_event_handler(fn_or_type, *args, **kwargs)[source]

Register a handler scoped to this line only.

Wraps the plot-level pointer_move / pointer_down handler with a line_id filter. Only pointer_move and pointer_down are meaningful on a line handle.

remove_handler(cid_or_fn, *types)[source]: Remove a handler registered via this line handle.

set_data(y, x_axis=None)[source]

Update the y-data (and optionally x-axis) of this overlay line.

The y-axis range is recomputed and the panel re-renders immediately.

Parameters:

y (array-like, shape (N,)) – New y values. Must be 1-D.
x_axis (array-like, shape (N,), optional) – New x coordinates. If omitted the existing x-axis is kept.

Raises:

ValueError – If called on the primary line (use Plot1D.set_data() instead), or if y is not 1-D.
KeyError – If this line has already been removed.

Return type:

None

remove()[source]

Remove this overlay line from its parent plot.

Return type:: None

property x: The x-axis array for this overlay line.

property data: The y-data array for this overlay line.

property color: str

property linewidth: float

property linestyle: str

property alpha: float

class anyplotlib.plot2d.Plot2D(data, x_axis=None, y_axis=None, units='px', cmap=None, vmin=None, vmax=None, origin='upper', gpu='auto', tile='auto', integration_method='mean', overview_method='mean', tile_backend=None)[source]

Bases: _BasePlot, _PanelMixin, _MarkerMixin

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:

units (str)
cmap (str | None)
vmin (float | None)
vmax (float | None)
origin (str)
gpu (str | bool)
tile (str | bool)
integration_method (str)
overview_method (str)

TILE_THRESHOLD = 1024

OVERVIEW_MAX = 1024

VIEW_OVERFETCH = 2.0

VIEW_ZOOM_MIN = 1.05

RANGE_SAMPLE_MAX = 2048

property gpu_active: bool: True when this image is being rendered by the WebGPU path (reported by JS after the device resolves and the panel flips to GPU). False on the Canvas2D path (small image, gpu=False, no GPU, or a GPU failure/fallback).

enable_tile(backend=None, integration_method='mean', overview_method=None)[source]

Turn tile mode ON (or reconfigure it) AFTER construction — for a consumer whose large frame isn’t known at imshow time (e.g. a live navigator whose signal frame arrives later and changes). Registers the internal view→tile loop (once), sets the logical size from the backend, and paints the overview base. Call update_tile_source(new_frame) on each subsequent data change.

backend: a TileBackend (or an ndarray, wrapped). None keeps the current backend (just re-enable / change method).

overview_method: sampling method for the base overview texture ("mean"|"subsample"|"max"). None keeps the current setting (default "mean" from construction). Use "subsample" to restore the old fast nearest-neighbour path when a full-frame area-mean is too expensive.

Parameters:

integration_method (str)
overview_method (str | None)

Return type:

None

update_tile_source(array=None)[source]

The backing DATA changed (e.g. a movie navigator advanced a frame) — keep the current zoom/subselection but refresh the pixels. Re-samples the overview base AND (if a detail tile is currently shown) the SAME detail region from the new data, so a live source updates in place without a view change.

array: swap the numpy backend’s source first (convenience for the common ndarray case). For a custom backend that already mutated its own source, call update_tile_source() with no argument to just re-sample.

Return type:: None

to_state_dict()[source]

Return a JSON-serialisable copy of the current state.

On the binary-transport path _state["image_b64"] may hold a tiny "\x00bin:<checksum>" change-token instead of a base64 string — the real pixels ride the PLOTBIN channel (_electron._route_change reads them from the Figure’s _raw_pixels side-table). The token is the correct WIRE representation and is passed through untouched here so the hot Figure._push path does NOT re-encode base64 every frame.

A COLD consumer with no binary channel (save_html / standalone / Jupyter) must instead materialise real base64; it calls resolve_pixel_tokens() on the returned dict (Figure._push does this for the standalone trait when binary transport is off).

Return type:: dict

resolve_pixel_tokens(d)[source]

Replace any "\x00bin:…" pixel change-token in d with the real base64 (materialised from the Figure’s _raw_pixels side-table), in place, and return d. Used by the COLD paths (save_html / standalone) that have no PLOTBIN channel and need the pixels inline. A no-op for a normal base64 string. See to_state_dict().

Also materialises every LAYER’s pixels: each layer has a top-level geom key layer_<id>_b64 AND a mirror image_b64 field inside its layers entry — both are resolved so a save_html snapshot of a layered plot is self-contained.

Parameters:: d (dict)
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().

The float64 cast happens HERE, lazily, not in set_data — a scrub pushes a new frame every tick but rarely reads .data back, and a full float64 copy of a 4k frame is ~12 ms. set_data keeps the frame in its source dtype (self._data); we cast + copy only on the (rare) read.

set_data(data, x_axis=None, y_axis=None, units=None, clim=None, tile=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.

tile — per-call override of the tile decision (default None uses the plot’s construction preference). False forces a PLAIN full-frame push even for a large frame (the caller manages its own decimation); True forces tile mode. A live consumer that only wants tiling on some frames (e.g. only when its GPU is active, sending the NATIVE frame then, but a pre-decimated frame otherwise) passes tile=False on the decimated frames so they don’t get auto-tiled at the wrong logical size.

clim — optional (vmin, vmax) display range applied in the SAME push as the new data. Without it the caller must follow with a separate set_clim, which pushes a SECOND time: the first push shows the image stretched over its full data range (wrong contrast) and the second corrects it, producing a one-frame flash on every update. Passing clim here makes data + contrast a single atomic frame (no flash).

Raises:

ValueError – If data has an invalid shape/ndim, or if this plot has image layers (add_layer()) and data’s (H, W) differs from the current image shape. A layer keeps the size it had when it was added/last updated, so a shape-changing base update would silently stretch stale-sized layer pixels over the new image. Remove all layers (remove_layer) before changing the base image’s shape, then re-add them at the new size.

Parameters:

data (ndarray)
units (str | None)
clim (tuple | None)
tile (str | bool | None)

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

property layers: list: The list of Layer handles, in z-order (index 0 drawn first, above the base image).

add_layer(data, *, cmap='magma', alpha=0.5, clim=None, visible=True, tint=None)[source]

Add an image LAYER drawn over the base image.

Each layer has its OWN colormap, display range (clim), and opacity (alpha), and is composited on top of the base image (and previously added layers) with the SAME zoom/pan transform, so it tracks the base exactly. This is the multi-image overlay primitive; for a single-colour boolean mask use set_overlay_mask() instead.

Parameters:

data (ndarray, shape (H, W)) – 2-D scalar array, the same size as the base image. Normalised to uint8 via clim → LUT exactly like the base image. A shape mismatch raises ValueError.
cmap (str, optional) – Colormap name (default "magma"). Ignored for display while tint is set (the tint LUT replaces the colormap), but kept so set(cmap=...) can revert to it.
alpha (float, optional) – Opacity in [0, 1] (default 0.5).
clim ((vmin, vmax) or None, optional) – Display range; None (default) auto-scales to the data min/max.
visible (bool, optional) – Whether the layer is drawn (default True).
tint (str or None, optional) – A #rgb / #rrggbb hex colour. When set, the layer renders as a clear→colour intensity ramp instead of a named colormap: RGB is tint at every intensity and per-texel alpha ramps linearly 0 → 255 (transparent at low intensity → opaque tint at high). The per-texel alpha multiplies with the layer’s alpha. None (default) keeps the named-colormap behaviour. An invalid colour raises ValueError.

Returns:

A handle with .set(...) / .set_data(frame) / .remove().

Return type:

Layer

Raises:

RuntimeError – If the plot is in TILE mode — layers are incompatible with tiling (a layer would have to be tiled independently against the same view). Load the plot with tile=False to use layers.
ValueError – If data is not 2-D or does not match the base image size.

remove_layer(layer)[source]

Remove layer (a Layer handle or its id string).

Return type:: None

set_colormap(name)[source]

Parameters:: name (str)
Return type:: None

set_clim(vmin=None, vmax=None)[source]

Set the display range. Because scalar frames are quantised to uint8 over their clim (so a hot pixel / zero beam can’t crush the signal — see _normalize_image), a new range is honoured by RE-QUANTISING from the cached 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.

Return type:: None

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

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 passed to set_data — already origin-applied), so a zoom-in shows true native pixels for the visible region WITHOUT transferring the whole full-res frame. The shader samples this tile instead of the base whenever the current zoom window lies inside [x0:x1, y0:y1]; otherwise it falls back to the base texture. set_detail(None) clears it (revert to base).

tile is quantised to uint8 over the SAME display range as the base (display_min/display_max) so its contrast matches seamlessly — a zoom crop must look identical to the base, just sharper. Only meaningful for scalar (non-RGB) images.

Return type:: None

set_scale_mode(mode)[source]

Parameters:: mode (str)
Return type:: None

property colormap_name: str

set_xlabel(label, fontsize=None)[source]

Set the x-axis label.

Parameters:

label (str) – Label text. Supports the mini-TeX subset for scientific notation, e.g. r"$q$ ($\AA^{-1}$)" or r"$10^{-3}$ m" — see _BasePlot notes.
fontsize (float, optional) – Font size in CSS pixels. Default 11. None keeps the current size.

Return type:

None

set_ylabel(label, fontsize=None)[source]

Set the y-axis label. Same semantics as set_xlabel().

Parameters:

label (str)
fontsize (float | None)

Return type:

None

set_xlim(xmin, xmax)[source]

Parameters:

xmin (float)
xmax (float)

Return type:

None

set_ylim(ymin, ymax)[source]

Parameters:

ymin (float)
ymax (float)

Return type:

None

get_xlim()[source]

Return type:: tuple

get_ylim()[source]

Return type:: tuple

get_xbound()[source]

Return type:: tuple

set_extent(x_axis, y_axis, units=None)[source]

Recalibrate the image axes to the given coordinate arrays.

Sets has_axes so the front-end draws physical tick gutters + the scale bar — the same gate set_data(x_axis=, y_axis=) sets. Without this a tiled image (which is calibrated ONLY through set_extent / enable_tile, never through set_data with axis args) would show no ticks and no scale bar (the has_axes gate stayed False). Pass units to update the scale-bar unit label in the same push.

Parameters:: units (str | None)
Return type:: None

set_colorbar_label(label, fontsize=None)[source]

Set the colorbar label (mini-TeX allowed; default size 10 px).

Parameters:

label (str)
fontsize (float | None)

Return type:

None

set_colorbar_visible(visible)[source]

Parameters:: visible (bool)
Return type:: None

set_colorbar_pad(pad)[source]

Set the gap in px between the image and the colorbar strip.

Parameters:: pad (float or None) – Gap in CSS pixels. None restores the default (6 px). The gap comes out of the image width, so widening it shrinks the image rather than pushing the strip off the panel.
Return type:: None

set_aspect(ratio)[source]

Return type:: None

set_scalebar_style(color=None, bgcolor=None)[source]

Recolour the automatic scale bar.

The scale bar appears on its own whenever the panel has calibrated axes (units other than "px"). It defaults to white on a translucent dark pill, which reads well on most images but not on a light one.

Parameters:

color (str, optional) – CSS colour for the bar and its label. None (default) leaves it at white.
bgcolor (str, optional) – CSS colour for the pill behind them, or the string "none" to draw no pill at all. None (default) leaves it at the translucent dark pill.

Return type:

None

Examples

>>> plot.set_scalebar_style(color="black", bgcolor="none")

add_widget(kind, color='#00e5ff', **kwargs)[source]

Add an overlay widget by kind name.

Dispatches to the dedicated add_<kind>_widget method. Supported kinds: "circle", "rectangle", "annular", "polygon", "crosshair", "label", "arrow", "line", "brush", "vline", "hline".

Every kind also accepts show_handles (default True) to toggle the grab-handle dots without changing hit-testing / draggability. vline / hline have no handles — the whole line is the grab target — so they ignore it, and neither does brush (a freehand stroke has no grab point).

Parameters:

kind (str)
color (str)

Return type:

Widget

add_circle_widget(cx=None, cy=None, r=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable circle overlay.

Parameters:

cx (float | None)
cy (float | None)
r (float | None)
color (str)
linewidth (float)
show_handles (bool)

Return type:

CircleWidget

add_rectangle_widget(x=None, y=None, w=None, h=None, color='#00e5ff', linewidth=2, show_handles=True, max_extent=None)[source]

Add a draggable rectangle overlay.

max_extent caps the rectangle’s size in the widget’s coordinates — a scalar caps both axes, a (max_w, max_h) pair caps them separately. The rectangle then physically stops growing at the cap while dragging (the dragged corner pins, the opposite corner stays put).

Parameters:

x (float | None)
y (float | None)
w (float | None)
h (float | None)
color (str)
linewidth (float)
show_handles (bool)

Return type:

RectangleWidget

add_annular_widget(cx=None, cy=None, r_outer=None, r_inner=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable annular (ring) overlay.

Parameters:

cx (float | None)
cy (float | None)
r_outer (float | None)
r_inner (float | None)
color (str)
linewidth (float)
show_handles (bool)

Return type:

AnnularWidget

add_polygon_widget(vertices=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable polygon overlay.

Parameters:

color (str)
linewidth (float)
show_handles (bool)

Return type:

PolygonWidget

add_brush_widget(radius=None, color='#00e5ff', colors=None, class_id=0, strokes=None, stroke_classes=None, alpha=0.6, active=True, erase=False)[source]

Add a freehand paint-brush overlay for labelling regions.

Shift + drag paints a stroke; a bare drag still pans the image and still drags other widgets. One brush can hold several label classes at once — a stroke is tagged with the widget’s current class_id and drawn in colors[class_id].

Painting is modal: while the brush is armed, a Shift-press over the image no longer emits a panel pointer_down, so a host that binds Shift-click to something else needs a different modifier (or active=False while that mode is on). A Shift-drag starting in the axis margin is not a brush gesture and pans as usual.

The stroke accumulates in the browser and reaches Python once, on release, as a pointer_up event — pointer_move does not fire for a brush. See BrushWidget.

Parameters:

radius (float, optional) – Brush radius in image pixels; the painted band is 2 * radius wide. Defaults to 2 % of the smaller image dimension (at least 2), so the default is visible on a 4096² image and usable on a 64² one.
color (str, optional) – CSS colour for classes not covered by colors. Default "#00e5ff".
colors (list of str, optional) – Per-class CSS colours, indexed by class_id.
class_id (int, optional) – Label class new strokes are tagged with. Default 0.
strokes (list, optional) – Pre-existing strokes [[[x, y], ...], ...] in image pixels.
stroke_classes (list of int, optional) – Class id per entry of strokes; must be the same length.
alpha (float, optional) – Stroke opacity. Default 0.6, so the labelled feature stays visible underneath.
active (bool, optional) – Accept Shift-drag painting. Default True; False parks the tool with its strokes still drawn.
erase (bool, optional) – Armed drags remove stroke points within radius instead of painting. Default False.

Returns:

Widget object. widget.strokes / widget.stroke_classes hold the painted geometry; clear_strokes() and strokes_for_class() manage it.

Return type:

BrushWidget

add_crosshair_widget(cx=None, cy=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable crosshair overlay.

Parameters:

cx (float | None)
cy (float | None)
color (str)
linewidth (float)
show_handles (bool)

Return type:

CrosshairWidget

add_label_widget(x=None, y=None, text='Label', fontsize=14, color='#00e5ff', show_handles=True)[source]

Add a draggable text label overlay.

Parameters:

x (float | None)
y (float | None)
text (str)
fontsize (int)
color (str)
show_handles (bool)

Return type:

LabelWidget

add_arrow_widget(x=None, y=None, u=None, v=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable arrow overlay (tail at (x, y), head at (x + u, y + v)). Defaults place the tail at 25 %, 25 % of the image with a vector of 15 % of the image size, mirroring add_label_widget()’s defaulting.

Parameters:

x (float | None)
y (float | None)
u (float | None)
v (float | None)
color (str)
linewidth (float)
show_handles (bool)

Return type:

ArrowWidget

add_line_widget(x1=None, y1=None, x2=None, y2=None, color='#00e5ff', linewidth=2, show_handles=True)[source]

Add a draggable two-endpoint line segment overlay.

A bare segment with a grab handle at each end — no arrowhead (see add_arrow_widget()) and no closed path (see add_polygon_widget()). Use it for a line profile, a cross-section cut, or a two-point measurement.

Parameters:

x1 (float, optional) – First endpoint in image coordinates. Defaults to 25 % of the image size.
y1 (float, optional) – First endpoint in image coordinates. Defaults to 25 % of the image size.
x2 (float, optional) – Second endpoint. Defaults to 75 % of the image size.
y2 (float, optional) – Second endpoint. Defaults to 75 % of the image size.
color (str, optional) – CSS colour string. Default "#00e5ff".
linewidth (float, optional) – Stroke width in px. Default 2.
show_handles (bool, optional) – Draw the endpoint grab handles. Default True.

Returns:

Widget object. widget.length gives the segment length in data coordinates.

Return type:

LineWidget

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

Add a draggable full-height vertical line overlay.

The line spans the whole panel and is grabbable anywhere along its length, which makes it the right pointer for “select a column” — a crosshair pinned to one axis leaves a stray perpendicular line.

Parameters:

x (float, optional) – Initial x position in image coordinates. Defaults to the middle.
color (str, optional) – CSS colour string. Default "#00e5ff".
linewidth (float, optional) – Stroke width in px. Default 2.

Return type:

VLineWidget

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

Add a draggable full-width horizontal line overlay.

The row counterpart of add_vline_widget(); grabbable anywhere along its length.

Parameters:

y (float, optional) – Initial y position in image coordinates. Defaults to the middle.
color (str, optional) – CSS colour string. Default "#00e5ff".
linewidth (float, optional) – Stroke width in px. Default 2.

Return type:

HLineWidget

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, transform='data', clip_display=True, size_units='data')[source]

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

size_units="px" pins radius to screen pixels so the circles keep their size through a zoom; the default "data" scales them with the data, as a shape drawn on the image does.

Parameters:

transform (str)
clip_display (bool)
size_units (str)

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, transform='data', clip_display=True, size_units='data')[source]

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

A marker standing in for a point usually wants size_units="px" so it does not grow with zoom — that is what matplotlib does, sizing scatter markers in display points.

Parameters:

transform (str)
clip_display (bool)
size_units (str)

Return type:

MarkerGroup

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

Add static horizontal lines at the given y positions.

Parameters:

transform (str)
clip_display (bool)

Return type:

MarkerGroup

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

Add static vertical lines at the given x positions.

Parameters:

transform (str)
clip_display (bool)

Return type:

MarkerGroup

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

Parameters:

transform (str)
clip_display (bool)

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, transform='data', clip_display=True, size_units='data')[source]

Parameters:

transform (str)
clip_display (bool)
size_units (str)

Return type:

MarkerGroup

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

Parameters:

transform (str)
clip_display (bool)

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, transform='data', clip_display=True, size_units='data')[source]

Parameters:

transform (str)
clip_display (bool)
size_units (str)

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, transform='data', clip_display=True, size_units='data')[source]

Parameters:

transform (str)
clip_display (bool)
size_units (str)

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, transform='data', clip_display=True)[source]

Parameters:

transform (str)
clip_display (bool)

Return type:

MarkerGroup

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

Parameters:

transform (str)
clip_display (bool)

Return type:

MarkerGroup

class anyplotlib.plot2d.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:

data (ndarray)
units (str | None)

Return type:

None

class anyplotlib.plot3d.Plot3D(geom_type, x, y, z, *, colormap='viridis', color='#4fc3f7', colors=None, 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, bounds=None, voxel_size=1.0, alpha=None, texture=None, gpu='auto')[source]

Bases: _BasePlot

3-D plot panel.

Supports four geometry types:

'surface' – triangulated surface, Z-coloured via colormap, or wrapped in an image with set_texture() (globes, star charts).
'scatter' – point cloud; single colour or per-point colors.
'line' – connected line through 3-D points.
'voxels' – shaded translucent cubes at the given centres; voxels lying on a PlaneWidget slice render more opaque.

A single point can be emphasised with set_highlight() (e.g. the “current” orientation in an IPF explorer), and bounds= fixes the axes extents for origin-true geometry such as unit vectors on a sphere. Draggable PlaneWidget slice selectors are added with add_widget().

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:

geom_type (str)
colormap (str)
color (str)
point_size (float)
linewidth (float)
x_label (str)
y_label (str)
z_label (str)
azimuth (float)
elevation (float)
zoom (float)
voxel_size (float)
alpha (float | None)
gpu (str | bool)

add_widget(kind, **kwargs)[source]

Add an interactive overlay widget to this 3-D panel.

Currently supports "plane" — a draggable axis-aligned slice plane (see PlaneWidget):

pw = vol.add_widget("plane", axis="z", position=24)

@pw.add_event_handler("pointer_move")
def on_drag(event):
    resliced(int(round(pw.position)))

Parameters:: kind (str)

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

set_voxel_alpha(alpha, slice_alpha=None)[source]

Set voxel transparency (geom_type 'voxels').

Parameters:

alpha (float) – Base opacity (0–1) for voxels not on any plane widget.
slice_alpha (float, optional) – Opacity for voxels lying on a PlaneWidget slice. None keeps the current value (default 0.95).

Return type:

None

to_state_dict()[source]

Return type:: dict

property gpu_active: bool

True if this panel is currently rendering geometry on the GPU.

Reflects the JS renderer’s decision after the first frame: WebGPU is used only when available and when the panel’s gpu policy and point count call for it. Always False on the Canvas2D fallback path (no navigator.gpu, no adapter, device lost, or gpu=False).

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 (°).

Uses a targeted field push so re-aiming the camera never re-transmits the panel’s geometry — important for large voxel/scatter panels.

Parameters:

azimuth (float | None)
elevation (float | None)

Return type:

None

set_zoom(zoom)[source]

Parameters:: zoom (float)
Return type:: None

reset_view()[source]

Restore the camera to the angles/zoom set at construction time.

Return type:: None

set_xlabel(label, fontsize=None)[source]

Set the x-axis label (mini-TeX allowed; default size 11 px).

Parameters:

label (str)
fontsize (float | None)

Return type:

None

set_ylabel(label, fontsize=None)[source]

Set the y-axis label (mini-TeX allowed; default size 11 px).

Parameters:

label (str)
fontsize (float | None)

Return type:

None

set_zlabel(label, fontsize=None)[source]

Set the z-axis label (mini-TeX allowed; default size 11 px).

Parameters:

label (str)
fontsize (float | None)

Return type:

None

get_xlim()[source]

Return the data x range as (xmin, xmax).

Return type:: tuple

get_ylim()[source]

Return the data y range as (ymin, ymax).

Return type:: tuple

get_zlim()[source]

Return the data z range as (zmin, zmax).

Return type:: tuple

set_data(x, y, z)[source]

Replace the geometry data (same shape rules as the constructor).

Bounds given at construction time (bounds=) are preserved. An auto-mapped texture (set_texture() without uv=) follows the new grid, keeping the flip_v it was applied with; explicit UVs are kept and must still match the vertex count.

Return type:: None

set_texture(image, *, uv=None, alpha=1.0, shade=False, cull_backfaces=False, flip_v=False)[source]

Wrap an image around this surface (geom_type == 'surface').

Each triangle is filled with the matching patch of image, so the picture follows the geometry as you orbit — a globe, a planet, or a star chart on the celestial sphere. By default the image is mapped parametrically: its left edge to the surface grid’s first column, its right edge to the last, its top row to the grid’s first row. Build the sphere with longitude along the columns and latitude down the rows and an equirectangular (plate-carrée) image lands exactly right.

Rendering goes through WebGPU when it is available and the surface has more than ~2k triangles (see the gpu argument to Axes.plot_surface()), which lifts the practical grid size from a few thousand triangles to hundreds of thousands. Without a GPU — or with alpha below 1, which needs the Canvas2D compositing path — every triangle is texture-mapped on the CPU instead, so prefer a coarse grid there and let the image carry the detail.

Parameters:

image (array-like, bytes, or path) – An (H, W, 3|4) colour array (uint8, or float 0–1 — a PIL image works too), the raw bytes of a PNG/JPEG/GIF/WebP, or a path to such a file. Encoded input is passed through untouched; arrays are PNG-compressed. Very large images cost wire size and decode time — 2048×1024 is plenty for a sphere.
uv ((U, V) or (N, 2) array, optional) – Explicit texture coordinates in 0–1, one per vertex, instead of the default parametric mapping. U/V may be given in the grid’s 2-D shape or already flattened.
alpha (float, optional) – Opacity of the whole textured surface, 0–1. Default 1. Below 1 the surface is composited as one translucent skin — whatever the panel draws behind it (a reference sphere, a scatter cloud) shows through, but the surface’s own far side does not.
shade (bool, optional) – Modulate the texture with diffuse lighting from the upper left. Default False (the image is reproduced faithfully); True gives a sphere its familiar lit look and makes relief read as relief.
cull_backfaces (bool, optional) – Skip triangles facing away from the camera. Default False. Set True for a closed surface (sphere, ellipsoid, blob) — it halves the drawing work with no visual change. On an open surface it makes the back side invisible, which is usually not what you want. Ignored on the WebGPU path, where the depth buffer resolves occlusion exactly and culling buys nothing.
flip_v (bool, optional) – Mirror the mapping vertically (v → 1 - v). Use when the image is stored bottom-up relative to the grid’s row order. Remembered for the auto mapping, so a later set_data() rebuilds the UVs with the same flip.

Raises:

ValueError – If this is not a 'surface' panel, alpha is outside [0, 1], image is not a decodable image, or uv does not cover every vertex.

Return type:

None