Plotting¶

2-D Matplotlib and 3-D PyVista visualization. All PyVista helpers accept plotter= to compose several objects in one scene. See the Visualization user guide.

2-D (Matplotlib)¶

plot2D_pressure_slices ¶

plot2D_pressure_slices(
    pressure_field,
    x=None,
    y=None,
    z=None,
    *,
    coords=None,
    time_array=None,
    db_scale=True,
    figsize=None,
    save_path=None,
    file_name="pressure_field.png",
    video_duration_s=5,
    fps=30,
    center=None,
    center_to_max=False,
    title=None,
    label=None,
    ratios=None,
    p_max=None,
    **kwargs,
)

Plot orthogonal 2D slices of a pressure field.

Handles both monochromatic (3D) and transient (4D) data. For 3D data a single static figure is produced; for 4D data frames are displayed sequentially and optionally saved to disk.

If the 3D field has exactly one singleton dimension it is treated as a single plane and plotted as one image. Otherwise three orthogonal planes (XZ at y0, XY at z0, YZ at x0) are shown side-by-side.

Parameters:

Name	Type	Description	Default
`pressure_field`	`ndarray`	Pressure field data: Shape `(Nx, Ny, Nz)`: monochromatic (static) field. Shape `(Nt, Nx, Ny, Nz)`: transient field, time along axis 0.	required
`x`	`ndarray`	Coordinate arrays in mm. If None, default indices are used.	`None`
`y`	`ndarray`	Coordinate arrays in mm. If None, default indices are used.	`None`
`z`	`ndarray`	Coordinate arrays in mm. If None, default indices are used.	`None`
`coords`	`dict`	Coordinate dict with keys `"x"`, `"y"`, `"z"` (and optionally `"t0"`, `"dt"`). Overrides individual x, y, z when provided.	`None`
`time_array`	`ndarray`	Physical time values in seconds for each frame. Only used for 4D data. If None, frame indices are used as labels.	`None`
`db_scale`	`bool`	Convert pressures to dB before plotting. Default True.	`True`
`figsize`	`tuple of float`	Figure size `(width, height)` in inches.	`None`
`save_path`	`str or Path`	Output directory. If None, nothing is saved. 3D: saves one image named `<file_name>.png`. 4D: saves one image per frame and attempts to assemble an mp4 via ffmpeg (falls back to GIF via pillow).	`None`
`file_name`	`str`	File name with extension. Default `"pressure_field.png"`. For 4D data, image extensions are auto-swapped to `.mp4`.	`'pressure_field.png'`
`video_duration_s`	`float`	Total display duration in seconds for 4D data. All frames are spread evenly over this duration. Default 5.	`5`
`fps`	`int`	Frame rate for 4D display and export. Default 30.	`30`
`center`	`tuple of float`	Physical location `(xc, yc, zc)` in mm through which the three slice planes are taken (the XZ plane sits at `y = yc`, XY at `z = zc`, YZ at `x = xc`). Each coordinate is matched to its nearest grid index from coords/x/y/z. A component may be None to keep the geometric centre on that axis. Overrides center_to_max. Default None.	`None`
`center_to_max`	`bool`	If True, slice planes pass through the pressure maximum; otherwise through the geometric centre. Ignored when center is given. Default False.	`False`
`title`	`str`	Figure suptitle. For 4D data the time stamp is appended when None.	`None`
`label`	`str`	Colorbar label. Auto-set from `db_scale` when None.	`None`
`ratios`	`array-like of length 3`	Manual column width ratios `[XZ, XY, YZ]`. Auto-computed from physical extents when None. Only used for 3D full-volume data.	`None`
`p_max`	`float`	Reference peak for normalisation. Used as `vmax` in dB conversion or as divisor in linear mode. Defaults to `abs(field).max()`.	`None`
`**kwargs`		Forwarded to :func:`plot2D_pressure_plane` (e.g. `vmin`, `vmax`, `interpolation`).	`{}`

Returns:

Type	Description
`None`	This function displays the figure and returns nothing.

plot2D_transient_slices ¶

