cdiutils.interactive.plot_3d_isosurface#

cdiutils.interactive.plot_3d_isosurface(amplitude, quantities, voxel_size=None, initial_quantity=None, cmap=None, vmin=None, vmax=None, convention=None, figsize=(9, 6), title=None, lighting_params=None, camera_position=None, theme='plotly_white')[source]#

Plot an interactive 3D isosurface using Plotly and ipywidgets.

This function creates an interactive 3D visualisation where users can adjust the isosurface threshold, switch between different scalar quantities, change colormaps, and control colourbar scaling using interactive widgets. The camera view is preserved when updating.

Interactive Controls:

  • Isosurface slider: Adjust threshold level (0-1 normalised)

  • Quantity dropdown: Switch between different quantities

  • Colourmap dropdown: Change the colourmap on-the-fly

  • Set limits checkbox: Enable manual colourbar limits (default: OFF) * When OFF: Auto-scales to min/max of current plot * When ON: Enables vmin/vmax input fields for manual control

  • vmin/vmax inputs: Set custom colourbar limits (disabled unless “Set limits” is checked)

  • Symmetric colourbar: Centre at 0 for strain/phase data (default: OFF)

  • Replace NaN with mean: Replace NaN values with mean to avoid weird colouring artefacts (default: OFF)

Parameters:

  • amplitude (np.ndarray) – 3D array for determining isosurface levels.

  • quantities (dict[str, np.ndarray]) – Dictionary of 3D arrays to visualise, with keys as quantity names and values as numpy arrays.

  • voxel_size (tuple[float, float, float] | None, optional) – Size of voxels (dx, dy, dz) for proper scaling. Defaults to (1.0, 1.0, 1.0).

  • initial_quantity (str | None, optional) – Name of the quantity to display initially. Must be a key in quantities dict. If None, uses the first key in quantities. Defaults to None.

  • cmap (str | None, optional) – Initial colourmap name. Defaults to “viridis”.

  • vmin (float | None, optional) – Initial minimum value for colour scale. If None, auto-scales to data minimum. Defaults to None.

  • vmax (float | None, optional) – Initial maximum value for colour scale. If None, auto-scales to data maximum. Defaults to None.

  • convention (str | None, optional) – Coordinate convention (“cxi” or “xu”). Defaults to “cxi”.

  • figsize (tuple[int, int], optional) – Figure size in inches (width, height). Defaults to (9, 6).

  • title (str | None, optional) – Plot title. Defaults to “Interactive 3D Isosurface”.

  • lighting_params (dict[str, float] | None, optional) – Plotly lighting parameters. Defaults to preset values.

  • camera_position (dict | None, optional) – Initial camera position. Defaults to eye=dict(x=1.5, y=1.5, z=1.5).

  • theme (str, optional) – Plotly theme. Defaults to “plotly_white”.

Returns:

ipywidgets VBox containing controls and the figure widget.

Return type:

VBox

Raises:

  • PlotlyImportError – if plotly or required packages are not installed.

  • ValueError – if amplitude and quantities have different shapes, or if initial_quantity is not in quantities dict.

Example

>>> import numpy as np
>>> amp = np.random.rand(50, 50, 50)
>>> strain = np.random.randn(50, 50, 50) * 0.01
>>> phase = np.random.randn(50, 50, 50) * np.pi
>>> widget = plot_3d_isosurface(
...     amp,
...     {"het_strain": strain, "phase": phase},
...     voxel_size=(1.0, 1.0, 1.0),
...     initial_quantity="het_strain",
...     cmap="cet_CET_D13"
... )
>>> display(widget)