anyplotlib.Plot3D

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

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)

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)

Remove a widget by ID string or Widget instance.

Return type:

None

list_widgets()

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

Return type:

list

set_voxel_alpha(alpha, slice_alpha=None)

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

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)

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

Parameters:

name (str)

Return type:

None

set_view(azimuth=None, elevation=None)

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)

Parameters:

zoom (float)

Return type:

None

reset_view()

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

Return type:

None

set_xlabel(label, fontsize=None)

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)

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)

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

Parameters:

• label (str)

• fontsize (float | None)

Return type:

None

get_xlim()

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

Return type:

tuple

get_ylim()

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

Return type:

tuple

get_zlim()

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

Return type:

tuple

set_data(x, y, z)

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)

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

See also

clear_texture

Remove the texture and fall back to colormapped Z.

Examples

lat = np.linspace(np.pi / 2, -np.pi / 2, 180)    # rows: N → S
lon = np.linspace(-np.pi, np.pi, 360)            # cols: W → E
LON, LAT = np.meshgrid(lon, lat)
X = np.cos(LAT) * np.cos(LON)
Y = np.cos(LAT) * np.sin(LON)
Z = np.sin(LAT)

globe = ax.plot_surface(X, Y, Z, bounds=((-1, 1),) * 3)
globe.set_texture("earth.jpg", shade=True, cull_backfaces=True)

clear_texture()

Remove the image texture; the surface reverts to colormapped Z.

Return type:

None

property has_texture: bool

True when an image texture is currently applied.

set_point_colors(colors)

Set (or clear) per-point colours on a scatter or voxels panel.

Parameters:

colors (list of "#rrggbb" strings, (N, 3) array, or None) – One colour per point / voxel. Floats are interpreted as 0–1 (or 0–255 when the max exceeds 1). None reverts to the single color for all elements.

Return type:

None

set_highlight(x, y, z, *, color='#ff1744', size=7.0)

Mark one 3-D point with an emphasised dot drawn on top.

The highlight is independent of the panel’s geometry — use it to flag the “current” item in a point cloud or on a surface (e.g. the orientation under a crosshair in an IPF explorer). Points on the far side of the data are drawn semi-transparent as a depth cue.

Parameters:

• x (float) – Position in data coordinates.

• y (float) – Position in data coordinates.

• z (float) – Position in data coordinates.

• color (str, optional) – CSS colour of the dot and ring. Default "#ff1744".

• size (float, optional) – Dot radius in pixels. Default 7.

Return type:

None

See also

clear_highlight

Remove the highlight.

clear_highlight()

Remove the highlight point set by set_highlight().

Return type:

None

set_sphere(radius=1.0, *, color='#9e9e9e', alpha=0.15, wireframe=True)

Draw an origin-centred reference sphere behind the data.

Rendered as a shaded silhouette disk plus latitude/longitude wireframe arcs (far-side arcs dimmed). Scatter points on the far side of the sphere are also dimmed, so a point cloud on the sphere reads with correct depth — ideal for inverse-pole-figure / orientation plots of unit vectors.

Assumes origin-centred, isotropic bounds — pass bounds=((-r, r),) * 3 to the constructor so the sphere’s screen silhouette is a true circle.

Parameters:

• radius (float, optional) – Sphere radius in data units. Default 1 (unit sphere).

• color (str, optional) – Base CSS colour of the shading and wireframe. Default grey.

• alpha (float, optional) – Opacity of the shaded silhouette (0–1). Default 0.15.

• wireframe (bool, optional) – Draw latitude/longitude arcs. Default True.

Return type:

None

See also

clear_sphere

Remove the reference sphere.

clear_sphere()

Remove the reference sphere set by set_sphere().

Return type:

None