plot2D_transient_slices(
    pressure_field,
    x=None,
    y=None,
    z=None,
    *,
    coords=None,
    time_array=None,
    center_mm=None,
    center_to_max=False,
    db_scale=True,
    figsize=None,
    save_path=None,
    file_name="transient_2Dslices.gif",
    video_duration_s=5,
    fps=30,
    title=None,
    label=None,
    p_max=None,
    **kwargs,
)

Animate orthogonal pressure slices of transient data with Matplotlib.

Accepts either a full 4D volume (slices computed internally) or a dict of pre-computed 3D planes (up to 3).

Parameters:

Name	Type	Description	Default
`pressure_field`	`ndarray or dict`	`(Nt, Nx, Ny, Nz)` ndarray: full transient volume. Orthogonal slices are extracted automatically. `dict` with keys from `{"xz", "xy", "yz"}`: pre-computed planes, each `(Nt, N1, N2)`.	required
`x`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`y`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`z`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`coords`	`dict`	Coordinate dict with keys `"x"`, `"y"`, `"z"` (and optionally `"t0"`, `"dt"`). Overrides individual x, y, z when provided.	`None`
`time_array`	`ndarray`	Physical time values (length Nt). If None, frame indices are used.	`None`
`center_mm`	`tuple of float`	`(x0, y0, z0)` in mm. For volume input this selects the slice position; for planes input it sets the subplot titles. Default: geometric centre (volume) or coordinate midpoints (planes).	`None`
`center_to_max`	`bool`	If True and input is a volume, slice through the global pressure maximum instead of center_mm. Default False.	`False`
`db_scale`	`bool`	Convert to dB before display. Default True.	`True`
`figsize`	`tuple of float`	Figure size in inches.	`None`
`save_path`	`str or Path`	Output directory. Saves MP4 (or GIF fallback).	`None`
`file_name`	`str`	Base file name for saved video. Default `"transient_slices"`.	`'transient_2Dslices.gif'`
`video_duration_s`	`float`	Target video duration in seconds. Default 5.	`5`
`fps`	`int`	Frame rate. Default 30.	`30`
`title`	`str`	Override time-stamp text in each frame.	`None`
`label`	`str`	Colorbar label.	`None`
`p_max`	`float`	Reference peak for normalisation / dB conversion.	`None`
`**kwargs`		Forwarded to `imshow` (e.g. `cmap`, `vmin`, `vmax`, `interpolation`).	`{}`

plot2D_pressure_plane ¶

plot2D_pressure_plane(
    pressure_plane,
    x=None,
    z=None,
    *,
    figsize=None,
    title=None,
    plane_axis="y",
    ax=None,
    **kwargs,
)

Plot a 2D pressure plane using matplotlib.pyplot.imshow.

Parameters:

Name	Type	Description	Default
`pressure_plane`	`(len(x), len(z)) numpy.ndarray`	2D pressure plane data.	required
`x`	`ndarray`	First in-plane coordinate array (lateral axis of the slice, mm). If None, default indices are used.	`None`
`z`	`ndarray`	Second in-plane coordinate array (axial axis of the slice, mm). If None, default indices are used.	`None`
`figsize`	`tuple of float`	Figure size in inches. If None, computed from the grid aspect ratio.	`None`
`title`	`str`	Figure title. If None, no title is shown.	`None`
`plane_axis`	`(y, x, z)`	Axis normal to the plane being plotted. Controls axis labels. Default is `"y"`.	`"y"`
`ax`	`Axes`	Existing axes to draw into. If None, a new figure and axes are created.	`None`
`**kwargs`		Forwarded to `matplotlib.axes.Axes.imshow`.	`{}`

Returns:

Type	Description
`Axes`	Axes containing the pressure image.

3-D (PyVista)¶

High-level renderers that open a ready-to-show pv.Plotter.

plot3D_pressure_vol ¶

