zea.visualize¶

Visualization functions for 2D and 3D ultrasound data.

Functions

`pad_or_crop_extent`(image, extent, target_extent)	Pads and/or crops the extent of an image to match a target extent.
`plot_biplanes`(volume[, cmap, resolution, ...])	Plot three intersecting planes from a 3D volume in 3D space.
`plot_frustum_vertices`(rho_range, ...[, ...])	Plots the vertices of a frustum in spherical coordinates and highlights specified planes.
`plot_image_grid`(images[, ncols, cmap, vmin, ...])	Plot a batch of images in a grid.
`plot_quadrants`(ax, array, fixed_coord, cmap, ...)	For a given 3D array, plot a plane with fixed_coord using four individual quadrants.
`set_mpl_style`([style])	Set the matplotlib style.
`visualize_matrix`(matrix[, font_color])	Visualize a matrix with the values in each cell.

zea.visualize.pad_or_crop_extent(image, extent, target_extent)[source]¶

Pads and/or crops the extent of an image to match a target extent.

This is useful for side by side comparison of images with different extents.

Parameters:

image (np.ndarray) – The input image to be padded and/or cropped. Only 2D images are supported. Image shape must be (grid_size_z, grid_size_x).
extent (tuple) – The current extent of the image in the format (x_min, x_max, z_min, z_max).
target_extent (tuple) – The target extent to match in the format (x_min, x_max, z_min, z_max).

Returns:

The padded and/or cropped image.

Return type:

np.ndarray

zea.visualize.plot_biplanes(volume, cmap='gray', resolution=1.0, stride=1, slice_x=None, slice_y=None, slice_z=None, show_axes=None, fig=None, ax=None, **kwargs)[source]¶

Plot three intersecting planes from a 3D volume in 3D space.

Also known as ultrasound biplane visualization.

Parameters:

volume (ndarray) – 3D numpy array representing the volume to be plotted.
cmap (str, optional) – Colormap to be used for plotting. Defaults to “gray”.
resolution (float, optional) – Resolution factor for the volume. Defaults to 1.0.
stride (int, optional) – Stride for plotting the quadrants. Defaults to 1.
slice_x (int, optional) – Index for the slice in the x-plane. Defaults to None.
slice_y (int, optional) – Index for the slice in the y-plane. Defaults to None.
slice_z (int, optional) – Index for the slice in the z-plane. Defaults to None.
show_axes (dict, optional) – Dictionary to specify axis labels and extents. Defaults to None.
fig (matplotlib.figure.Figure, optional) – Matplotlib figure object. Defaults to None. Can be used to reuse the figure in a loop.
ax (matplotlib.axes.Axes3DSubplot, optional) – Matplotlib 3D axes object. Defaults to None. Can be used to reuse the axes in a loop.
**kwargs – Additional keyword arguments for the plot_surface method.

Returns:

A tuple containing the figure and axes objects (fig, ax).

Return type:

tuple

Raises:

AssertionError – If none of slice_x, slice_y, or slice_z are provided.

zea.visualize.plot_frustum_vertices(rho_range, theta_range, phi_range, num_points=20, phi_plane=None, theta_plane=None, rho_plane=None, fig=None, ax=None, color_frustum='blue', phi_color='yellow', theta_color='green', rho_color='red')[source]¶

Plots the vertices of a frustum in spherical coordinates and highlights specified planes.

Parameters:

rho_range (tuple) – Range of rho values (min, max).
theta_range (tuple) – Range of theta values (min, max).
phi_range (tuple) – Range of phi values (min, max).
num_points (int, optional) – Number of points to generate along each edge. Defaults to 20.
phi_plane (float or list, optional) – Value(s) of phi at which to plot plane(s). Defaults to None.
theta_plane (float or list, optional) – Value(s) of theta at which to plot plane(s). Defaults to None.
rho_plane (float or list, optional) – Value(s) of rho at which to plot plane(s). Defaults to None.
fig (matplotlib.figure.Figure, optional) – Figure object to plot on. Defaults to None. Can be used to reuse the figure in a loop.
ax (matplotlib.axes.Axes3DSubplot, optional) – Axes object to plot on. Defaults to None. Can be used to reuse the axes in a loop.

