anyplotlib.Axes#

class anyplotlib.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')[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.

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', 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 ~8k 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 ~8k; 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" ("-.") . 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

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