plot3D_pressure_vol(
    pressure_field,
    x=None,
    y=None,
    z=None,
    *,
    db_scale=False,
    coords=None,
    show_fig=True,
    save_path=None,
    file_name="3D_pressure_slices.mp4",
    scalars="Pressure",
    plotter=None,
    off_screen=False,
    window_size=[520, 720],
    notebook=False,
    plot_focal_spot=False,
    scale=1.0,
    anti_aliasing="ssaa",
    colorbar_title=None,
    box_color="#b0b0b0",
    box_opacity=0.2,
    contour_levels=11,
    bounds_kwargs=None,
    **kwargs,
)

Plot a 3D pressure field as a PyVista volume with bounding box and axes.

Parameters:

Name	Type	Description	Default
`pressure_field`	`(Nx, Ny, Nz) numpy.ndarray`	Pressure field samples on the grid.	required
`x`	`(Nx,) numpy.ndarray`	Lateral coordinates (mm).	`None`
`y`	`(Ny,) numpy.ndarray`	Elevation coordinates (mm).	`None`
`z`	`(Nz,) numpy.ndarray`	Axial coordinates (mm).	`None`
`db_scale`	`bool`	Convert to dB before display. Default False.	`False`
`coords`	`dict`	Coordinate dict with keys `"x"`, `"y"`, `"z"`. Overrides individual x, y, z when provided.	`None`
`show_fig`	`bool`	If True, call `plotter.show()` to display the figure. Default True.	`True`
`save_path`	`str or Path`	Path to save a screenshot. If None, no file is written. Default None.	`None`
`file_name`	`str`	File name for saved screenshot. Default `"3D_pressure_volume.png"`.	`'3D_pressure_slices.mp4'`
`scalars`	`str`	Name of the scalar array attached to the volume. Default `"Pressure"`.	`'Pressure'`
`plotter`	`Plotter`	Existing plotter to draw into. If None, a new plotter is created.	`None`
`off_screen`	`bool`	Render off-screen (no window). Default False.	`False`
`window_size`	`list of int`	Window size `[width, height]` in pixels before `scale`. Default `[520, 720]`.	`[520, 720]`
`notebook`	`bool`	Use notebook-mode rendering. Default False.	`False`
`plot_focal_spot`	`bool`	Draw the focal spot as an isosurface. Default False.	`False`
`scale`	`float`	Resolution scale factor applied to window size and fonts. Default 1.0.	`1.0`
`anti_aliasing`	`str`	PyVista anti-aliasing mode. Default `"ssaa"`.	`'ssaa'`
`colorbar_title`	`str`	Colorbar title. If None, the scalar name is used.	`None`
`box_color`	`str`	Bounding-box colour. Default `"#b0b0b0"`.	`'#b0b0b0'`
`box_opacity`	`float`	Bounding-box opacity. Default 0.2.	`0.2`
`contour_levels`	`int`	Number of isosurface contour levels. Default 11.	`11`
`bounds_kwargs`	`dict`	Keyword arguments forwarded to `plotter.show_bounds()`.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The configured plotter.

plot3D_pressure_slices ¶

plot3D_pressure_slices(
    pressure_field,
    x=None,
    y=None,
    z=None,
    *,
    db_scale=False,
    coords=None,
    show_fig=True,
    save_path=None,
    scalars="Pressure",
    plotter=None,
    off_screen=False,
    window_size=[520, 720],
    notebook=False,
    center_to_max=False,
    scale=1.0,
    anti_aliasing="ssaa",
    colorbar_title=None,
    camera_position=None,
    camera_elevation=None,
    camera_azimuth=None,
    **kwargs,
)

Plot orthogonal XZ/XY/YZ slices of a 3D pressure field using PyVista.

Parameters:

Name	Type	Description	Default
`pressure_field`	`(Nx, Ny, Nz) numpy.ndarray`	Pressure field samples on the grid.	required
`x`	`(Nx,) numpy.ndarray`	Lateral coordinates (mm).	`None`
`y`	`(Ny,) numpy.ndarray`	Elevation coordinates (mm).	`None`
`z`	`(Nz,) numpy.ndarray`	Axial coordinates (mm).	`None`
`db_scale`	`bool`	Convert to dB before display. Default False.	`False`
`coords`	`dict`	Coordinate dict with keys `"x"`, `"y"`, `"z"`. Overrides individual x, y, z when provided.	`None`
`show_fig`	`bool`	If True, call `plotter.show()` to display the figure. Default True.	`True`
`save_path`	`str or Path`	Path to save a screenshot. If None, no file is written. Default None.	`None`
`scalars`	`str`	Name of the scalar array attached to the volume. Default `"Pressure"`.	`'Pressure'`
`plotter`	`Plotter`	Existing plotter to draw into. If None, a new plotter is created.	`None`
`off_screen`	`bool`	Render off-screen (no window). Default False.	`False`
`window_size`	`list of int`	Window size `[width, height]` in pixels before `scale`. Default `[520, 720]`.	`[520, 720]`
`notebook`	`bool`	Use notebook-mode rendering. Default False.	`False`
`center_to_max`	`bool`	If True, centre slices on the pressure maximum; otherwise on the geometric centre. Default False.	`False`
`scale`	`float`	Resolution scale factor applied to window size and fonts. Default 1.0.	`1.0`
`anti_aliasing`	`str`	PyVista anti-aliasing mode. Default `"ssaa"`.	`'ssaa'`
`colorbar_title`	`str`	Colorbar title. If None, the scalar name is used.	`None`
`camera_position`	`str or list`	PyVista camera position. If None, the default view is used.	`None`
`camera_elevation`	`float`	Camera elevation angle in degrees. If None, the default is used.	`None`
`camera_azimuth`	`float`	Camera azimuth angle in degrees. If None, the default is used.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The configured plotter.

plot3D_transient_slices ¶

plot3D_transient_slices(
    pressure_field,
    x=None,
    y=None,
    z=None,
    *,
    coords=None,
    time_array=None,
    center_mm=None,
    center_to_max=False,
    show_fig=True,
    db_scale=False,
    save_path=None,
    file_name=None,
    video_duration_s=5,
    fps=30,
    scalars="Pressure",
    plotter=None,
    off_screen=False,
    window_size=[520, 720],
    notebook=False,
    scale=1.0,
    anti_aliasing="ssaa",
    colorbar_title=None,
    camera_position=None,
    camera_elevation=None,
    camera_azimuth=None,
    vmin=None,
    vmax=None,
    theme="white",
    show_grid_kwargs=None,
    **kwargs,
)

Plot transient pressure slices with PyVista time slider or video.

Accepts either a full 4D volume (slices computed internally) or a dict of pre-computed 3D planes (up to 3).

Parameters:

Name	Type	Description	Default
`pressure_field`	`ndarray or dict`	`(Nt, Nx, Ny, Nz)` ndarray: full transient volume. Orthogonal slices are extracted automatically. `dict` with keys from `{"xz", "xy", "yz"}`: pre-computed planes, each `(Nt, N1, N2)`.	required
`x`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`y`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`z`	`ndarray`	Coordinate arrays in mm. Default: index arrays.	`None`
`coords`	`dict`	Coordinate dict with keys `"x"`, `"y"`, `"z"` (and optionally `"t0"`, `"dt"`). Overrides x, y, z when provided.	`None`
`time_array`	`ndarray`	Physical time values (length Nt). If None, frame indices are used.	`None`
`center_mm`	`tuple of float`	`(x0, y0, z0)` in mm. For volume input this selects the slice position; for planes input it sets the 3-D plane offsets. Default: geometric centre (volume) or coordinate midpoints (planes).	`None`
`center_to_max`	`bool`	If True and input is a volume, slice through the global pressure maximum instead of center_mm. Default False.	`False`
`show_fig`	`bool`	Call `plotter.show()`. Default True.	`True`
`db_scale`	`bool`	Convert to dB before display. Default False.	`False`
`save_path`	`str or Path`	Directory for video export. If None, interactive slider is shown.	`None`
`file_name`	`str`	Video file name with extension (e.g. `"slices.mp4"`, `"slices.gif"`). Default: `"3D_pressure_slices.mp4"` if save_path is not None.	`None`
`video_duration_s`	`float`	Target video duration in seconds. Default 5.	`5`
`fps`	`int`	Video frame rate. Default 30.	`30`
`scalars`	`str`	Scalar array name on each mesh. Default `"Pressure"`.	`'Pressure'`
`plotter`	`Plotter`	Existing plotter (e.g. with a transducer mesh already added).	`None`
`off_screen`	`bool`	Render off-screen. Default False.	`False`
`window_size`	`list of int`	`[width, height]` before scale. Default `[520, 720]`.	`[520, 720]`
`notebook`	`bool`	Notebook rendering mode. Default False.	`False`
`scale`	`float`	Resolution scale factor. Default 1.0.	`1.0`
`anti_aliasing`	`str`	PyVista anti-aliasing mode. Default `"ssaa"`.	`'ssaa'`
`colorbar_title`	`str`	Colorbar title. Default: scalars name.	`None`
`camera_position`	`str or list`	PyVista camera position. Default: automatic.	`None`
`camera_elevation`	`float`	Camera elevation angle in degrees. Default: automatic.	`None`
`camera_azimuth`	`float`	Camera azimuth angle in degrees. Default: automatic.	`None`
`vmin`	`float`	Minimum scalar value for the colour map.	`None`
`vmax`	`float`	Maximum scalar value for the colour map.	`None`
`theme`	`str`	PyVista colour theme. Default `"white"`.	`'white'`
`show_grid_kwargs`	`dict`	Keyword arguments forwarded to `plotter.show_grid()`.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The configured plotter.