Returns:

A tuple containing the figure and axes objects (fig, ax).

Return type:

tuple

Raises:

ValueError – If no plane is specified (phi_plane, theta_plane, or rho_plane).

Example

>>> from zea.visualize import plot_frustum_vertices
>>> rho_range = [0.1, 10]  # in mm
>>> theta_range = [-0.6, 0.6]  # in rad
>>> phi_range = [-0.6, 0.6]  # in rad
>>> fig, ax = plot_frustum_vertices(
...     rho_range,
...     theta_range=theta_range,
...     phi_range=phi_range,
...     phi_plane=0,
...     phi_color="red",
...     theta_plane=0.2,
...     color_frustum="blue",
... )

zea.visualize.plot_image_grid(images, ncols=None, cmap='gray', vmin=None, vmax=None, interpolation='auto', titles=None, suptitle=None, aspect=None, figsize=None, fig=None, fig_contents=None, remove_axis=True, background_color='black', text_color='white', **kwargs)[source]¶

Plot a batch of images in a grid.

Parameters:

images (List[np.ndarray]) – batch of images.
ncols (int, optional) – Number of columns. Defaults to None.
cmap (str or list, optional) – Colormap. Defaults to ‘gray’. If list, cmap must be of same length as images and is set for each axis.
vmin (float or list, optional) – Minimum plot value. Defaults to None. if list vmin must be of same length as images and is set for each axis.
vmax (float or list , optional) – Maximum plot value. Defaults to None. if list vmax must be of same length as images and is set for each axis.
interpolation (str, optional) – Interpolation method that mpl uses. Defaults to ‘auto’.
titles (list, optional) – List of titles for subplots. Defaults to None.
suptitle (str, optional) – Title for the plot. Defaults to None.
aspect (optional) – Aspect ratio for imshow.
figsize (tuple, optional) – Figure size. Defaults to None.
fig (figure, optional) – Matplotlib figure object. Defaults to None. Can be used to plot on an existing figure.
fig_contents (list, optional) – List of matplotlib image objects. Defaults to None.
remove_axis (bool, optional) – Whether to remove axis. Defaults to True. If False, the axis will be removed and the spines will be hidden, which allows for the labels to still be visible if plotted after the fact.
background_color (str, optional) – Background color. Defaults to None.
**kwargs – arguments for plt.Figure.

Returns:

Matplotlib figure object fig_contents (list): List of matplotlib image objects.

Return type:

fig (figure)

zea.visualize.plot_quadrants(ax, array, fixed_coord, cmap, slice_index, stride=1, centroid=None, **kwargs)[source]¶

For a given 3D array, plot a plane with fixed_coord using four individual quadrants.

Parameters:

ax (matplotlib.axes.Axes3DSubplot) – The 3D axis to plot on.
array (numpy.ndarray) – The 3D array to be plotted.
fixed_coord (str) – The coordinate to be fixed (‘x’, ‘y’, or ‘z’).
cmap (str) – The colormap to be used for plotting.
slice_index (int or None) – The index of the slice to be plotted. If None, the middle slice is used.
stride (int, optional) – The stride step for plotting. Defaults to 1.
centroid (tuple, optional) – centroid around which to break the quadrants. If None, the middle of the image is used.
**kwargs – Additional keyword arguments for the plot_surface method.

Returns:

The axis with the plotted quadrants.

Return type:

matplotlib.axes.Axes3DSubplot

zea.visualize.set_mpl_style(style=None)[source]¶

Set the matplotlib style.

Parameters:

style (str, optional) – Path to the matplotlib style file.
"zea_darkmode.mplstyle" (Defaults to)
default (which is the)
toolbox. (darkmode style used throughout the zea)

Return type:

None

zea.visualize.visualize_matrix(matrix, font_color='white', **kwargs)[source]¶: Visualize a matrix with the values in each cell.