PyVista scene helpers¶

Composable add_* helpers — each takes a plotter= and returns it, so scenes are built up one object at a time (pressure, transducer, STL, atlas regions, markers).

add_pressure_vol ¶

add_pressure_vol(
    pressure_vol,
    *,
    plotter=None,
    window_size=[800, 800],
    notebook=False,
    plot_focal_spot=False,
    off_screen=False,
    colorbar_title=None,
    contour_levels=11,
    scale=1,
    vmin=None,
    vmax=None,
    **kwargs,
)

Add a pressure volume mesh to a PyVista plotter.

Parameters:

Name	Type	Description	Default
`pressure_vol`	`ImageData`	The pressure volume data to be added as a mesh.	required
`plotter`	`Plotter`	An existing PyVista plotter to which the pressure volume will be added. If None, a new plotter will be created. Default is None.	`None`
`window_size`	`list`	Size of the plot window. Default is [800, 800].	`[800, 800]`
`notebook`	`bool`	Whether to use notebook mode for the plotter. Default is False.	`False`
`plot_focal_spot`	`bool`	Whether to plot the focal spot as an isosurface. Default is False.	`False`
`off_screen`	`bool`	Whether to render the plot off-screen. Default is False.	`False`
`colorbar_title`	`str`	Title for the colorbar. If None, it will use the name of the scalar field in pressure_vol. Default is None.	`None`
`contour_levels`	`int`	Number of contour levels to use when plotting the pressure volume. Default is 11.	`11`
`scale`	`float`	Scaling factor for font sizes in the scalar bar. Default is 1.	`1`
`vmin`	`float`	Minimum value for the contour levels. If None, it will use the minimum value in the pressure volume. Default is None.	`None`
`vmax`	`float`	Maximum value for the contour levels. If None, it will use the maximum value in the pressure volume. Default is None.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The PyVista plotter with the pressure volume mesh added.

add_transducer_mesh ¶

add_transducer_mesh(
    TX_mesh,
    *,
    plotter=None,
    window_size=[800, 800],
    notebook=False,
    off_screen=False,
    scale=1,
    scalars="Apodization",
    color=None,
    colorbar_title=None,
    **kwargs,
)

Add a transducer mesh to a PyVista plotter, colored by apodization, delays or a flat color.

Parameters:

Name	Type	Description	Default
`TX_mesh`	`PolyData`	The mesh representing the transducer, with point data for apodization and delays.	required
`plotter`	`Plotter`	An existing PyVista plotter to which the transducer mesh will be added. If None a new plotter will be created. Default is None.	`None`
`window_size`	`list`	Base size of the plot window before `scale`. Default is [800, 800].	`[800, 800]`
`notebook`	`bool`	Whether to use notebook mode for the plotter. Default is False.	`False`
`off_screen`	`bool`	Whether to render the plot off-screen. Default is False.	`False`
`scale`	`float`	Resolution scale factor applied to window size and scalar-bar fonts (only when this call creates the plotter). Default is 1.	`1`
`scalars`	`str`	Which scalar field to use for coloring the transducer mesh. Must be either "Apodization" or "Delays". Default is "Apodization".	`'Apodization'`
`color`	`str or tuple`	Uniform PyVista color (name, hex string or RGB tuple). When given it overrides `scalars`: the whole mesh is painted this color and no scalar bar is shown. Default is None (color by `scalars`).	`None`
`colorbar_title`	`str`	Title for the colorbar. If None, it will use "Apodization" or "Delays" based on the scalars parameter. Default is None.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The plotter with the transducer mesh added.

add_3D_vol ¶

add_3D_vol(
    vol_3D,
    *,
    plotter=None,
    notebook=False,
    window_size=[700, 700],
    off_screen=False,
    scale=1,
    colorbar_title=None,
    **kwargs,
)

Add a 3-D volume to a PyVista plotter.

Parameters:

Name	Type	Description	Default
`vol_3D`	`ImageData`	The volume data (e.g. 3-D ultrasound scan).	required
`plotter`	`Plotter`	Existing plotter. If None, a new one is created.	`None`
`notebook`	`bool`	Enable Jupyter notebook rendering. Default False.	`False`
`window_size`	`list of int`	Render window size. Default `[700, 700]`.	`[700, 700]`
`off_screen`	`bool`	Render off-screen. Default False.	`False`
`scale`	`float`	Scaling factor for scalar bar font sizes. Default 1.	`1`
`colorbar_title`	`str`	Title for the colour bar. Defaults to the scalar name.	`None`
`**kwargs`		Forwarded to `plotter.add_volume()`.	`{}`

Returns:

Type	Description
`Plotter`	The plotter with the volume added.

add_2D_image ¶

add_2D_image(
    image_grid,
    *,
    plotter=None,
    notebook=False,
    window_size=[700, 700],
    off_screen=False,
    scale=1,
    colorbar_title=None,
    **kwargs,
)

Add a 2D image as a mesh to a PyVista plotter.

Parameters:

Name	Type	Description	Default
`image_grid`	`ImageData`	The 2D image data to be added as a mesh (e.g. 2D ultrasound image).	required
`plotter`	`Plotter`	An existing PyVista plotter to which the image will be added. If None, a new plotter will be created. Default is None.	`None`
`notebook`	`bool`	Whether to use notebook mode for the plotter. Default is False.	`False`
`window_size`	`list`	Size of the plot window. Default is [700, 700].	`[700, 700]`
`off_screen`	`bool`	Whether to render the plot off-screen. Default is False.	`False`
`scale`	`float`	Scaling factor for font sizes in the scalar bar. Default is 1.	`1`
`colorbar_title`	`str`	Title for the colour bar. Defaults to the scalar name.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The PyVista plotter with the 2D image mesh added.

add_regions_mesh ¶

add_regions_mesh(
    pv_regions_dict,
    *,
    plotter=None,
    window_size=[800, 800],
    notebook=False,
    off_screen=False,
    kwargs_dict=None,
    **kwargs,
)

Plot the PyVista mesh of specified BrainAtlas structures.

Parameters:

Name	Type	Description	Default
`pv_regions_dict`	`dict or PolyData`	Dictionary of PyVista meshes keyed by region name, or a single mesh.	required
`plotter`	`Plotter`	Existing plotter. If None, a new one is created.	`None`
`window_size`	`list of int`	Render window size in pixels. Default `[800, 800]`.	`[800, 800]`
`notebook`	`bool`	Enable Jupyter notebook rendering. Default False.	`False`
`off_screen`	`bool`	Render off-screen. Default False.	`False`
`kwargs_dict`	`dict`	Per-region keyword arguments for `add_mesh`.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()` as defaults.	`{}`

Returns:

Type	Description
`Plotter`	The plotter with brain region meshes added.

add_stl_mesh ¶

add_stl_mesh(
    stl_mesh,
    *,
    plotter=None,
    window_size=(800, 800),
    notebook=False,
    off_screen=False,
    color="lightblue",
    opacity=1.0,
    show_edges=True,
    edge_color="black",
    ambient=0.3,
    label=None,
    **kwargs,
)

Add an STL mesh to a PyVista plotter.

Parameters:

Name	Type	Description	Default
`stl_mesh`	`PolyData or str or Path`	Mesh object or path to an STL file. If a path is given, the mesh is loaded automatically.	required
`plotter`	`Plotter`	Existing plotter. If None, a new one is created.	`None`
`window_size`	`tuple of int`	Render window size `(width, height)`. Default `(800, 800)`.	`(800, 800)`
`notebook`	`bool`	Enable Jupyter notebook rendering. Default False.	`False`
`off_screen`	`bool`	Render off-screen. Default False.	`False`
`color`	`str or tuple`	Mesh colour. Default `"lightblue"`.	`'lightblue'`
`opacity`	`float`	Mesh opacity from 0 (transparent) to 1 (opaque). Default 1.0.	`1.0`
`show_edges`	`bool`	Show mesh edges. Default True.	`True`
`edge_color`	`str or tuple`	Edge colour when `show_edges=True`. Default `"black"`.	`'black'`
`ambient`	`float`	Ambient lighting coefficient. Default 0.3.	`0.3`
`label`	`str`	Legend label. If None, no label is added.	`None`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The plotter with the STL mesh added.

add_markers ¶

add_markers(
    points,
    *,
    plotter=None,
    notebook=False,
    window_size=(700, 700),
    off_screen=False,
    point_size=1,
    labels=None,
    label_offset=(0, 0, 0),
    label_font_size=12,
    **kwargs,
)

Add marker points and optional labels to a PyVista plotter.

Parameters:

Name	Type	Description	Default
`points`	`(array - like, shape(N, 3))`	Marker coordinates.	required
`plotter`	`Plotter`	Existing plotter. If None, a new one is created.	`None`
`notebook`	`bool`	Enable Jupyter notebook rendering. Default False.	`False`
`window_size`	`tuple of int`	Render window size. Default `(700, 700)`.	`(700, 700)`
`off_screen`	`bool`	Render off-screen. Default False.	`False`
`point_size`	`float`	Size of marker points. Default 1.	`1`
`labels`	`list of str`	Text labels for each point.	`None`
`label_offset`	`tuple of float`	Offset for label placement. Default `(0, 0, 0)`.	`(0, 0, 0)`
`label_font_size`	`int`	Font size for labels. Default 12.	`12`
`**kwargs`		Forwarded to `plotter.add_mesh()`.	`{}`

Returns:

Type	Description
`Plotter`	The plotter with markers added.

PyVista mesh builders¶

Turn raw arrays or files into PyVista meshes for use with the helpers above.

create_3Dvol_mesh ¶

create_3Dvol_mesh(
    vol_matrix, x=None, y=None, z=None, *, scalars="Values"
)

Create a PyVista volume mesh from coordinate arrays and data.

Parameters:

Name	Type	Description	Default
`vol_matrix`	`ndarray`	Volume data (dim = 3).	required
`x`	`ndarray or None`	1D coordinate arrays for the x, y, and z axes (in mm). If None, pixel indices are used with a default spacing of 1 mm.	`None`
`y`	`ndarray or None`	1D coordinate arrays for the x, y, and z axes (in mm). If None, pixel indices are used with a default spacing of 1 mm.	`None`
`z`	`ndarray or None`	1D coordinate arrays for the x, y, and z axes (in mm). If None, pixel indices are used with a default spacing of 1 mm.	`None`
`scalars`	`str`	Name for the scalar data array. Default `'Values'`.	`'Values'`

Returns:

Type	Description
`ImageData`	The volume mesh with attached scalar data.

create_2Dimage_mesh ¶

create_2Dimage_mesh(
    matrix,
    *,
    extent=None,
    plane_offset=None,
    scalars="a.u.",
)

Create a PyVista structured grid from a 2D image matrix.

Parameters:

Name	Type	Description	Default
`matrix`	`(H, W) numpy.ndarray`	2D array representing the image data.	required
`extent`	`tuple of float`	Spatial extent `(x_min, x_max, y_min, y_max)` in mm. If None, pixel indices are used.	`None`
`plane_offset`	`dict`	Single-key dict specifying the out-of-plane offset, e.g. `{"y": 10.0}`. Must have exactly one key (`"x"`, `"y"`, or `"z"`). Defaults to `{"y": 0}`.	`None`
`scalars`	`str`	Name for the scalar data array. Default `"a.u."`.	`'a.u.'`

Returns:

Type	Description
`StructuredGrid`	Structured grid representing the 2D image in world coordinates.

load_mesh_from_stl ¶

load_mesh_from_stl(
    file_path,
    *,
    scale=1.0,
    translation=(0.0, 0.0, 0.0),
    rotation_axis=None,
    rotation_angle=0.0,
)

Load an STL file and return a PyVista mesh with optional transformations.

Parameters:

Name	Type	Description	Default
`file_path`	`str or Path`	Path to the STL file.	required
`scale`	`float`	Uniform scale factor. Default 1.0 (no scaling).	`1.0`
`translation`	`tuple of float`	Translation vector `(dx, dy, dz)`. Default `(0, 0, 0)`.	`(0.0, 0.0, 0.0)`
`rotation_axis`	`tuple of float`	Rotation axis `(x, y, z)`. If None, no rotation is applied.	`None`
`rotation_angle`	`float`	Rotation angle in degrees. Default 0.0.	`0.0`

Returns:

Type	Description
`PolyData`	Loaded mesh with transformations applied.

Export¶

save_pyvista_screenshot ¶

save_pyvista_screenshot(
    plotter,
    save_path,
    file_name: str,
    *,
    transparent_background: bool = True,
) -> Path | None

Save a PyVista plotter screenshot.

Parameters:

Name	Type	Description	Default
`plotter`	`Plotter`	Plotter to capture.	required
`save_path`	`str or Path`	Output directory.	required
`file_name`	`str`	File name with extension (e.g. `"screenshot.png"`).	required
`transparent_background`	`bool`	Use a transparent background in the screenshot.	`True`

Returns:

Type	Description
`Path or None`	Saved path, or `None` on failure.

save_pyvista_movie ¶

save_pyvista_movie(
    plotter,
    save_path,
    file_name: str,
    update_fn,
    frame_indices,
    *,
    fps: int = 30,
) -> Path | None

Record a PyVista animation by iterating frame_indices.

update_fn(idx) is called for each frame index before writing. .gif uses plotter.open_gif; other extensions use plotter.open_movie.

Parameters:

Name	Type	Description	Default
`plotter`	`Plotter`	Plotter to record from.	required
`save_path`	`str or Path`	Output directory.	required
`file_name`	`str`	File name with extension (e.g. `"movie.mp4"`).	required
`update_fn`	`callable`	Called as `update_fn(idx)` for each frame before writing.	required
`frame_indices`	`iterable of int`	Sequence of frame indices to iterate over.	required
`fps`	`int`	Frame rate for video formats.	`30`

Returns:

Type	Description
`Path or None`	Saved path, or `None` on failure.

save_matplotlib_animation ¶

save_matplotlib_animation(
    ani,
    save_path,
    file_name: str,
    *,
    fps: int = 30,
    dpi: int = 150,
) -> Path | None

Save a :class:~matplotlib.animation.FuncAnimation to disk.

For extensions in {.mp4, .avi, .mov} ffmpeg is used directly. For anything else ffmpeg is tried first, falling back to pillow (GIF).

Parameters:

Name	Type	Description	Default
`ani`	`FuncAnimation`	Animation object to save.	required
`save_path`	`str or Path`	Output directory.	required
`file_name`	`str`	File name with extension (e.g. `"anim.mp4"`).	required
`fps`	`int`	Frame rate.	`30`
`dpi`	`int`	Resolution in dots per inch.	`150`

Returns:

Type	Description
`Path or None`	Path that was actually written, or `None` on failure.