Viz

Visualization of volumetric data.

qim3d.viz.chunks

chunks(zarr_path, **kwargs)

Launches an interactive explorer for large-scale OME-Zarr and Zarr datasets.

This tool enables you to inspect massive 3D or 5D datasets (e.g., bio-imaging pyramids, large block-wise volumes) one chunk at a time without loading the entire file into RAM. It relies on lazy loading, making it ideal for checking data integrity, visualizing specific regions of interest (ROI) in big data, or navigating multi-resolution hierarchies.

Key Features:

• Lazy Exploration: Loads only the specific chunk selected via dropdown menus.
• Multiscale Support: Automatically detects and navigates resolution levels (pyramids) in OME-Zarr groups.
• 5D Navigation: Supports dimensions for Time (T) and Channel (C) in addition to spatial axes (Z, Y, X).
• Versatile Visualization: Switch instantly between a slicer, a slices_grid, or a 3D volumetric rendering for the selected chunk.

Parameters:

Name	Type	Description	Default
zarr_path	str	The filesystem path to the OME-Zarr or Zarr dataset.	required
**kwargs	Any	Additional keyword arguments passed selectively to the underlying visualization function. For example, you can pass cmap='magma' (for slicer/slices) or zoom=1.5 (for volume). Arguments not supported by the currently selected visualization method are ignored.	{}

Returns:

Name	Type	Description
chunk_explorer	VBox	The interactive interface containing controls for scale selection, chunk coordinates, and the visualization display.

Raises:

Type	Description
ValueError	If the dataset dimensionality is not 3D or 5D.

Example

import qim3d

# Visualize interactive chunks explorer
qim3d.viz.chunks('path/to/zarr/dataset.zarr')

Source code in qim3d/viz/_data_exploration.py

def chunks(zarr_path: str, **kwargs) -> widgets.VBox:
    """
    Launches an interactive explorer for large-scale OME-Zarr and Zarr datasets.

    This tool enables you to inspect massive 3D or 5D datasets (e.g., bio-imaging pyramids, large block-wise volumes) one chunk at a time without loading the entire file into RAM. It relies on lazy loading, making it ideal for checking data integrity, visualizing specific regions of interest (ROI) in big data, or navigating multi-resolution hierarchies.

    **Key Features:**

    * **Lazy Exploration:** Loads only the specific chunk selected via dropdown menus.
    * **Multiscale Support:** Automatically detects and navigates resolution levels (pyramids) in OME-Zarr groups.
    * **5D Navigation:** Supports dimensions for Time (T) and Channel (C) in addition to spatial axes (Z, Y, X).
    * **Versatile Visualization:** Switch instantly between a `slicer`, a `slices_grid`, or a 3D `volumetric` rendering for the selected chunk.

    Args:
        zarr_path (str): The filesystem path to the OME-Zarr or Zarr dataset.
        **kwargs (Any): Additional keyword arguments passed selectively to the underlying visualization function.
            For example, you can pass `cmap='magma'` (for `slicer`/`slices`) or `zoom=1.5` (for `volume`). Arguments not supported by the currently selected visualization method are ignored.

    Returns:
        chunk_explorer (widgets.VBox):
            The interactive interface containing controls for scale selection, chunk coordinates, and the visualization display.

    Raises:
        ValueError: If the dataset dimensionality is not 3D or 5D.

    Example:
        ```python
        import qim3d

        # Visualize interactive chunks explorer
        qim3d.viz.chunks('path/to/zarr/dataset.zarr')
        ```
        ![interactive chunks explorer](../../assets/screenshots/chunks_explorer.gif)

    """
    # Opens the Zarr dataset - doesn't load to memory yet
    zarr_data = zarr.open(zarr_path, mode='r')

    title = widgets.HTML('<h2>Chunk Explorer</h2>')
    info_label = widgets.HTML(value='Chunk info will be displayed here')

    def get_num_chunks(shape: Sequence[int], chunk_size: Sequence[int]) -> list[int]:
        return [(s + chunk_size[i] - 1) // chunk_size[i] for i, s in enumerate(shape)]

    def _filter_kwargs(
        function: Callable[..., Any], kwargs: dict[str, Any]
    ) -> dict[str, Any]:
        """Filter kwargs to only include those that are accepted by the function."""
        sig = inspect.signature(function)
        return {k: v for k, v in kwargs.items() if k in sig.parameters}

    def load_and_visualize(
        key: int,
        *coords: int,
        visualization_method: Literal['slicer', 'slices', 'volume'],
        **inner_kwargs: object,
    ) -> Widget | Figure | Output:
        key = _path_from_dropdown(key)
        arr = (
            da.from_zarr(zarr_data)
            if isinstance(zarr_data, zarr.Array)
            else da.from_zarr(zarr_data[key])
        )
        shape = arr.shape
        chunksz = arr.chunks

        if arr.ndim == 3:
            z_idx, y_idx, x_idx = coords
            slices = (
                slice(
                    z_idx * chunksz[0][0], min((z_idx + 1) * chunksz[0][0], shape[0])
                ),
                slice(
                    y_idx * chunksz[1][0], min((y_idx + 1) * chunksz[1][0], shape[1])
                ),
                slice(
                    x_idx * chunksz[2][0], min((x_idx + 1) * chunksz[2][0], shape[2])
                ),
            )
            chunk = arr[slices].compute()
        elif arr.ndim == 5:
            t_idx, c_idx, z_idx, y_idx, x_idx = coords
            slices = (
                slice(
                    t_idx * chunksz[0][0], min((t_idx + 1) * chunksz[0][0], shape[0])
                ),
                slice(
                    c_idx * chunksz[1][0], min((c_idx + 1) * chunksz[1][0], shape[1])
                ),
                slice(
                    z_idx * chunksz[2][0], min((z_idx + 1) * chunksz[2][0], shape[2])
                ),
                slice(
                    y_idx * chunksz[3][0], min((y_idx + 1) * chunksz[3][0], shape[3])
                ),
                slice(
                    x_idx * chunksz[4][0], min((x_idx + 1) * chunksz[4][0], shape[4])
                ),
            )
            chunk = arr[slices].compute()
            chunk = chunk[0, 0, ...]
        else:
            msg = f'Unsupported ndim={arr.ndim}'
            raise ValueError(msg)

        mins, maxs, means = chunk.min(), chunk.max(), chunk.mean()
        ranges = [f'{sl.start}-{sl.stop}' for sl in slices]
        coords_str = ', '.join(str(c) for c in coords)
        info_html = (
            f"<div style='font-size:14px; margin-left:32px'>"
            f"<h3 style='margin:0'>Chunk Info</h3>"
            f'<pre>'
            f'shape      : {chunk.shape}\n'
            f'coords     : ({coords_str})\n'
            f'ranges     : {ranges}\n'
            f'dtype      : {chunk.dtype}\n'
            f'min / max  : {mins:.0f} / {maxs:.0f}\n'
            f'mean value : {means:.0f}\n'
            f'</pre></div>'
        )
        info_label.value = info_html

        if visualization_method == 'slicer':
            kw = _filter_kwargs(qim3d.viz.slicer, inner_kwargs)
            return qim3d.viz.slicer(chunk, **kw)
        if visualization_method == 'slices':
            out = widgets.Output()
            with out:
                kw = _filter_kwargs(qim3d.viz.slices_grid, inner_kwargs)
                fig = qim3d.viz.slices_grid(chunk, **kw)
                display(fig)
            return out
        # volume
        out = widgets.Output()
        with out:
            kw = _filter_kwargs(qim3d.viz.volumetric, inner_kwargs)
            vol = qim3d.viz.volumetric(chunk, show=False, **kw)
            display(vol)
        return out

    def _path_from_dropdown(string: str) -> str:
        return string.split('(')[0].strip()

    if isinstance(zarr_data, zarr.Group):
        scale_opts = [
            f'{key} {zarr_data[key].shape}' for key in sorted(zarr_data.keys())
        ]
    elif isinstance(zarr_data, zarr.Array):
        scale_opts = [
            f'{zarr_data.shape}',
        ]
    drop_style = {'description_width': '120px'}
    scale_dd = widgets.Dropdown(
        options=scale_opts, description='Scale:', style=drop_style
    )

    if isinstance(zarr_data, zarr.Array):
        first_shape = zarr_data.shape
        chunks = zarr_data.chunks
    else:
        first_array = zarr_data[_path_from_dropdown(scale_opts[0])]
        first_shape = first_array.shape
        chunks = first_array.chunks

    if len(first_shape) == 3:
        axis_names = ['Z', 'Y', 'X']
    elif len(first_shape) == 5:
        axis_names = ['T', 'C', 'Z', 'Y', 'X']
    else:
        msg = f'Only 3D or 5D supported, got ndim={len(first_shape)}'
        raise ValueError(msg)

    counts0 = get_num_chunks(first_shape, chunks)
    axis_dds = []
    for name, cnt in zip(axis_names, counts0):
        dd = widgets.Dropdown(
            options=list(range(cnt)), value=0, description=f'{name}:', style=drop_style
        )
        axis_dds.append(dd)

    method_dd = widgets.Dropdown(
        options=['slicer', 'slices', 'volume'],
        value='slicer',
        description='Viz:',
        style=drop_style,
    )

    def disable_observers() -> None:
        for dd in (*axis_dds, method_dd):
            dd.unobserve(_update_vis, names='value')

    def enable_observers() -> None:
        for dd in (*axis_dds, method_dd):
            dd.observe(_update_vis, names='value')

    def _update_coords(key: str) -> None:
        disable_observers()
        key = _path_from_dropdown(key)
        shp = zarr_data[key].shape
        cnts = get_num_chunks(shp, zarr_data[key].chunks)
        for dd, c in zip(axis_dds, cnts):
            dd.options = list(range(c))
            dd.disabled = c == 1
            dd.value = 0
        enable_observers()
        _update_vis()

    def _update_vis(*_) -> None:
        coords = [dd.value for dd in axis_dds]
        widget = load_and_visualize(
            scale_dd.value, *coords, visualization_method=method_dd.value, **kwargs
        )
        container.children = [title, controls_with_info, widget]

    scale_dd.observe(lambda change: _update_coords(scale_dd.value), names='value')
    enable_observers()

    initial = load_and_visualize(
        scale_dd.value,
        *[dd.value for dd in axis_dds],
        visualization_method=method_dd.value,
        **kwargs,
    )

    control_box = widgets.VBox([scale_dd, *axis_dds, method_dd])
    controls_with_info = widgets.HBox([control_box, info_label])
    container = widgets.VBox([title, controls_with_info, initial])
    return container

qim3d.viz.circles

circles(blobs, volume, alpha=0.5, color='#ff9900', **kwargs)

Visualizes detected blobs as circles overlaid on the volume slices.

This function is primarily used to verify the results of blob detection algorithms. It takes a list of detected features (defined by their center coordinates and radius) and projects them onto the 2D slices of the volume. As you scroll through the stack, the circles dynamically resize to represent the cross-section of the 3D spherical blobs at that specific depth, providing an intuitive check for detection accuracy.

Parameters:

Name	Type	Description	Default
blobs	ndarray	A list or array of detected blobs. Each blob is expected to be a 4-tuple or array (z, y, x, radius). This is typically the output from qim3d.detection.blobs.	required
volume	ndarray	The 3D volume (image stack) on which the blobs were detected.	required
alpha	float	The transparency level of the filled circles (0.0 to 1.0). Defaults to 0.5.	0.5
color	str	The color of the circles, capable of accepting hex codes or standard color names. Defaults to "#ff9900" (orange).	'#ff9900'
**kwargs	Any	Additional keyword arguments passed to the underlying qim3d.viz.slices_grid function (e.g., vmin, vmax).	{}

Returns:

Name	Type	Description
slicer_obj	interactive	An interactive widget with a slider to navigate through slices, showing the overlay of detected blobs.

Example

import qim3d
import qim3d.detection

# Get data
vol = qim3d.examples.cement_128x128x128

# Detect blobs, and get binary mask
blobs, _ = qim3d.detection.blobs(
    vol,
    min_sigma=1,
    max_sigma=8,
    threshold=0.001,
    overlap=0.1,
    background="bright"
    )

# Visualize detected blobs with circles method
qim3d.viz.circles(blobs, vol, alpha=0.8, color='blue')

Source code in qim3d/viz/_detection.py

def circles(
    blobs: tuple[float, float, float, float],
    volume: np.ndarray,
    alpha: float = 0.5,
    color: str = '#ff9900',
    **kwargs,
) -> widgets.interactive:
    """
    Visualizes detected blobs as circles overlaid on the volume slices.

    This function is primarily used to verify the results of blob detection algorithms. It takes a list of detected features (defined by their center coordinates and radius) and projects them onto the 2D slices of the volume. As you scroll through the stack, the circles dynamically resize to represent the cross-section of the 3D spherical blobs at that specific depth, providing an intuitive check for detection accuracy.

    Args:
        blobs (np.ndarray): A list or array of detected blobs. Each blob is expected to be a 4-tuple or array `(z, y, x, radius)`. This is typically the output from `qim3d.detection.blobs`.
        volume (np.ndarray): The 3D volume (image stack) on which the blobs were detected.
        alpha (float, optional): The transparency level of the filled circles (0.0 to 1.0). Defaults to 0.5.
        color (str, optional): The color of the circles, capable of accepting hex codes or standard color names. Defaults to "#ff9900" (orange).
        **kwargs (Any): Additional keyword arguments passed to the underlying `qim3d.viz.slices_grid` function (e.g., `vmin`, `vmax`).

    Returns:
        slicer_obj (widgets.interactive):
            An interactive widget with a slider to navigate through slices, showing the overlay of detected blobs.

    Example:
        ```python
        import qim3d
        import qim3d.detection

        # Get data
        vol = qim3d.examples.cement_128x128x128

        # Detect blobs, and get binary mask
        blobs, _ = qim3d.detection.blobs(
            vol,
            min_sigma=1,
            max_sigma=8,
            threshold=0.001,
            overlap=0.1,
            background="bright"
            )

        # Visualize detected blobs with circles method
        qim3d.viz.circles(blobs, vol, alpha=0.8, color='blue')
        ```
        ![blob detection](../../assets/screenshots/blob_detection.gif)
    """

    def _slicer(z_slice):
        clear_output(wait=True)
        fig = qim3d.viz.slices_grid(
            volume[z_slice : z_slice + 1],
            n_slices=1,
            colormap='gray',
            display_figure=False,
            display_positions=False,
            **kwargs,
        )
        # Add circles from deteced blobs
        for detected in blobs:
            z, y, x, s = detected
            if abs(z - z_slice) < s:  # The blob is in the slice
                # Adjust the radius based on the distance from the center of the sphere
                distance_from_center = abs(z - z_slice)
                angle = (
                    np.pi / 2 * (distance_from_center / s)
                )  # Angle varies from 0 at the center to pi/2 at the edge
                adjusted_radius = s * np.cos(angle)  # Radius follows a cosine curve

                if adjusted_radius > 0.5:
                    c = plt.Circle(
                        (x, y),
                        adjusted_radius,
                        color=color,
                        linewidth=0,
                        fill=True,
                        alpha=alpha,
                    )
                    fig.get_axes()[0].add_patch(c)

        display(fig)
        return fig

    position_slider = widgets.IntSlider(
        value=volume.shape[0] // 2,
        min=0,
        max=volume.shape[0] - 1,
        description='Slice',
        continuous_update=True,
    )
    slicer_obj = widgets.interactive(_slicer, z_slice=position_slider)
    slicer_obj.layout = widgets.Layout(align_items='flex-start')

    return slicer_obj

qim3d.viz.compare_volumes

compare_volumes(volume1, volume2, slice_axis=0, slice_index=None, volumetric_visualization=False)

Launches an interactive dashboard to visually compare two 3D volumes side-by-side.

This tool is essential for registration validation (checking alignment), change detection, or analyzing reconstruction errors (residuals). It displays synchronized slices of both volumes alongside a computed difference map. You can switch between 'difference', 'absolute difference', and 'quadratic difference' modes to highlight discrepancies effectively.

If enabled, the tool also provides 3D volumetric rendering (via k3d), allowing you to inspect the spatial distribution of the errors or changes in 3D space.

Parameters:

Name	Type	Description	Default
volume1	ndarray	The first 3D volume (e.g., Ground Truth or Reference).	required
volume2	ndarray	The second 3D volume (e.g., Prediction or Moving Image). Must have the same shape as volume1.	required
slice_axis	int	The initial axis along which to slice (0, 1, or 2). Defaults to 0.	0
slice_index	int	The initial slice index to display. If None, defaults to the middle slice.	None
volumetric_visualization	bool	If True, includes interactive 3D volumetric renderings below the slice views. Defaults to False.	False

Returns:

Name	Type	Description
widget	VBox	The interactive widget containing the comparison controls, slice plots, and optional 3D views.

Example

import qim3d

vol1 = qim3d.generate.volume(noise_scale=0.020, dtype='float32')
vol2 = qim3d.generate.volume(noise_scale=0.021, dtype='float32')

qim3d.viz.compare_volumes(vol1, vol2, volumetric_visualization=True)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume1', 'volume2')
def compare_volumes(
    volume1: np.ndarray,
    volume2: np.ndarray,
    slice_axis: int = 0,
    slice_index: int = None,
    volumetric_visualization: bool = False,
) -> widgets.interactive:
    """
    Launches an interactive dashboard to visually compare two 3D volumes side-by-side.

    This tool is essential for registration validation (checking alignment), change detection, or analyzing reconstruction errors (residuals). It displays synchronized slices of both volumes alongside a computed difference map. You can switch between 'difference', 'absolute difference', and 'quadratic difference' modes to highlight discrepancies effectively.

    If enabled, the tool also provides 3D volumetric rendering (via `k3d`), allowing you to inspect the spatial distribution of the errors or changes in 3D space.

    Args:
        volume1 (np.ndarray): The first 3D volume (e.g., Ground Truth or Reference).
        volume2 (np.ndarray): The second 3D volume (e.g., Prediction or Moving Image). Must have the same shape as `volume1`.
        slice_axis (int, optional): The initial axis along which to slice (0, 1, or 2). Defaults to 0.
        slice_index (int, optional): The initial slice index to display. If `None`, defaults to the middle slice.
        volumetric_visualization (bool, optional): If `True`, includes interactive 3D volumetric renderings below the slice views. Defaults to `False`.

    Returns:
        widget (widgets.VBox):
            The interactive widget containing the comparison controls, slice plots, and optional 3D views.

    Example:
        ```python
        import qim3d

        vol1 = qim3d.generate.volume(noise_scale=0.020, dtype='float32')
        vol2 = qim3d.generate.volume(noise_scale=0.021, dtype='float32')

        qim3d.viz.compare_volumes(vol1, vol2, volumetric_visualization=True)
        ```
        ![volume_comparison](../../assets/screenshots/viz-compare_volumes.png)

    """

    if volume1.ndim != 3:
        msg = 'Volume must be 3D.'
        raise ValueError(msg)
    if volume1.shape != volume2.shape:
        msg = 'Volumes must have the same shape.'
        raise ValueError(msg)

    if np.issubdtype(volume1.dtype, np.unsignedinteger) and np.issubdtype(
        volume2.dtype, np.unsignedinteger
    ):
        log.warning(
            'Volumes have unsigned integer datatypes. Beware of over-/underflow.'
        )

    if slice_axis not in (0, 1, 2):
        msg = 'Invalid slice_axis.'
        raise ValueError(msg)

    if slice_index is None:
        slice_index = volume1.shape[slice_axis] // 2
    if not isinstance(slice_index, int):
        msg = 'slice_index must be an integer.'
        raise ValueError(msg)

    vc = _VolumeComparison(
        volume1, volume2, slice_axis, slice_index, volumetric_visualization
    )
    return vc.build_interactive()

qim3d.viz.export_rotation

export_rotation(path, volume, degrees=360, n_frames=180, fps=30, image_size=(256, 256), colormap='magma', camera_height=2.0, camera_distance='auto', camera_focus='center', show=False)

Exports a 360-degree turntable animation of the volume to a video or GIF.

Generates a spinning orbit visualization of the 3D data, perfect for presentations, reports, or sharing results on the web. It renders the volume from a rotating camera perspective and saves the output as a movie file (.mp4, .webm, .avi) or an animated .gif.

Key Features:

• Presentation Ready: Creates smooth, professional animations of your data.
• Flexible Output: Supports common video formats and high-quality GIFs.
• Customizable Camera: Control the height, distance, and focus point of the rotation.

Parameters:

Name	Type	Description	Default
path	str	The destination file path. Must end with .gif, .avi, .mp4, or .webm. If no extension is provided, defaults to .gif.	required
volume	ndarray	The 3D input volume to be animated.	required
degrees	int	Total rotation angle in degrees (e.g., 360 for a full spin).	360
n_frames	int	Total number of frames to generate. Higher values create smoother/slower animations at fixed FPS.	180
fps	int	Frames per second. Controls the playback speed.	30
image_size	tuple[int, int] or None	Resolution (width, height) of the output frames.	(256, 256)
colormap	str	Matplotlib colormap name for the volume rendering.	'magma'
camera_height	float	Vertical position of the camera relative to the volume's Z-axis height.	2.0
camera_distance	float or str	Distance from the camera to the focus point. str: Use 'auto' to automatically calculate a fitting distance. float: Specific distance in voxel units.	'auto'
camera_focus	list or str	The point the camera rotates around. str: Use 'center' to rotate around the volume center. list: A list of 3 integers [z, y, x] specifying the voxel coordinate.	'center'
show	bool	If True, displays the generated animation inline in the notebook.	False

Raises:

Type	Description
TypeError	If camera_focus or camera_distance is invalid.
ValueError	If path contains an unsupported file extension.

Example

Creation of .gif file with default parameters of a generated volume.

import qim3d
vol = qim3d.generate.volume()

qim3d.viz.export_rotation('test.gif', vol, show=True)

Example

Creation of a .webm file with specified parameters of a generated volume in the shape of a tube.

import qim3d

vol = qim3d.generate.volume(shape='tube')

qim3d.viz.export_rotation('test.webm', vol,
                          degrees = 360,
                          n_frames = 120,
                          fps = 30,
                          image_size = (512,512),
                          camera_height = 3.0,
                          camera_distance = 'auto',
                          camera_focus = 'center',
                          show = True)

Source code in qim3d/viz/_data_exploration.py

def export_rotation(
    path: str,
    volume: np.ndarray,
    degrees: int = 360,
    n_frames: int = 180,
    fps: int = 30,
    image_size: tuple[int, int] | None = (256, 256),
    colormap: str = 'magma',
    camera_height: float = 2.0,
    camera_distance: float | str = 'auto',
    camera_focus: list | str = 'center',
    show: bool = False,
) -> None:
    """
    Exports a 360-degree turntable animation of the volume to a video or GIF.

    Generates a spinning orbit visualization of the 3D data, perfect for presentations, reports, or sharing results on the web. It renders the volume from a rotating camera perspective and saves the output as a movie file (.mp4, .webm, .avi) or an animated .gif.

    **Key Features:**

    * **Presentation Ready:** Creates smooth, professional animations of your data.
    * **Flexible Output:** Supports common video formats and high-quality GIFs.
    * **Customizable Camera:** Control the height, distance, and focus point of the rotation.

    Args:
        path (str): The destination file path. Must end with .gif, .avi, .mp4, or .webm. If no extension is provided, defaults to .gif.
        volume (numpy.ndarray): The 3D input volume to be animated.
        degrees (int, optional): Total rotation angle in degrees (e.g., 360 for a full spin).
        n_frames (int, optional): Total number of frames to generate. Higher values create smoother/slower animations at fixed FPS.
        fps (int, optional): Frames per second. Controls the playback speed.
        image_size (tuple[int, int] or None, optional): Resolution (width, height) of the output frames.
        colormap (str, optional): Matplotlib colormap name for the volume rendering.
        camera_height (float, optional): Vertical position of the camera relative to the volume's Z-axis height.
        camera_distance (float or str, optional): Distance from the camera to the focus point.

            * **str**: Use `'auto'` to automatically calculate a fitting distance.
            * **float**: Specific distance in voxel units.

        camera_focus (list or str, optional): The point the camera rotates around.

            * **str**: Use `'center'` to rotate around the volume center.
            * **list**: A list of 3 integers `[z, y, x]` specifying the voxel coordinate.

        show (bool, optional): If `True`, displays the generated animation inline in the notebook.

    Raises:
        TypeError: If `camera_focus` or `camera_distance` is invalid.
        ValueError: If `path` contains an unsupported file extension.

    Example:
        Creation of .gif file with default parameters of a generated volume.
        ```python
        import qim3d
        vol = qim3d.generate.volume()

        qim3d.viz.export_rotation('test.gif', vol, show=True)
        ```
        ![export_rotation_defaults](../../assets/screenshots/export_rotation_defaults.gif)

    Example:
        Creation of a .webm file with specified parameters of a generated volume in the shape of a tube.
        ```python
        import qim3d

        vol = qim3d.generate.volume(shape='tube')

        qim3d.viz.export_rotation('test.webm', vol,
                                  degrees = 360,
                                  n_frames = 120,
                                  fps = 30,
                                  image_size = (512,512),
                                  camera_height = 3.0,
                                  camera_distance = 'auto',
                                  camera_focus = 'center',
                                  show = True)
        ```
        ![export_rotation_video](../../assets/screenshots/export_rotation_video.gif)

    """
    if not (
        camera_focus == 'center'
        or (
            isinstance(camera_focus, list | np.ndarray)
            and not isinstance(camera_focus, str)
            and len(camera_focus) == 3
        )
    ):
        msg = f'Value "{camera_focus}" for camera focus is invalid. Use "center" or a list of three values.'
        raise TypeError(msg)
    if not (isinstance(camera_distance, float) or camera_distance == 'auto'):
        msg = f'Value "{camera_distance}" for camera distance is invalid. Use "auto" or a float value.'
        raise TypeError(msg)

    if Path(path).suffix == '':
        print(f'Input path: "{path}" does not have a filetype. Defaulting to .gif.')
        path += '.gif'

    # Handle img in (xyz) instead of (zyx) (due to rendering issues with the up-vector, ensure that z=y, such that we now have (x,z,y))
    vol = np.transpose(volume, (2, 0, 1))

    # Create a uniform grid
    grid = pv.ImageData()
    grid.dimensions = np.array(vol.shape) + 1  # PyVista dims are +1 from volume shape
    grid.spacing = (1, 1, 1)
    grid.origin = (0, 0, 0)
    grid.cell_data['values'] = vol.flatten(order='F')  # Fortran order

    # Initialize plotter
    plotter = pv.Plotter(off_screen=True)
    plotter.add_volume(grid, opacity='linear', cmap=colormap)
    plotter.remove_scalar_bar()  # Remove colorbar

    frames = []
    camera_height = vol.shape[1] * camera_height

    if camera_distance == 'auto':
        bounds = np.array(plotter.bounds)  # (xmin, xmax, ymin, ymax, zmin, zmax)
        diag = np.linalg.norm(
            [bounds[1] - bounds[0], bounds[3] - bounds[2], bounds[5] - bounds[4]]
        )
        camera_distance = diag * 2.0

    if camera_focus == 'center':
        _, center, _ = plotter.camera_position
    else:
        center = camera_focus

    center = np.array(center)

    angle_per_frame = degrees / n_frames
    radians_per_frame = np.radians(angle_per_frame)

    # Set up orbit radius and fixed up
    radius = camera_distance
    fixed_up = [0, 1, 0]
    for i in tqdm(range(n_frames), desc='Rendering'):
        theta = radians_per_frame * i
        x = radius * np.sin(theta)
        z = radius * np.cos(theta)
        y = camera_height  # fixed height

        eye = center + np.array([x, y, z])
        plotter.camera_position = [eye.tolist(), center.tolist(), fixed_up]

        plotter.render()
        img = plotter.screenshot(return_img=True, window_size=image_size)
        frames.append(img)

    if path[-4:] == '.gif':
        imageio.mimsave(path, frames, fps=fps, loop=0)

    elif path[-4:] == '.avi' or path[-4:] == '.mp4':
        writer = imageio.get_writer(path, fps=fps)
        for frame in frames:
            writer.append_data(frame)
        writer.close()

    elif path[-5:] == '.webm':
        writer = imageio.get_writer(
            path, fps=fps, codec='vp9', ffmpeg_params=['-crf', '32']
        )
        for frame in frames:
            writer.append_data(frame)
        writer.close()

    else:
        msg = 'Invalid file extension. Please use .gif, .avi, .mp4 or .webm'
        raise ValueError(msg)

    path = _get_save_path(path)
    log.info('File saved to ' + str(path.resolve()))

    if show:
        if path.suffix == '.gif':
            display(Image(filename=path))
        elif path.suffix in ['.avi', '.mp4', '.webm']:
            display(Video(filename=path, html_attributes='controls autoplay loop'))

qim3d.viz.fade_mask

fade_mask(volume, axis=0, colormap='magma', min_value=None, max_value=None)

Launches an interactive tool to tune parameters for edge fading (vignetting) on a 3D volume.

This function helps you find the optimal settings for suppressing boundary artifacts or focusing on the center of the volume. It visualizes the process by displaying three panels: the original slice, the generated weight mask (attenuation map), and the final result. You can adjust the decay rate, ratio (radius), and geometry (spherical or cylindrical) in real-time before applying them permanently using qim3d.operations.fade_mask.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume.	required
axis	int	The axis alignment for the mask geometry (relevant for cylindrical fading). Defaults to 0.	0
colormap	str	The Matplotlib colormap used for displaying the volume and mask. Defaults to 'magma'.	'magma'
min_value	float	Custom minimum intensity for display contrast. If None, uses the data minimum.	None
max_value	float	Custom maximum intensity for display contrast. If None, uses the data maximum.	None

Returns:

Name	Type	Description
slicer_obj	interactive	The interactive widget containing the parameter sliders and the side-by-side visualization.

Example

import qim3d
vol = qim3d.examples.cement_128x128x128
qim3d.viz.fade_mask(vol)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def fade_mask(
    volume: np.ndarray,
    axis: int = 0,
    colormap: str = 'magma',
    min_value: float = None,
    max_value: float = None,
) -> widgets.interactive:
    """
    Launches an interactive tool to tune parameters for edge fading (vignetting) on a 3D volume.

    This function helps you find the optimal settings for suppressing boundary artifacts or focusing on the center of the volume. It visualizes the process by displaying three panels: the original slice, the generated weight mask (attenuation map), and the final result. You can adjust the decay rate, ratio (radius), and geometry (spherical or cylindrical) in real-time before applying them permanently using `qim3d.operations.fade_mask`.

    Args:
        volume (np.ndarray): The 3D input volume.
        axis (int, optional): The axis alignment for the mask geometry (relevant for cylindrical fading). Defaults to 0.
        colormap (str, optional): The Matplotlib colormap used for displaying the volume and mask. Defaults to 'magma'.
        min_value (float, optional): Custom minimum intensity for display contrast. If `None`, uses the data minimum.
        max_value (float, optional): Custom maximum intensity for display contrast. If `None`, uses the data maximum.

    Returns:
        slicer_obj (widgets.interactive):
            The interactive widget containing the parameter sliders and the side-by-side visualization.

    Example:
        ```python
        import qim3d
        vol = qim3d.examples.cement_128x128x128
        qim3d.viz.fade_mask(vol)
        ```
        ![operations-edge_fade_before](../../assets/screenshots/viz-fade_mask.gif)

    """

    # Create the interactive widget
    def _slicer(
        position: int,
        decay_rate: float,
        ratio: float,
        geometry: str,
        invert: bool,
    ) -> Figure:
        fig, axes = plt.subplots(1, 3, figsize=(9, 3))

        slice_img = volume[position, :, :]
        # If min_value is higher than the highest value in the image ValueError is raised
        new_min_value = (
            None
            if (isinstance(min_value, float | int) and min_value > np.max(slice_img))
            else min_value
        )
        new_max_value = (
            None
            if (isinstance(max_value, float | int) and max_value < np.min(slice_img))
            else max_value
        )

        axes[0].imshow(slice_img, cmap=colormap, vmin=new_min_value, vmax=new_max_value)
        axes[0].set_title('Original')
        axes[0].axis('off')

        mask = qim3d.operations.fade_mask(
            np.ones_like(volume),
            decay_rate=decay_rate,
            ratio=ratio,
            geometry=geometry,
            axis=axis,
            invert=invert,
        )
        axes[1].imshow(mask[position, :, :], cmap=colormap)
        axes[1].set_title('Mask')
        axes[1].axis('off')

        masked_volume = qim3d.operations.fade_mask(
            volume,
            decay_rate=decay_rate,
            ratio=ratio,
            geometry=geometry,
            axis=axis,
            invert=invert,
        )
        # If min_value is higher than the highest value in the image ValueError is raised
        slice_img = masked_volume[position, :, :]
        new_min_value = (
            None
            if (isinstance(min_value, float | int) and min_value > np.max(slice_img))
            else min_value
        )
        new_max_value = (
            None
            if (isinstance(max_value, float | int) and max_value < np.min(slice_img))
            else max_value
        )
        axes[2].imshow(slice_img, cmap=colormap, vmin=new_min_value, vmax=new_max_value)
        axes[2].set_title('Masked')
        axes[2].axis('off')

        return fig

    shape_dropdown = widgets.Dropdown(
        options=['spherical', 'cylindrical'],
        value='spherical',  # default value
        description='Geometry',
    )

    position_slider = widgets.IntSlider(
        value=volume.shape[0] // 2,
        min=0,
        max=volume.shape[0] - 1,
        description='Slice',
        continuous_update=False,
    )
    decay_rate_slider = widgets.FloatSlider(
        value=10,
        min=1,
        max=50,
        step=1.0,
        description='Decay Rate',
        continuous_update=False,
    )
    ratio_slider = widgets.FloatSlider(
        value=0.5,
        min=0.1,
        max=1,
        step=0.01,
        description='Ratio',
        continuous_update=False,
    )

    # Create the Checkbox widget
    invert_checkbox = widgets.Checkbox(
        value=False,
        description='Invert',  # default value
    )

    slicer_obj = widgets.interactive(
        _slicer,
        position=position_slider,
        decay_rate=decay_rate_slider,
        ratio=ratio_slider,
        geometry=shape_dropdown,
        invert=invert_checkbox,
    )
    slicer_obj.layout = widgets.Layout(align_items='flex-start')

    return slicer_obj

qim3d.viz.grid_overview

grid_overview(data, n_images=7, colormap_im='gray', colormap_segm='viridis', alpha=0.5, show=False)

Displays an overview grid of images, labels, and masks (if they exist).

Labels are the annotated target segmentations Masks are applied to the output and target prior to the loss calculation in case of sparse labeled data

Parameters:

Name	Type	Description	Default
data	list or Dataset	A list of tuples or Torch dataset containing image, label, (and mask data).	required
n_images	int	The maximum number of images to display. Defaults to 7.	7
colormap_im	str	The colormap to be used for displaying input images. Defaults to 'gray'.	'gray'
colormap_segm	str	The colormap to be used for displaying labels. Defaults to 'viridis'.	'viridis'
alpha	float	The transparency level of the label and mask overlays. Defaults to 0.5.	0.5
show	bool	If True, displays the plot (i.e. calls plt.show()). Defaults to False.	False

Raises:

Type	Description
ValueError	If the data elements are not tuples.

Returns:

Name	Type	Description
fig	Figure	The figure with an overview of the images and their labels.

Notes

• If the image data is RGB, the color map is ignored and the user is informed.
• The number of displayed images is limited to the minimum between n_images and the length of the data.
• The grid layout and dimensions vary based on the presence of a mask.

Source code in qim3d/viz/_metrics.py

def grid_overview(
    data: list ,
    n_images: int = 7,
    colormap_im: str = 'gray',
    colormap_segm: str = 'viridis',
    alpha: float = 0.5,
    show: bool = False,
) -> matplotlib.figure.Figure:
    """
    Displays an overview grid of images, labels, and masks (if they exist).

    Labels are the annotated target segmentations
    Masks are applied to the output and target prior to the loss calculation in case of
    sparse labeled data

    Args:
        data (list or torch.utils.data.Dataset): A list of tuples or Torch dataset containing image, label, (and mask data).
        n_images (int, optional): The maximum number of images to display. Defaults to 7.
        colormap_im (str, optional): The colormap to be used for displaying input images. Defaults to 'gray'.
        colormap_segm (str, optional): The colormap to be used for displaying labels. Defaults to 'viridis'.
        alpha (float, optional): The transparency level of the label and mask overlays. Defaults to 0.5.
        show (bool, optional): If True, displays the plot (i.e. calls plt.show()). Defaults to False.

    Raises:
        ValueError: If the data elements are not tuples.


    Returns:
        fig (matplotlib.figure.Figure): The figure with an overview of the images and their labels.

    Notes:
        - If the image data is RGB, the color map is ignored and the user is informed.
        - The number of displayed images is limited to the minimum between `n_images`
            and the length of the data.
        - The grid layout and dimensions vary based on the presence of a mask.

    """

    # Check if data has a mask
    has_mask = len(data[0]) > 2 and data[0][-1] is not None

    # Check if image data is RGB and inform the user if it's the case
    if len(data[0][0].squeeze().shape) > 2:
        log.info('Input images are RGB: color map is ignored')

    # Check if dataset have at least specified number of images
    if len(data) < n_images:
        log.warning(
            'Not enough images in the dataset. Changing n_images=%d to n_images=%d',
            n_images,
            len(data),
        )
        n_images = len(data)

    # Adapt segmentation cmap so that background is transparent
    colors_segm = colormaps.get_cmap(colormap_segm)(np.linspace(0, 1, 256))
    colors_segm[:128, 3] = 0
    custom_cmap = LinearSegmentedColormap.from_list('CustomCmap', colors_segm)

    # Check if data have the right format
    if not isinstance(data[0], tuple):
        raise ValueError('Data elements must be tuples')

    # Define row titles
    row_titles = ['Input images', 'Ground truth segmentation', 'Mask']

    # Make new list such that possible augmentations remain identical for all three rows
    plot_data = [data[idx] for idx in range(n_images)]

    fig = plt.figure(
        figsize=(2 * n_images, 9 if has_mask else 6), constrained_layout=True
    )

    # create 2 (3) x 1 subfigs
    subfigs = fig.subfigures(nrows=3 if has_mask else 2, ncols=1)
    for row, subfig in enumerate(subfigs):
        subfig.suptitle(row_titles[row], fontsize=22)

        # create 1 x n_images subplots per subfig
        axs = subfig.subplots(nrows=1, ncols=n_images)
        for col, ax in enumerate(np.atleast_1d(axs)):
            if row in [1, 2]:  # Ground truth segmentation and mask
                ax.imshow(plot_data[col][0].squeeze(), cmap=colormap_im)
                ax.imshow(plot_data[col][row].squeeze(), cmap=custom_cmap, alpha=alpha)
                ax.axis('off')
            else:
                ax.imshow(plot_data[col][row].squeeze(), cmap=colormap_im)
                ax.axis('off')

    if show:
        plt.show()
    plt.close()

    return fig

qim3d.viz.grid_pred

grid_pred(in_targ_preds, n_images=7, colormap_im='gray', colormap_segm='viridis', alpha=0.5, show=False)

Displays a grid of input images, predicted segmentations, ground truth segmentations, and their comparison.

Displays a grid of subplots representing different aspects of the input images and segmentations. The grid includes the following rows: - Row 1: Input images - Row 2: Predicted segmentations overlaying input images - Row 3: Ground truth segmentations overlaying input images - Row 4: Comparison between true and predicted segmentations overlaying input images

Each row consists of n_images subplots, where each subplot corresponds to an image from the dataset. The function utilizes various color maps for visualization and applies transparency to the segmentations.

Parameters:

Name	Type	Description	Default
in_targ_preds	tuple	A tuple containing input images, target segmentations, and predicted segmentations.	required
n_images	int	Number of images to display. Defaults to 7.	7
colormap_im	str	Color map for input images. Defaults to "gray".	'gray'
colormap_segm	str	Color map for segmentations. Defaults to "viridis".	'viridis'
alpha	float	Alpha value for transparency. Defaults to 0.5.	0.5
show	bool	If True, displays the plot (i.e. calls plt.show()). Defaults to False.	False

Returns:

Name	Type	Description
fig	Figure	The figure with images, labels and the label prediction from the trained models.

Example

import qim3d dataset = MySegmentationDataset() model = MySegmentationModel() in_targ_preds = qim3d.ml.inference(dataset,model) qim3d.viz.grid_pred(in_targ_preds, colormap_im='viridis', alpha=0.5)

Source code in qim3d/viz/_metrics.py

def grid_pred(
    in_targ_preds: tuple[np.ndarray, np.ndarray, np.ndarray],
    n_images: int = 7,
    colormap_im: str = 'gray',
    colormap_segm: str = 'viridis',
    alpha: float = 0.5,
    show: bool = False,
) -> matplotlib.figure.Figure:
    """
    Displays a grid of input images, predicted segmentations, ground truth segmentations, and their comparison.

    Displays a grid of subplots representing different aspects of the input images and segmentations.
    The grid includes the following rows:
        - Row 1: Input images
        - Row 2: Predicted segmentations overlaying input images
        - Row 3: Ground truth segmentations overlaying input images
        - Row 4: Comparison between true and predicted segmentations overlaying input images

    Each row consists of `n_images` subplots, where each subplot corresponds to an image from the dataset.
    The function utilizes various color maps for visualization and applies transparency to the segmentations.

    Args:
        in_targ_preds (tuple): A tuple containing input images, target segmentations, and predicted segmentations.
        n_images (int, optional): Number of images to display. Defaults to 7.
        colormap_im (str, optional): Color map for input images. Defaults to "gray".
        colormap_segm (str, optional): Color map for segmentations. Defaults to "viridis".
        alpha (float, optional): Alpha value for transparency. Defaults to 0.5.
        show (bool, optional): If True, displays the plot (i.e. calls plt.show()). Defaults to False.

    Returns:
        fig (matplotlib.figure.Figure): The figure with images, labels and the label prediction from the trained models.

    Raises:
        None

    Example:
        import qim3d
        dataset = MySegmentationDataset()
        model = MySegmentationModel()
        in_targ_preds = qim3d.ml.inference(dataset,model)
        qim3d.viz.grid_pred(in_targ_preds, colormap_im='viridis', alpha=0.5)

    """
    import torch

    # Check if dataset have at least specified number of images
    if len(in_targ_preds[0]) < n_images:
        log.warning(
            'Not enough images in the dataset. Changing n_images=%d to n_images=%d',
            n_images,
            len(in_targ_preds[0]),
        )
        n_images = len(in_targ_preds[0])

    # Take only the number of images from in_targ_preds
    inputs, targets, preds = (items[:n_images] for items in in_targ_preds)

    # Adapt segmentation cmap so that background is transparent
    colors_segm = colormaps.get_cmap(colormap_segm)(np.linspace(0, 1, 256))
    colors_segm[:128, 3] = 0
    custom_cmap = LinearSegmentedColormap.from_list('CustomCmap', colors_segm)

    N = n_images
    H = inputs[0].shape[-2]
    W = inputs[0].shape[-1]

    comp_rgb = torch.zeros((N, 4, H, W))
    comp_rgb[:, 1, :, :] = targets.logical_and(preds)
    comp_rgb[:, 0, :, :] = targets.logical_xor(preds)
    comp_rgb[:, 3, :, :] = targets.logical_or(preds)

    row_titles = [
        'Input images',
        'Predicted segmentation',
        'Ground truth segmentation',
        'True vs. predicted segmentation',
    ]

    fig = plt.figure(figsize=(2 * n_images, 10), constrained_layout=True)

    # create 3 x 1 subfigs
    subfigs = fig.subfigures(nrows=4, ncols=1)
    for row, subfig in enumerate(subfigs):
        subfig.suptitle(row_titles[row], fontsize=22)

        # create 1 x n_images subplots per subfig
        axs = subfig.subplots(nrows=1, ncols=n_images)
        for col, ax in enumerate(np.atleast_1d(axs)):
            if row == 0:
                ax.imshow(inputs[col], cmap=colormap_im)
                ax.axis('off')

            elif row == 1:  # Predicted segmentation
                ax.imshow(inputs[col], cmap=colormap_im)
                ax.imshow(preds[col], cmap=custom_cmap, alpha=alpha)
                ax.axis('off')
            elif row == 2:  # Ground truth segmentation
                ax.imshow(inputs[col], cmap=colormap_im)
                ax.imshow(targets[col], cmap=custom_cmap, alpha=alpha)
                ax.axis('off')
            else:
                ax.imshow(inputs[col], cmap=colormap_im)
                ax.imshow(comp_rgb[col].permute(1, 2, 0), alpha=alpha)
                ax.axis('off')

    if show:
        plt.show()
    plt.close()

    return fig

qim3d.viz.histogram

histogram(volume, coarseness=1, ignore_zero=True, bins='auto', slice_index=None, slice_axis=0, vertical_line=None, vertical_line_colormap='qim', kde=False, log_scale=False, despine=True, show_title=True, color='qim3d', edgecolor=None, figsize=(8, 4.5), bin_style='step', return_fig=False, show=True, ax=None, **sns_kwargs)

Computes and displays the intensity distribution (histogram) of a 3D volume or a specific 2D slice.

This function visualizes the frequency of voxel intensities (gray values), which is essential for analyzing data contrast, identifying material phases, and determining threshold values for segmentation. It utilizes seaborn.histplot and includes optimizations for 3D data, such as subsampling (coarseness) to handle large datasets efficiently. You can also overlay Kernel Density Estimates (KDE) or specific threshold markers.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume.	required
coarseness	int or list[int]	Subsampling factor to speed up computation. A value of 1 uses all data; 2 uses every second voxel, etc.	1
ignore_zero	bool	If True, excludes zero-valued voxels (background) from the statistics.	True
bins	int or str	The number of bins or a binning strategy (e.g., 'auto', 'sturges').	'auto'
slice_index	int, str, or None	The specific slice to analyze. If None, analyzes the entire volume. Accepts an integer index or 'middle'.	None
slice_axis	int	The axis along which to extract the slice (0, 1, or 2). Used only if slice_index is provided.	0
vertical_line	int or Iterable	One or more intensity values to mark with vertical dashed lines (e.g., to visualize a threshold cut-off).	None
vertical_line_colormap	str or Iterable	The colormap or list of colors for the vertical lines.	'qim'
kde	bool	If True, computes and overlays a Kernel Density Estimate (smooth curve) of the distribution.	False
log_scale	bool	If True, sets the Y-axis (frequency) to a logarithmic scale.	False
despine	bool	If True, removes the top and right borders of the plot for a cleaner look.	True
show_title	bool	If True, adds a descriptive title with slice/volume information.	True
color	str	The main color of the histogram bars.	'qim3d'
edgecolor	str	The color of the bar edges.	None
figsize	tuple[float, float]	The width and height of the figure in inches.	(8, 4.5)
bin_style	str	The visual style of the histogram ('bars', 'step', or 'poly').	'step'
return_fig	bool	If True, returns the matplotlib.figure.Figure object.	False
show	bool	If True, calls plt.show() to display the plot.	True
ax	Axes	An existing Axes object to plot onto. If provided, the function returns this Axes object (unless return_fig=True).	None
**sns_kwargs	str | float | bool	Additional keyword arguments passed to seaborn.histplot.	{}

Returns:

Name	Type	Description
object	matplotlib.figure.Figure, matplotlib.axes.Axes, or None	The plot object, depending on parameters: matplotlib.figure.Figure: Returned if return_fig=True. matplotlib.axes.Axes: Returned if return_fig=False and ax was provided. None: If return_fig=False and no ax is provided (plot is displayed immediately).

Raises:

Type	Description
ValueError	If slice_axis is invalid or slice_index is out of bounds.

Example

import qim3d

vol = qim3d.examples.bone_128x128x128
qim3d.viz.histogram(vol)

Histogram from a single slice

import qim3d

vol = qim3d.examples.bone_128x128x128
qim3d.viz.histogram(vol, slice_index=100, slice_axis=1, bin_style='bars', edgecolor='white')

Using coarseness for faster computation

import qim3d

vol = qim3d.examples.bone_128x128x128
qim3d.viz.histogram(vol, coarseness=2, kde=True, log_scale=True)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def histogram(
    volume: np.ndarray,
    coarseness: int | list[int] = 1,
    ignore_zero: bool = True,
    bins: int | str = 'auto',
    slice_index: int | str | None = None,
    slice_axis: int = 0,
    vertical_line: int | Iterable = None,
    vertical_line_colormap: str | Iterable = 'qim',
    kde: bool = False,
    log_scale: bool = False,
    despine: bool = True,
    show_title: bool = True,
    color: str = 'qim3d',
    edgecolor: str | None = None,
    figsize: tuple[float, float] = (8, 4.5),
    bin_style: Literal['bars', 'step', 'poly'] = 'step',
    return_fig: bool = False,
    show: bool = True,
    ax: plt.Axes | None = None,
    **sns_kwargs: str | float | bool,
) -> plt.Figure | plt.Axes | None:
    """
    Computes and displays the intensity distribution (histogram) of a 3D volume or a specific 2D slice.

    This function visualizes the frequency of voxel intensities (gray values), which is essential for analyzing data contrast, identifying material phases, and determining threshold values for segmentation. It utilizes `seaborn.histplot` and includes optimizations for 3D data, such as subsampling (`coarseness`) to handle large datasets efficiently. You can also overlay Kernel Density Estimates (KDE) or specific threshold markers.

    Args:
        volume (np.ndarray): The 3D input volume.
        coarseness (int or list[int], optional): Subsampling factor to speed up computation. A value of `1` uses all data; `2` uses every second voxel, etc.
        ignore_zero (bool, optional): If `True`, excludes zero-valued voxels (background) from the statistics.
        bins (int or str, optional): The number of bins or a binning strategy (e.g., 'auto', 'sturges').
        slice_index (int, str, or None, optional): The specific slice to analyze. If `None`, analyzes the entire volume. Accepts an integer index or 'middle'.
        slice_axis (int, optional): The axis along which to extract the slice (0, 1, or 2). Used only if `slice_index` is provided.
        vertical_line (int or Iterable, optional): One or more intensity values to mark with vertical dashed lines (e.g., to visualize a threshold cut-off).
        vertical_line_colormap (str or Iterable, optional): The colormap or list of colors for the vertical lines.
        kde (bool, optional): If `True`, computes and overlays a Kernel Density Estimate (smooth curve) of the distribution.
        log_scale (bool, optional): If `True`, sets the Y-axis (frequency) to a logarithmic scale.
        despine (bool, optional): If `True`, removes the top and right borders of the plot for a cleaner look.
        show_title (bool, optional): If `True`, adds a descriptive title with slice/volume information.
        color (str, optional): The main color of the histogram bars.
        edgecolor (str, optional): The color of the bar edges.
        figsize (tuple[float, float], optional): The width and height of the figure in inches.
        bin_style (str, optional): The visual style of the histogram ('bars', 'step', or 'poly').
        return_fig (bool, optional): If `True`, returns the `matplotlib.figure.Figure` object.
        show (bool, optional): If `True`, calls `plt.show()` to display the plot.
        ax (matplotlib.axes.Axes, optional): An existing Axes object to plot onto. If provided, the function returns this Axes object (unless `return_fig=True`).
        **sns_kwargs: Additional keyword arguments passed to `seaborn.histplot`.

    Returns:
        object (matplotlib.figure.Figure, matplotlib.axes.Axes, or None):
            The plot object, depending on parameters:

            * **matplotlib.figure.Figure**: Returned if `return_fig=True`.
            * **matplotlib.axes.Axes**: Returned if `return_fig=False` and `ax` was provided.
            * **None**: If `return_fig=False` and no `ax` is provided (plot is displayed immediately).

    Raises:
        ValueError: If `slice_axis` is invalid or `slice_index` is out of bounds.

    Example:
        ```python
        import qim3d

        vol = qim3d.examples.bone_128x128x128
        qim3d.viz.histogram(vol)
        ```
        ![viz histogram](../../assets/screenshots/viz-histogram-vol.png)

    Example: Histogram from a single slice
        ```python
        import qim3d

        vol = qim3d.examples.bone_128x128x128
        qim3d.viz.histogram(vol, slice_index=100, slice_axis=1, bin_style='bars', edgecolor='white')
        ```
        ![viz histogram](../../assets/screenshots/viz-histogram-slice.png)

    Example: Using coarseness for faster computation
        ```python
        import qim3d

        vol = qim3d.examples.bone_128x128x128
        qim3d.viz.histogram(vol, coarseness=2, kde=True, log_scale=True)
        ```
        ![viz histogram](../../assets/screenshots/viz-histogram-coarse.png)

    """
    if not (0 <= slice_axis < volume.ndim):
        msg = f'Axis must be an integer between 0 and {volume.ndim - 1}.'
        raise ValueError(msg)

    title_suffixes = []

    if slice_index == 'middle':
        slice_index = volume.shape[slice_axis] // 2

    if slice_index is not None:
        if 0 <= slice_index < volume.shape[slice_axis]:
            img_slice = np.take(volume, indices=slice_index, axis=slice_axis)
            data = img_slice.ravel()
            title = f'Intensity histogram of slice #{slice_index} {img_slice.shape} along axis {slice_axis}'
        else:
            msg = f'Slice index out of range. Must be between 0 and {volume.shape[slice_axis] - 1}.'
            raise ValueError(msg)
    else:
        data = volume.ravel()
        title = f'Intensity histogram for volume {volume.shape}'

    if ignore_zero:
        data = data[data > 0]
        title_suffixes.append('zero-values ignored')

    if title_suffixes:
        title += ' (' + ', '.join(title_suffixes) + ')'

    # Use provided Axes or create new figure
    if ax is None:
        fig, ax = plt.subplots(figsize=figsize)
    else:
        fig = None

    if log_scale:
        ax.set_yscale('log')

    if color == 'qim3d':
        color = qim3d.viz.colormaps.qim(1.0)

    sns.histplot(
        data,
        bins=bins,
        kde=kde,
        color=color,
        element=bin_style,
        edgecolor=edgecolor,
        ax=ax,  # Plot directly on the specified Axes
        **sns_kwargs,
    )

    if vertical_line is not None:
        if isinstance(vertical_line_colormap, str):
            colors = matplotlib.colormaps[vertical_line_colormap]
        elif isinstance(vertical_line_colormap, Iterable):
            colors = lambda x: vertical_line_colormap[x]

        if isinstance(vertical_line, (float | int)):
            ax.axvline(
                x=vertical_line,
                color=colors(0),
                linestyle='--',
                linewidth=2,
            )
        elif isinstance(vertical_line, Iterable):
            for index, line_position in enumerate(vertical_line):
                if isinstance(vertical_line_colormap, str):
                    index = index / (max(len(vertical_line) - 1, 1))
                ax.axvline(
                    x=line_position,
                    color=colors(index),
                    linestyle='--',
                    linewidth=2,
                )

    if despine:
        sns.despine(
            fig=None,
            ax=ax,
            top=True,
            right=True,
            left=False,
            bottom=False,
            offset={'left': 0, 'bottom': 18},
            trim=True,
        )

    ax.set_xlabel('Voxel Intensity')
    ax.set_ylabel('Frequency')

    if show_title:
        ax.set_title(title, fontsize=10)

    # Handle show and return
    if show and fig is not None:
        plt.show()

    if return_fig:
        return fig
    elif ax is not None:
        return ax

qim3d.viz.image_preview

image_preview(image, image_width=80, axis=None, slice=None, relative_intensity=True)

Image preview function

Source code in qim3d/viz/_preview.py

def image_preview(
    image: np.ndarray,
    image_width: int = 80,
    axis: int = None,
    slice: int = None,
    relative_intensity: bool = True,
):
    """ 
    Image preview function
    """
    if image.ndim == 3 and image.shape[2] > 4:
        image = choose_slice(image, axis, slice)
    image = check_and_adjust_image_dims(image)
    ratio = X_STRIDE * image_width / image.shape[1]
    image = check_and_adjust_values(image, relative_intensity)
    image = rescale_image(image, (X_STRIDE * image_width, int(ratio * image.shape[0])))
    print(image_ansi_string(image))

qim3d.viz.iso_surface

iso_surface(volume, colormap='Magma')

Creates an interactive tool to visualize 3D iso-surfaces (surfaces of constant value).

Generates a GUI to extract and render 3D contours from the volume in real-time. This is useful for finding specific intensity boundaries, visualizing segmentation masks, or exploring the shape of objects defined by a specific threshold. It uses Plotly for interaction and includes controls for resolution and transparency.

Key Features:

• Interactive Thresholding: Adjust the iso-value dynamically to see how the surface changes.
• Performance Control: Adjustable resolution slider to balance between mesh quality and rendering speed.
• Visual Styles: Supports wireframe mode, transparency, and various colormaps.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume to be visualized.	required
colormap	str	The initial color map name (e.g., 'Magma', 'Viridis'). Can be changed in the GUI.	'Magma'

Example

import qim3d

vol = qim3d.generate.volume(noise_scale=0.020)
qim3d.viz.iso_surface(vol)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def iso_surface(volume: np.ndarray, colormap: str = 'Magma') -> None:
    """
    Creates an interactive tool to visualize 3D iso-surfaces (surfaces of constant value).

    Generates a GUI to extract and render 3D contours from the volume in real-time. This is useful for finding specific intensity boundaries, visualizing segmentation masks, or exploring the shape of objects defined by a specific threshold. It uses `Plotly` for interaction and includes controls for resolution and transparency.

    **Key Features:**

    * **Interactive Thresholding:** Adjust the iso-value dynamically to see how the surface changes.
    * **Performance Control:** Adjustable resolution slider to balance between mesh quality and rendering speed.
    * **Visual Styles:** Supports wireframe mode, transparency, and various colormaps.

    Args:
        volume (numpy.ndarray): The 3D input volume to be visualized.
        colormap (str, optional): The initial color map name (e.g., 'Magma', 'Viridis'). Can be changed in the GUI.

    Example:
        ```python
        import qim3d

        vol = qim3d.generate.volume(noise_scale=0.020)
        qim3d.viz.iso_surface(vol)
        ```
        ![volume_comparison](../../assets/screenshots/iso_surface.gif)

    """
    IsoSurface(volume, colormap)

qim3d.viz.line_profile

line_profile(volume, slice_axis=0, slice_index='middle', vertical_position='middle', horizontal_position='middle', angle=0, fraction_range=(0.0, 1.0), y_limits='auto')

Creates an interactive tool to visualize intensity profiles along a line segment within a 3D volume.

This function allows you to draw a line on a specific slice of your data and plot the pixel or voxel intensity values along that path. It is ideal for quantitative analysis, such as checking material homogeneity, measuring the sharpness of edges (step functions), or inspecting noise levels across a region of interest (ROI). The tool supports arbitrary angles, dynamic pivot points, and adjustable plot limits.

Key Features:

• Profile Plotting: Real-time graph of intensity values (gray levels) versus distance.
• Flexible Positioning: Define the line by a pivot point (vertical/horizontal) and an angle of rotation.
• Navigation: Select specific slices using indices or keywords like 'middle'.
• Zooming: Focus on specific segments of the line using the fraction_range parameter.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume (image stack).	required
slice_axis	int	The axis along which to extract the 2D slice (0, 1, or 2). Defaults to 0.	0
slice_index	int or str	The index of the slice to display. Can be an integer or a position string ('start', 'middle', 'end'). Defaults to 'middle'.	'middle'
vertical_position	int or str	The vertical coordinate of the line's pivot point. Can be an integer or 'start', 'middle', 'end'. Defaults to 'middle'.	'middle'
horizontal_position	int or str	The horizontal coordinate of the line's pivot point. Can be an integer or 'start', 'middle', 'end'. Defaults to 'middle'.	'middle'
angle	int or float	The angle of the line in degrees relative to the horizontal axis. Floats are rounded to the nearest integer. Defaults to 0.	0
fraction_range	tuple[float, float]	The start and end points of the line segment as a fraction of the image width/height (0.0 to 1.0). Defaults to (0.00, 1.00).	(0.0, 1.0)
y_limits	str or tuple[float, float]	Controls the Y-axis range of the intensity plot. Defaults to 'auto'. 'auto': Dynamically adapts to the min/max intensity on the current line. 'full': Fixes the range to the global min/max of the entire volume. tuple: Manually sets the range (e.g., (0, 255)).	'auto'

Returns:

Name	Type	Description
widget	interactive	The interactive widget object containing the slice viewer and the intensity plot.

Example

import qim3d

vol = qim3d.examples.bone_128x128x128
qim3d.viz.line_profile(vol)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def line_profile(
    volume: np.ndarray,
    slice_axis: int = 0,
    slice_index: int | str = 'middle',
    vertical_position: int | str = 'middle',
    horizontal_position: int | str = 'middle',
    angle: int = 0,
    fraction_range: tuple[float, float] = (0.00, 1.00),
    y_limits: str | tuple[float, float] = 'auto',
) -> widgets.interactive:
    """
    Creates an interactive tool to visualize intensity profiles along a line segment within a 3D volume.

    This function allows you to draw a line on a specific slice of your data and plot the pixel or voxel intensity values along that path. It is ideal for quantitative analysis, such as checking material homogeneity, measuring the sharpness of edges (step functions), or inspecting noise levels across a region of interest (ROI). The tool supports arbitrary angles, dynamic pivot points, and adjustable plot limits.

    **Key Features:**

    * **Profile Plotting:** Real-time graph of intensity values (gray levels) versus distance.
    * **Flexible Positioning:** Define the line by a pivot point (vertical/horizontal) and an angle of rotation.
    * **Navigation:** Select specific slices using indices or keywords like 'middle'.
    * **Zooming:** Focus on specific segments of the line using the `fraction_range` parameter.

    Args:
        volume (np.ndarray): The 3D input volume (image stack).
        slice_axis (int, optional): The axis along which to extract the 2D slice (0, 1, or 2). Defaults to 0.
        slice_index (int or str, optional): The index of the slice to display. Can be an integer or a position string ('start', 'middle', 'end'). Defaults to 'middle'.
        vertical_position (int or str, optional): The vertical coordinate of the line's pivot point. Can be an integer or 'start', 'middle', 'end'. Defaults to 'middle'.
        horizontal_position (int or str, optional): The horizontal coordinate of the line's pivot point. Can be an integer or 'start', 'middle', 'end'. Defaults to 'middle'.
        angle (int or float, optional): The angle of the line in degrees relative to the horizontal axis. Floats are rounded to the nearest integer. Defaults to 0.
        fraction_range (tuple[float, float], optional): The start and end points of the line segment as a fraction of the image width/height (0.0 to 1.0). Defaults to (0.00, 1.00).
        y_limits (str or tuple[float, float], optional): Controls the Y-axis range of the intensity plot. Defaults to 'auto'.

            * **'auto'**: Dynamically adapts to the min/max intensity on the current line.
            * **'full'**: Fixes the range to the global min/max of the entire volume.
            * **tuple**: Manually sets the range (e.g., `(0, 255)`).

    Returns:
        widget (widgets.interactive):
            The interactive widget object containing the slice viewer and the intensity plot.

    Example:
        ```python
        import qim3d

        vol = qim3d.examples.bone_128x128x128
        qim3d.viz.line_profile(vol)
        ```
        ![viz histogram](../../assets/screenshots/viz-line_profile.gif)

    """

    def parse_position(
        pos: int | str,
        pos_range: tuple[int, int],
        name: str,
    ) -> int:
        if isinstance(pos, int):
            if not pos_range[0] <= pos < pos_range[1]:
                msg = (
                    f'Value for {name} must be inside [{pos_range[0]}, {pos_range[1]}]'
                )
                raise ValueError(msg)
            return pos
        elif isinstance(pos, str):
            pos = pos.lower()
            if pos == 'start':
                return pos_range[0]
            elif pos == 'middle':
                return pos_range[0] + (pos_range[1] - pos_range[0]) // 2
            elif pos == 'end':
                return pos_range[1]
            else:
                msg = (
                    f"Invalid string '{pos}' for {name}. "
                    "Must be 'start', 'middle', or 'end'."
                )
                raise ValueError(msg)
        else:
            msg = 'Axis position must be of type int or str.'
            raise TypeError(msg)

    if not isinstance(volume, np.ndarray | da.Array):
        msg = 'Data type for volume not supported.'
        raise ValueError(msg)
    if volume.ndim != 3:
        msg = 'Volume must be 3D.'
        raise ValueError(msg)

    dims = volume.shape
    slice_index = parse_position(slice_index, (0, dims[slice_axis] - 1), 'slice_index')
    # the omission of the ends for the pivot point is due to border issues.
    vertical_position = parse_position(
        vertical_position, (1, np.delete(dims, slice_axis)[0] - 2), 'vertical_position'
    )
    horizontal_position = parse_position(
        horizontal_position,
        (1, np.delete(dims, slice_axis)[1] - 2),
        'horizontal_position',
    )

    if not isinstance(angle, float | int):
        msg = 'Invalid type for angle.'
        raise ValueError(msg)
    angle = round(angle) % 360

    if not (
        0.0 <= fraction_range[0] <= 1.0
        and 0.0 <= fraction_range[1] <= 1.0
        and fraction_range[0] <= fraction_range[1]
    ):
        msg = 'Invalid values for fraction_range.'
        raise ValueError(msg)

    if isinstance(y_limits, str):
        if y_limits not in ['auto', 'full']:
            msg = 'Invalid string value for y_limits.'
            raise ValueError(msg)
    else:
        y_limits = [*y_limits]

    lp = _LineProfile(
        volume,
        slice_axis,
        slice_index,
        vertical_position,
        horizontal_position,
        angle,
        fraction_range,
        y_limits,
    )
    return lp.build_interactive()

qim3d.viz.local_thickness

local_thickness(image, image_lt, max_projection=False, axis=0, slice_index=None, show=False, figsize=(15, 5))

Visualizes a local thickness map alongside the original image and a statistics histogram.

This function provides a comprehensive view of structure width or pore size distribution. It displays a side-by-side comparison of the original data and the computed local thickness (heat map), where color intensity represents the diameter of the largest sphere that fits inside the structure at that point. It also includes a histogram to quantify the distribution of thickness values.

For 3D volumes, the output can be either an interactive slice viewer or a static Maximum Intensity Projection (MIP).

Parameters:

Name	Type	Description	Default
image	ndarray	The original 2D or 3D input data (binary or grayscale).	required
image_lt	ndarray	The computed local thickness map (must have the same shape as image). This is typically the output of qim3d.processing.local_thickness.	required
max_projection	bool	If True (and input is 3D), collapses the volume along the specified axis using maximum projection before plotting. Results in a static 2D figure. Defaults to False.	False
axis	int	The axis along which to slice or project the volume. Defaults to 0.	0
slice_index	int or float	The initial slice to display for 3D volumes. int: The exact index of the slice. float: A fraction between 0.0 and 1.0 (e.g., 0.5 for the middle). None: Defaults to the middle slice.	None
show	bool	If True, explicitly calls plt.show() to render the plot immediately. Defaults to False.	False
figsize	tuple[int, int]	The width and height of the figure in inches. Defaults to (15, 5).	(15, 5)

Returns:

Name	Type	Description
object	interactive or Figure	The visualization object, depending on the input and parameters: widgets.interactive: Returned if the input is 3D and max_projection=False. Contains a slider for slice navigation. matplotlib.figure.Figure: Returned if the input is 2D or if max_projection=True.

Raises:

Type	Description
ValueError	If slice_index is a float outside the range [0, 1].

Example

import qim3d

fly = qim3d.examples.fly_150x256x256
lt_fly = qim3d.processing.local_thickness(fly)
qim3d.viz.local_thickness(fly, lt_fly, axis=0)

Source code in qim3d/viz/_local_thickness.py

def local_thickness(
    image: np.ndarray,
    image_lt: np.ndarray,
    max_projection: bool = False,
    axis: int = 0,
    slice_index: Optional[Union[int, float]] = None,
    show: bool = False,
    figsize: Tuple[int, int] = (15, 5),
) -> Union[plt.Figure, widgets.interactive]:
    """
    Visualizes a local thickness map alongside the original image and a statistics histogram.

    This function provides a comprehensive view of structure width or pore size distribution. It displays a side-by-side comparison of the original data and the computed local thickness (heat map), where color intensity represents the diameter of the largest sphere that fits inside the structure at that point. It also includes a histogram to quantify the distribution of thickness values.

    For 3D volumes, the output can be either an interactive slice viewer or a static Maximum Intensity Projection (MIP).

    Args:
        image (np.ndarray): The original 2D or 3D input data (binary or grayscale).
        image_lt (np.ndarray): The computed local thickness map (must have the same shape as `image`). This is typically the output of `qim3d.processing.local_thickness`.
        max_projection (bool, optional): If `True` (and input is 3D), collapses the volume along the specified axis using maximum projection before plotting. Results in a static 2D figure. Defaults to `False`.
        axis (int, optional): The axis along which to slice or project the volume. Defaults to 0.
        slice_index (int or float, optional): The initial slice to display for 3D volumes.

            * **int**: The exact index of the slice.
            * **float**: A fraction between 0.0 and 1.0 (e.g., 0.5 for the middle).
            * **None**: Defaults to the middle slice.

        show (bool, optional): If `True`, explicitly calls `plt.show()` to render the plot immediately. Defaults to `False`.
        figsize (tuple[int, int], optional): The width and height of the figure in inches. Defaults to (15, 5).

    Returns:
        object (widgets.interactive or matplotlib.figure.Figure):
            The visualization object, depending on the input and parameters:

            * **widgets.interactive**: Returned if the input is 3D and `max_projection=False`. Contains a slider for slice navigation.
            * **matplotlib.figure.Figure**: Returned if the input is 2D or if `max_projection=True`.

    Raises:
        ValueError: If `slice_index` is a float outside the range [0, 1].

    Example:
        ```python
        import qim3d

        fly = qim3d.examples.fly_150x256x256
        lt_fly = qim3d.processing.local_thickness(fly)
        qim3d.viz.local_thickness(fly, lt_fly, axis=0)
        ```
        ![local thickness 3d](../../assets/screenshots/local_thickness_3d.gif)
    """

    def _local_thickness(image, image_lt, show, figsize, axis=None, slice_index=None):
        if slice_index is not None:
            image = image.take(slice_index, axis=axis)
            image_lt = image_lt.take(slice_index, axis=axis)

        fig, axs = plt.subplots(1, 3, figsize=figsize, layout='constrained')

        axs[0].imshow(image, cmap='gray')
        axs[0].set_title('Original image')
        axs[0].axis('off')

        axs[1].imshow(image_lt, cmap='viridis')
        axs[1].set_title('Local thickness')
        axs[1].axis('off')

        plt.colorbar(
            axs[1].imshow(image_lt, cmap='viridis'), ax=axs[1], orientation='vertical'
        )

        axs[2].hist(image_lt[image_lt > 0].ravel(), bins=32, edgecolor='black')
        axs[2].set_title('Local thickness histogram')
        axs[2].set_xlabel('Local thickness')
        axs[2].set_ylabel('Count')

        if show:
            plt.show()

        plt.close()

        return fig

    # Get the middle slice if the input is 3D
    if len(image.shape) == 3:
        if max_projection:
            if slice_index is not None:
                log.warning(
                    'slice_index is not used for max_projection. It will be ignored.'
                )
            image = image.max(axis=axis)
            image_lt = image_lt.max(axis=axis)
            return _local_thickness(image, image_lt, show, figsize)
        else:
            if slice_index is None:
                slice_index = image.shape[axis] // 2
            elif isinstance(slice_index, float):
                if slice_index < 0 or slice_index > 1:
                    raise ValueError(
                        'Values of slice_index of float type must be between 0 and 1.'
                    )
                slice_index = int(slice_index * image.shape[0]) - 1
            slice_index_slider = widgets.IntSlider(
                min=0,
                max=image.shape[axis] - 1,
                step=1,
                value=slice_index,
                description='Slice index',
                layout=widgets.Layout(width='450px'),
            )
            widget_obj = widgets.interactive(
                _local_thickness,
                image=widgets.fixed(image),
                image_lt=widgets.fixed(image_lt),
                show=widgets.fixed(True),
                figsize=widgets.fixed(figsize),
                axis=widgets.fixed(axis),
                slice_index=slice_index_slider,
            )
            widget_obj.layout = widgets.Layout(align_items='center')
            if show:
                display(widget_obj)
            return widget_obj
    else:
        if max_projection:
            log.warning(
                'max_projection is only used for 3D images. It will be ignored.'
            )
        if slice_index is not None:
            log.warning('slice_index is only used for 3D images. It will be ignored.')
        return _local_thickness(image, image_lt, show, figsize)

qim3d.viz.mesh

mesh(mesh, wireframe=False, show_edges=True, show=True, save_screenshot='', export_html='', explode=0, smooth_shading=False, face_color='#cccccc', edge_color='#993333', **kwargs)

Visualize a 3D mesh using pygel3d or pyvista. If you need more advanced tools, use pyvista directly.

Parameters:

Name	Type	Description	Default
mesh	Manifold	The input mesh object.	required
wireframe	bool	If True, displays the mesh as a wireframe. Defaults to False.	False
show_edges	bool	If True, shows edges of the mesh. Fefaults to True.	True
show	bool	If True, displays the visualization inline, useful for multiple plots. Works only with backend pyvista. Defaults to True.	True
save_screenshot	str	If True, saves the visualization as an png file. The string is interpreted as the file path where the screenshot will be saved. Works only with the backend pyvista. Defaults to ''.	''
export_html	str	If True, saves the visualization as an html file. The string is interpreted as the file path where the scene will be saved. Works only with the backend pyvista. Defaults to ''.	''
explode	int	Only works when mesh is qim3d.mesh.VolumeMesh. Defines how spread are the tetrahedrons. If 0, the volume us intact. Defaults to 1.	0
smooth_shading	bool	Smooths out edges. Only works with `pyvista'. Defaults to False.	False
face_color	str	Face color of the mesh. Onyl works with pyvista. Doesn't work with `wireframe = True'. Defaults to '#cccccc'.	'#cccccc'
edge_color	str	Edge color of the mesh. Only works with pyvista. Defaults to '#993333'.	'#993333'
**kwargs	Any	Additional keyword arguments specific to the chosen backend: - pyvista kwargs: Arguments that customize the pyvista visualization. - pygel3d.display kwargs: Arguments that customize the pygel3d.display visualization.	{}

Returns:

Name	Type	Description
None	None	The function displays the mesh but does not return a plot object.

Example

import qim3d

# Generate a 3D blob
synthetic_blob = qim3d.generate.volume()

# Convert the 3D numpy array to a Pygel3D mesh object
mesh = qim3d.mesh.from_volume(synthetic_blob, mesh_precision=0.5)

# Visualize the generated mesh
qim3d.viz.mesh(mesh)

qim3d.viz.mesh(mesh, backend='k3d', wireframe=False, flat_shading=False)

k3d_visualization

Source code in qim3d/viz/_mesh.py

def mesh(
    mesh: pygel3d.hmesh.Manifold | SurfaceMesh | VolumeMesh,
    wireframe: bool = False,
    show_edges: bool = True,
    show: bool = True,
    save_screenshot: str = '',
    export_html:str = '',
    explode: int = 0,
    smooth_shading: bool = False,
    face_color = '#cccccc',
    edge_color = '#993333',
    **kwargs,
) ->  None:
    """
    Visualize a 3D mesh using `pygel3d` or `pyvista`. If you need more advanced tools, use pyvista directly.

    Args:
        mesh (pygel3d.hmesh.Manifold): The input mesh object.
        wireframe (bool, optional): If True, displays the mesh as a wireframe. Defaults to False.
        show_edges (bool, optional): If True, shows edges of the mesh. Fefaults to True.
        show (bool, optional): If True, displays the visualization inline, useful for multiple plots.
            Works only with backend `pyvista`. Defaults to True.
        save_screenshot (str, optional): If True, saves the visualization as an `png` file.
            The string is interpreted as the file path where the screenshot will 
            be saved. Works only with the backend `pyvista`. Defaults to ''.
        export_html (str, optional): If True, saves the visualization as an `html` file.
            The string is interpreted as the file path where the scene will 
            be saved. Works only with the backend `pyvista`. Defaults to ''.
        explode (int, optional): Only works when mesh is qim3d.mesh.VolumeMesh.
            Defines how spread are the tetrahedrons. If 0, the volume us intact.
            Defaults to 1.
        smooth_shading (bool, optional): Smooths out edges. Only works with `pyvista'.
            Defaults to False.
        face_color (str, optional): Face color of the mesh. Onyl works with `pyvista`.
            Doesn't work with `wireframe = True'. Defaults to '#cccccc'.
        edge_color (str, optional): Edge color of the mesh. Only works with `pyvista`.
            Defaults to '#993333'.
        **kwargs (Any): Additional keyword arguments specific to the chosen backend:
            - `pyvista` kwargs: Arguments that customize the [`pyvista`](https://docs.pyvista.org/api/plotting) visualization.
            - `pygel3d.display` kwargs: Arguments that customize the [`pygel3d.display`](https://www2.compute.dtu.dk/projects/GEL/PyGEL/pygel3d/jupyter_display.html#display) visualization.

    Returns:
        None: The function displays the mesh but does not return a plot object.


    Example:
        ```python
        import qim3d

        # Generate a 3D blob
        synthetic_blob = qim3d.generate.volume()

        # Convert the 3D numpy array to a Pygel3D mesh object
        mesh = qim3d.mesh.from_volume(synthetic_blob, mesh_precision=0.5)

        # Visualize the generated mesh
        qim3d.viz.mesh(mesh)
        ```
        ![pygel3d_visualization](../../assets/screenshots/viz-pygel_mesh.png)

        ```python
        qim3d.viz.mesh(mesh, backend='k3d', wireframe=False, flat_shading=False)
        ```
        [k3d_visualization](../../assets/screenshots/sphere.html)
        <div class="scene">
            <iframe src="http://127.0.0.1:8000/qim3d/assets/screenshots/sphere.html" width="100%" height="500" frameborder="0"></iframe>
        </div>


    """

    if isinstance(mesh, (VolumeMesh, SurfaceMesh)):
        plotter = pv.Plotter()

        if isinstance(mesh, VolumeMesh):
            mesh = mesh.explode(explode)

        if wireframe:
            kwargs['style'] =  'wireframe'
        plotter.add_mesh(mesh, 
                         show_edges = show_edges, 
                         smooth_shading = smooth_shading,
                         show_scalar_bar=False,
                         color = face_color,
                         edge_color=edge_color, 
                         **kwargs)

        if show:
            plotter.show()

        if save_screenshot:
            if not save_screenshot.endswith('png'):
                save_screenshot = save_screenshot + '.png'
            plotter.screenshot(save_screenshot)

        if export_html:
            if not export_html.endswith('.html'):
                export_html = export_html + '.html'
            plotter.export_html(export_html)

        return

    if isinstance(mesh, pygel3d.hmesh.Manifold):
        if len(mesh.vertices()) > 100000:
            msg = f'The mesh has {len(mesh.vertices())} vertices, visualization may be slow. Consider using a smaller <mesh_precision> when computing the mesh.'
            log.info(msg)

        jd.set_export_mode(True)
        valid_pygel_kwargs = {k: v for k, v in kwargs.items() if k in ['smooth', 'data']}
        return jd.display(mesh, wireframe=show_edges, **valid_pygel_kwargs)

qim3d.viz.overlay

overlay(volume1, volume2, volume1_values=(None, None), volume2_values=(None, None), colormaps='gray', display_size=512)

Creates an interactive widget to compare two 3D volumes by overlaying them with adjustable transparency.

This tool is essential for tasks like image registration (checking alignment between two scans), segmentation validation (comparing a binary mask against the original raw data), or general change detection. It provides a slider to smoothly fade (blend) between the two volumes, allowing for precise visual inspection of differences and spatial correspondence slice-by-slice.

Parameters:

Name	Type	Description	Default
volume1	ndarray	The first 3D volume (e.g., the reference image).	required
volume2	ndarray	The second 3D volume (e.g., the moving image or segmentation mask). Must have the same shape as volume1.	required
volume1_values	tuple[float, float]	Intensity limits (min, max) for contrast stretching volume1. If (None, None), uses the volume's min and max.	(None, None)
volume2_values	tuple[float, float]	Intensity limits (min, max) for contrast stretching volume2.	(None, None)
colormaps	str or Colormap or tuple	The colormap(s) to apply. Can be a single value (applied to both) or a tuple (cmap1, cmap2). Defaults to 'gray'.	'gray'
display_size	int	The maximum width/height of the displayed image in pixels. Defaults to 512.	512

Returns:

Name	Type	Description
widget	VBox	The interactive widget containing the slicer controls and the fading overlay display.

Example

import qim3d

vol = qim3d.examples.cement_128x128x128
binary = qim3d.filters.gaussian(vol, sigma=2) < 60
labeled_volume, num_labels = qim3d.segmentation.watershed(binary)

segm_cmap = qim3d.viz.colormaps.segmentation(num_labels, style = 'bright')

qim3d.viz.overlay(vol, labeled_volume, colormaps=('grey', segm_cmap), volume2_values=(0, num_labels))

Source code in qim3d/viz/_data_exploration.py

def overlay(
    volume1: np.ndarray,
    volume2: np.ndarray,
    volume1_values: tuple[float, float] = (None, None),
    volume2_values: tuple[float, float] = (None, None),
    colormaps: ColormapLike | tuple[ColormapLike, ColormapLike] = 'gray',
    display_size: int = 512,
) -> widgets.interactive:
    """
    Creates an interactive widget to compare two 3D volumes by overlaying them with adjustable transparency.

    This tool is essential for tasks like image registration (checking alignment between two scans), segmentation validation (comparing a binary mask against the original raw data), or general change detection. It provides a slider to smoothly fade (blend) between the two volumes, allowing for precise visual inspection of differences and spatial correspondence slice-by-slice.

    Args:
        volume1 (np.ndarray): The first 3D volume (e.g., the reference image).
        volume2 (np.ndarray): The second 3D volume (e.g., the moving image or segmentation mask). Must have the same shape as `volume1`.
        volume1_values (tuple[float, float], optional): Intensity limits `(min, max)` for contrast stretching `volume1`. If `(None, None)`, uses the volume's min and max.
        volume2_values (tuple[float, float], optional): Intensity limits `(min, max)` for contrast stretching `volume2`.
        colormaps (str or matplotlib.colors.Colormap or tuple, optional): The colormap(s) to apply. Can be a single value (applied to both) or a tuple `(cmap1, cmap2)`. Defaults to 'gray'.
        display_size (int, optional): The maximum width/height of the displayed image in pixels. Defaults to 512.

    Returns:
        widget (widgets.VBox):
            The interactive widget containing the slicer controls and the fading overlay display.

    Example:
        ```python
        import qim3d

        vol = qim3d.examples.cement_128x128x128
        binary = qim3d.filters.gaussian(vol, sigma=2) < 60
        labeled_volume, num_labels = qim3d.segmentation.watershed(binary)

        segm_cmap = qim3d.viz.colormaps.segmentation(num_labels, style = 'bright')

        qim3d.viz.overlay(vol, labeled_volume, colormaps=('grey', segm_cmap), volume2_values=(0, num_labels))
        ```
        ![viz overlay](../../assets/screenshots/viz-overlay.gif)

    """
    if volume1.ndim != 3:
        msg = 'Volume must be 3D.'
        raise ValueError(msg)
    if volume1.shape != volume2.shape:
        msg = 'Volumes must have the same shape.'
        raise ValueError(msg)

    interactive_widget = OverlaySlicer(
        vol1=volume1,
        vol2=volume2,
        cmaps=colormaps,
        display_size=display_size,
        volume1_values=volume1_values,
        volume2_values=volume2_values,
    ).build_interactive()
    return interactive_widget

qim3d.viz.planes

planes(volume, colormap='magma', min_value=None, max_value=None)

Displays an interactive 3D scene with movable orthogonal cross-sections (X, Y, Z planes).

Creates a composite 3D viewer where three orthogonal slices intersect within the volume. Users can interactively drag sliders to explore the internal structure of the stack from different angles simultaneously. This visualization is often referred to as Multi-Planar Reconstruction (MPR) or an Orthogonal Slicer.

Key Features:

• 3D Context: Visualizes how the three planes (Axial, Coronal, Sagittal) intersect in 3D space.
• Interactive Controls: Includes sliders for position, opacity, and dynamic color range adjustment.
• High Performance: Uses Plotly and ipywidgets for responsive slicing of local data.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume.	required
colormap	str or Colormap	Matplotlib colormap name (e.g., 'magma', 'viridis').	'magma'
min_value	float	Minimum value for color scaling (lower bound of contrast).	None
max_value	float	Maximum value for color scaling (upper bound of contrast).	None

Example

import qim3d

# Load sample data
vol = qim3d.examples.shell_225x128x128

# Launch the interactive 3D plane viewer
qim3d.viz.planes(vol, colormap='plasma')

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def planes(
    volume: np.ndarray,
    colormap: str | matplotlib.colors.Colormap = 'magma',
    min_value: float = None,
    max_value: float = None,
) -> None:
    """
    Displays an interactive 3D scene with movable orthogonal cross-sections (X, Y, Z planes).

    Creates a composite 3D viewer where three orthogonal slices intersect within the volume.
    Users can interactively drag sliders to explore the internal structure of the stack from different angles simultaneously.
    This visualization is often referred to as Multi-Planar Reconstruction (MPR) or an Orthogonal Slicer.

    **Key Features:**

    * **3D Context:** Visualizes how the three planes (Axial, Coronal, Sagittal) intersect in 3D space.
    * **Interactive Controls:** Includes sliders for position, opacity, and dynamic color range adjustment.
    * **High Performance:** Uses `Plotly` and `ipywidgets` for responsive slicing of local data.

    Args:
        volume (numpy.ndarray): The 3D input volume.
        colormap (str or matplotlib.colors.Colormap, optional): Matplotlib colormap name (e.g., 'magma', 'viridis').
        min_value (float, optional): Minimum value for color scaling (lower bound of contrast).
        max_value (float, optional): Maximum value for color scaling (upper bound of contrast).

    Example:
        ```python
        import qim3d

        # Load sample data
        vol = qim3d.examples.shell_225x128x128

        # Launch the interactive 3D plane viewer
        qim3d.viz.planes(vol, colormap='plasma')
        ```
        ![viz planes](../../assets/screenshots/viz-planes.gif)

    """
    VolumePlaneSlicer(
        volume=volume, colormap=colormap, color_range=[min_value, max_value]
    ).show()

qim3d.viz.plot_connected_components

plot_connected_components(connected_components, component_indexs=None, max_cc_to_plot=32, overlay=None, crop=False, display_figure=True, colormap='viridis', min_value=None, max_value=None, **kwargs)

Plots the connected components from a qim3d.processing.cc.CC object. If an overlay image is provided, the connected component will be masked to the overlay image.

Parameters:

Name	Type	Description	Default
connected_components	CC	The connected components object.	required
component_indexs	list or tuple	The components to plot. If None the first max_cc_to_plot=32 components will be plotted. Defaults to None.	None
max_cc_to_plot	int	The maximum number of connected components to plot. Defaults to 32.	32
overlay	ndarray or None	Overlay image. Defaults to None.	None
crop	bool	Whether to crop the image to the cc. Defaults to False.	False
display_figure	bool	Whether to show the figure. Defaults to True.	True
colormap	str	Specifies the color map for the image. Defaults to "viridis".	'viridis'
min_value	float or None	Together with vmax define the data range the colormap covers. By default colormap covers the full range. Defaults to None.	None
max_value	float or None	Together with vmin define the data range the colormap covers. By default colormap covers the full range. Defaults to None	None
**kwargs	Any	Additional keyword arguments to pass to qim3d.viz.slices_grid.	{}

Returns:

Name	Type	Description
figs	list[Figure]	List of figures, if display_figure=False.

Example

import qim3d

vol = qim3d.examples.cement_128x128x128[50:150]
vol_bin = vol < 80
cc = qim3d.segmentation.get_3d_cc(vol_bin)

qim3d.viz.plot_cc(cc, crop=True, display_figure=True, overlay=None, num_slices=5, component_indexs=[4,6,7])
qim3d.viz.plot_cc(cc, crop=True, display_figure=True, overlay=vol, num_slices=5, component_indexs=[4,6,7])

Source code in qim3d/viz/_connected_components.py

def plot_connected_components(
    connected_components: ConnectedComponents,
    component_indexs: list | tuple = None,
    max_cc_to_plot: int = 32,
    overlay: np.ndarray = None,
    crop: bool = False,
    display_figure: bool = True,
    colormap: str = 'viridis',
    min_value: float = None,
    max_value: float = None,
    **kwargs,
) -> list[plt.Figure]:
    """
    Plots the connected components from a `qim3d.processing.cc.CC` object. If an overlay image is provided, the connected component will be masked to the overlay image.

    Args:
        connected_components (CC): The connected components object.
        component_indexs (list or tuple, optional): The components to plot. If None the first max_cc_to_plot=32 components will be plotted. Defaults to None.
        max_cc_to_plot (int, optional): The maximum number of connected components to plot. Defaults to 32.
        overlay (np.ndarray or None, optional): Overlay image. Defaults to None.
        crop (bool, optional): Whether to crop the image to the cc. Defaults to False.
        display_figure (bool, optional): Whether to show the figure. Defaults to True.
        colormap (str, optional): Specifies the color map for the image. Defaults to "viridis".
        min_value (float or None, optional): Together with vmax define the data range the colormap covers. By default colormap covers the full range. Defaults to None.
        max_value (float or None, optional): Together with vmin define the data range the colormap covers. By default colormap covers the full range. Defaults to None
        **kwargs (Any): Additional keyword arguments to pass to `qim3d.viz.slices_grid`.

    Returns:
        figs (list[plt.Figure]): List of figures, if `display_figure=False`.

    Example:
        ```python
        import qim3d

        vol = qim3d.examples.cement_128x128x128[50:150]
        vol_bin = vol < 80
        cc = qim3d.segmentation.get_3d_cc(vol_bin)

        qim3d.viz.plot_cc(cc, crop=True, display_figure=True, overlay=None, num_slices=5, component_indexs=[4,6,7])
        qim3d.viz.plot_cc(cc, crop=True, display_figure=True, overlay=vol, num_slices=5, component_indexs=[4,6,7])
        ```
        ![plot_cc_no_overlay](../../assets/screenshots/plot_cc_no_overlay.png)
        ![plot_cc_overlay](../../assets/screenshots/plot_cc_overlay.png)

    """
    # if no components are given, plot the first max_cc_to_plot=32 components
    if component_indexs is None:
        if len(connected_components) > max_cc_to_plot:
            log.warning(
                f'More than {max_cc_to_plot} connected components found. Only the first {max_cc_to_plot} will be plotted. Change max_cc_to_plot to plot more components.'
            )
        component_indexs = range(
            1, min(max_cc_to_plot + 1, len(connected_components) + 1)
        )

    figs = []
    for component in component_indexs:
        if overlay is not None:
            assert (
                overlay.shape == connected_components.shape
            ), f'Overlay image must have the same shape as the connected components. overlay.shape=={overlay.shape} != connected_components.shape={connected_components.shape}.'

            # plots overlay masked to connected component
            if crop:
                # Crop the overlay image based on the bounding box of the component
                bb = connected_components.get_bounding_box(component)[0]
                cc = connected_components.get_cc(component, crop=True)
                overlay_crop = overlay[bb]
                # use cc as mask for overlay_crop, where all values in cc set to 0 should be masked out, cc contains integers
                overlay_crop = np.where(cc == 0, 0, overlay_crop)
            else:
                cc = connected_components.get_cc(component, crop=False)
                overlay_crop = np.where(cc == 0, 0, overlay)
            fig = qim3d.viz.slices_grid(
                overlay_crop,
                display_figure=display_figure,
                colormap=colormap,
                min_value=min_value,
                max_value=max_value,
                **kwargs,
            )
        else:
            # assigns discrete color map to each connected component if not given
            if 'colormap' not in kwargs:
                kwargs['colormap'] = qim3d.viz.colormaps.segmentation(
                    len(component_indexs)
                )

            # Plot the connected component without overlay
            fig = qim3d.viz.slices_grid(
                connected_components.get_cc(component, crop=crop),
                display_figure=display_figure,
                **kwargs,
            )

        figs.append(fig)

    if not display_figure:
        return figs

    return

qim3d.viz.plot_metrics

plot_metrics(*metrics, linestyle='-', batch_linestyle='dotted', labels=None, figsize=(16, 6), show=False)

Plots the metrics over epochs and batches.

Parameters:

Name	Type	Description	Default
*metrics	tuple[dict[str, float]]	Variable-length argument list of dictionary containing the metrics per epochs and per batches.	()
linestyle	str	The style of the epoch metric line. Defaults to '-'.	'-'
batch_linestyle	str	The style of the batch metric line. Defaults to 'dotted'.	'dotted'
labels	list[str]	Labels for the plotted lines. Defaults to None.	None
figsize	Tuple[int, int]	Figure size (width, height) in inches. Defaults to (16, 6).	(16, 6)
show	bool	If True, displays the plot. Defaults to False.	False

Returns:

Name	Type	Description
fig	Figure	plot with metrics.

Example

train_loss = {'epoch_loss' : [...], 'batch_loss': [...]} val_loss = {'epoch_loss' : [...], 'batch_loss': [...]} plot_metrics(train_loss,val_loss, labels=['Train','Valid.'])

Source code in qim3d/viz/_metrics.py

def plot_metrics(
    *metrics: tuple[dict[str, float]],
    linestyle: str = '-',
    batch_linestyle: str = 'dotted',
    labels: list | None = None,
    figsize: tuple = (16, 6),
    show: bool = False,
):
    """
    Plots the metrics over epochs and batches.

    Args:
        *metrics: Variable-length argument list of dictionary containing the metrics per epochs and per batches.
        linestyle (str, optional): The style of the epoch metric line. Defaults to '-'.
        batch_linestyle (str, optional): The style of the batch metric line. Defaults to 'dotted'.
        labels (list[str], optional): Labels for the plotted lines. Defaults to None.
        figsize (Tuple[int, int], optional): Figure size (width, height) in inches. Defaults to (16, 6).
        show (bool, optional): If True, displays the plot. Defaults to False.

    Returns:
        fig (matplotlib.figure.Figure): plot with metrics.

    Example:
        train_loss = {'epoch_loss' : [...], 'batch_loss': [...]}
        val_loss = {'epoch_loss' : [...], 'batch_loss': [...]}
        plot_metrics(train_loss,val_loss, labels=['Train','Valid.'])

    """
    import seaborn as snb

    if labels == None:
        labels = [None] * len(metrics)
    elif len(metrics) != len(labels):
        raise ValueError("The number of metrics doesn't match the number of labels.")

    # plotting parameters
    snb.set_style('darkgrid')
    snb.set(font_scale=1.5)
    plt.rcParams['lines.linewidth'] = 2

    fig = plt.figure(figsize=figsize)

    palette = snb.color_palette(None, len(metrics))

    for i, metric in enumerate(metrics):
        metric_name = list(metric.keys())[0]
        epoch_metric = metric[list(metric.keys())[0]]
        batch_metric = metric[list(metric.keys())[1]]

        x_axis = np.linspace(0, len(epoch_metric) - 1, len(batch_metric))

        plt.plot(epoch_metric, linestyle=linestyle, color=palette[i], label=labels[i])
        plt.plot(
            x_axis, batch_metric, linestyle=batch_linestyle, color=palette[i], alpha=0.4
        )

    if labels[0] != None:
        plt.legend()

    plt.ylabel(metric_name)
    plt.xlabel('epoch')

    # reset plotting parameters
    snb.set_style('white')

    if show:
        plt.show()
    plt.close()

    return fig

qim3d.viz.slicer

slicer(volume, slice_axis=0, colormap='magma', min_value=None, max_value=None, image_height=3, image_width=3, display_positions=False, interpolation=None, image_size=None, colorbar=None, mask=None, mask_alpha=0.4, mask_colormap='gray', default_position=0.5, row_range=None, col_range=None, **matplotlib_imshow_kwargs)

Interactive tool to visualize, inspect, and scroll through 2D slices of a 3D volume.

Generates a GUI with a slider to navigate through the dataset along a specified axis. This function is essential for quality control, verifying segmentation masks, or exploring orthogonal views (axial, coronal, sagittal) of a stack.

Key Features:

• Scrollable Interface: Automatically generates a slider for the chosen axis.
• ROI Zoom: Crop the in-plane view interactively with the row and column range sliders (or seed an initial crop via row_range / col_range).
• Overlay Support: Visualize segmentation results on top of raw data using the mask parameter. Masks are currently not supported for Dask-backed volumes.
• Dynamic Contrast: Use colorbar='slices' to adapt intensity ranges per slice, or 'volume' for a global fixed range.
• Dask Support: For Dask arrays, only the selected slice is computed during interaction.

Parameters:

Name	Type	Description	Default
volume	ndarray or Array	The 3D input data to be sliced.	required
slice_axis	int	The axis to slice along (e.g., 0 for Z, 1 for Y, 2 for X).	0
colormap	str or LinearSegmentedColormap	Matplotlib colormap name for the volume.	'magma'
min_value	float	Minimum value for color scaling. If None, inferred from data. When colorbar='volume', this overrides the global volume minimum.	None
max_value	float	Maximum value for color scaling. If None, inferred from data. When colorbar='volume', this overrides the global volume maximum.	None
image_height	int	Height of the displayed figure.	3
image_width	int	Width of the displayed figure.	3
display_positions	bool	If True, displays the slice index/position on the image.	False
interpolation	str	Matplotlib interpolation method (e.g., 'nearest', 'bilinear').	None
image_size	int	Overrides both image_height and image_width to create a square figure.	None
colorbar	str	Strategy for the color bar range. 'volume': Constant range based on the global min/max of the volume. 'slices': Dynamic range calculated per individual slice. None: No color bar is displayed.	None
mask	ndarray	A 3D segmentation mask to overlay on the volume. Masks are currently not supported when volume is a Dask array.	None
mask_alpha	float	Opacity of the mask overlay (0.0 to 1.0).	0.4
mask_colormap	str	Matplotlib colormap name for the mask.	'gray'
default_position	float or int	Initial slice position of the slider. float: Relative position between 0.0 and 1.0 (e.g., 0.5 starts at the center). int: Exact slice index. Negative values follow standard Python indexing.	0.5
row_range	tuple[int, int]	Initial (start, stop) crop of the in-plane vertical (row) extent. If None, the full extent is shown. Sets the starting value of the row range slider; the crop can be adjusted interactively afterward. Contrast is still computed over the full slice, not the cropped region.	None
col_range	tuple[int, int]	Initial (start, stop) crop of the in-plane horizontal (column) extent. If None, the full extent is shown. Sets the starting value of the column range slider.	None
**matplotlib_imshow_kwargs		Additional keyword arguments passed to matplotlib.pyplot.imshow.	{}

Returns:

Name	Type	Description
slicer_obj	interactive	The interactive widget object containing the figure and the slice, row range, and column range sliders.

Example:

    import qim3d

    # Load sample data
    vol = qim3d.examples.bone_128x128x128

    # Visualize with a slider
    qim3d.viz.slicer(vol, colormap='bone')

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def slicer(
    volume: np.ndarray,
    slice_axis: int = 0,
    colormap: str = 'magma',
    min_value: float = None,
    max_value: float = None,
    image_height: int = 3,
    image_width: int = 3,
    display_positions: bool = False,
    interpolation: str | None = None,
    image_size: int = None,
    colorbar: str = None,
    mask: np.ndarray = None,
    mask_alpha: float = 0.4,
    mask_colormap: str = 'gray',
    default_position: float = 0.5,
    row_range: tuple[int, int] | None = None,
    col_range: tuple[int, int] | None = None,
    **matplotlib_imshow_kwargs,
) -> widgets.interactive:
    """
    Interactive tool to visualize, inspect, and scroll through 2D slices of a 3D volume.

    Generates a GUI with a slider to navigate through the dataset along a specified axis.
    This function is essential for quality control, verifying segmentation masks,
    or exploring orthogonal views (axial, coronal, sagittal) of a stack.

    **Key Features:**

    * **Scrollable Interface:** Automatically generates a slider for the chosen axis.
    * **ROI Zoom:** Crop the in-plane view interactively with the row and column range sliders
        (or seed an initial crop via `row_range` / `col_range`).
    * **Overlay Support:** Visualize segmentation results on top of raw data using the `mask` parameter.
        Masks are currently not supported for Dask-backed volumes.
    * **Dynamic Contrast:** Use `colorbar='slices'` to adapt intensity ranges per slice, or `'volume'` for a global fixed range.
    * **Dask Support:** For Dask arrays, only the selected slice is computed during interaction.

    Args:
        volume (numpy.ndarray or dask.array.Array): The 3D input data to be sliced.
        slice_axis (int, optional): The axis to slice along (e.g., 0 for Z, 1 for Y, 2 for X).
        colormap (str or matplotlib.colors.LinearSegmentedColormap, optional): Matplotlib colormap name for the volume.
        min_value (float, optional): Minimum value for color scaling. If `None`, inferred from data.
            When `colorbar='volume'`, this overrides the global volume minimum.
        max_value (float, optional): Maximum value for color scaling. If `None`, inferred from data.
            When `colorbar='volume'`, this overrides the global volume maximum.
        image_height (int, optional): Height of the displayed figure.
        image_width (int, optional): Width of the displayed figure.
        display_positions (bool, optional): If `True`, displays the slice index/position on the image.
        interpolation (str, optional): Matplotlib interpolation method (e.g., 'nearest', 'bilinear').
        image_size (int, optional): Overrides both `image_height` and `image_width` to create a square figure.
        colorbar (str, optional): Strategy for the color bar range.

            * `'volume'`: Constant range based on the global min/max of the volume.
            * `'slices'`: Dynamic range calculated per individual slice.
            * `None`: No color bar is displayed.

        mask (numpy.ndarray, optional): A 3D segmentation mask to overlay on the volume.
            Masks are currently not supported when `volume` is a Dask array.
        mask_alpha (float, optional): Opacity of the mask overlay (0.0 to 1.0).
        mask_colormap (str, optional): Matplotlib colormap name for the mask.
        default_position (float or int, optional): Initial slice position of the slider.

            * **float**: Relative position between 0.0 and 1.0 (e.g., `0.5` starts at the center).
            * **int**: Exact slice index. Negative values follow standard Python indexing.

        row_range (tuple[int, int], optional): Initial `(start, stop)` crop of the in-plane vertical
            (row) extent. If `None`, the full extent is shown. Sets the starting value of the row
            range slider; the crop can be adjusted interactively afterward. Contrast is still computed
            over the full slice, not the cropped region.
        col_range (tuple[int, int], optional): Initial `(start, stop)` crop of the in-plane horizontal
            (column) extent. If `None`, the full extent is shown. Sets the starting value of the column
            range slider.
        **matplotlib_imshow_kwargs: Additional keyword arguments passed to `matplotlib.pyplot.imshow`.

    Returns:
        slicer_obj (ipywidgets.interactive):
            The interactive widget object containing the figure and the slice, row range, and column range sliders.

    Example:
    ```python
        import qim3d

        # Load sample data
        vol = qim3d.examples.bone_128x128x128

        # Visualize with a slider
        qim3d.viz.slicer(vol, colormap='bone')
    ```
        ![viz slicer](../../assets/screenshots/viz-slicer.gif)

    """
    is_dask = isinstance(volume, da.Array)
    continuous_update = not is_dask

    msg = 'The mask parameter is not currently supported for Dask-backed volumes.'

    if is_dask and mask is not None:
        raise NotImplementedError(msg)

    if image_size:
        image_height = image_size
        image_width = image_size

    colorbar_options = [None, 'slices', 'volume']
    if colorbar not in colorbar_options:
        msg = (
            f"Unrecognized value '{colorbar}' for parameter colorbar. "
            f'Expected one of {colorbar_options}.'
        )
        raise ValueError(msg)
    show_colorbar = colorbar is not None
    if colorbar == 'slices' and not is_dask:
        # Precompute the minimum and maximum along each slice for faster widget sliding.
        non_slice_axes = tuple(i for i in range(volume.ndim) if i != slice_axis)
        slice_mins = np.min(volume, axis=non_slice_axes)
        slice_maxs = np.max(volume, axis=non_slice_axes)
    elif colorbar == 'volume':
        get_min = lambda: volume.min().compute() if is_dask else np.min(volume)
        get_max = lambda: volume.max().compute() if is_dask else np.max(volume)

        if min_value is None and max_value is None and is_dask:
            vol_min, vol_max = da.compute(volume.min(), volume.max())
        else:
            vol_min = get_min() if min_value is None else min_value
            vol_max = get_max() if max_value is None else max_value

    # Create the interactive widget
    def _slicer(
        slice_positions: int, row_range: tuple[int, int], col_range: tuple[int, int]
    ) -> Figure:
        lo, hi = row_range
        row_range = (n_rows - hi, n_rows - lo)

        if colorbar == 'slices' and not is_dask:
            dynamic_min = slice_mins[slice_positions]
            dynamic_max = slice_maxs[slice_positions]
        elif colorbar == 'volume':
            dynamic_min = vol_min
            dynamic_max = vol_max
        else:
            dynamic_min = min_value
            dynamic_max = max_value

        if is_dask:
            slicer_index = [slice(None)] * volume.ndim
            slicer_index[slice_axis] = slice_positions

            volume_input = volume[tuple(slicer_index)].compute()
            volume_input = np.expand_dims(volume_input, axis=slice_axis)

            slice_positions_input = 0
        else:
            volume_input = volume
            slice_positions_input = slice_positions

        fig = slices_grid(
            volume_input,
            slice_axis=slice_axis,
            colormap=colormap,
            min_value=dynamic_min,
            max_value=dynamic_max,
            image_height=image_height,
            image_width=image_width,
            display_positions=display_positions,
            interpolation=interpolation,
            slice_positions=slice_positions_input,
            n_slices=1,
            display_figure=True,
            colorbar=show_colorbar,
            mask=mask,
            mask_alpha=mask_alpha,
            mask_colormap=mask_colormap,
            row_range=row_range,
            col_range=col_range,
            **matplotlib_imshow_kwargs,
        )
        return fig

    if isinstance(default_position, float):
        default_position = int(default_position * (volume.shape[slice_axis] - 1))
    if isinstance(default_position, int):
        if default_position < 0:
            default_position = volume.shape[slice_axis] + default_position
        default_position = np.clip(
            default_position, a_min=0, a_max=volume.shape[slice_axis] - 1
        )
    else:
        default_position = volume.shape[slice_axis] // 2

    n_rows, n_cols = np.delete(volume.shape, slice_axis)
    if row_range is None:
        row_range = (0, n_rows)
    if col_range is None:
        col_range = (0, n_cols)

    row_slider = widgets.IntRangeSlider(
        value=row_range,
        min=0,
        max=n_rows,
        step=1,
        description='Row range',
        continuous_update=continuous_update,
    )

    col_slider = widgets.IntRangeSlider(
        value=col_range,
        min=0,
        max=n_cols,
        step=1,
        description='Column range',
        style={'description_width': 'initial'},
        continuous_update=continuous_update,
    )

    position_slider = widgets.IntSlider(
        value=default_position,
        min=0,
        max=volume.shape[slice_axis] - 1,
        description='Slice',
        continuous_update=continuous_update,
    )
    slicer_obj = widgets.interactive(
        _slicer,
        slice_positions=position_slider,
        row_range=row_slider,
        col_range=col_slider,
    )

    row_slider.orientation = 'vertical'
    out = slicer_obj.children[-1]

    image_row = widgets.HBox(
        [row_slider, out],
        layout=widgets.Layout(
            align_items='center',
            justify_content='center',
        ),
    )
    slicer_obj.children = (position_slider, image_row, col_slider)
    slicer_obj.layout = widgets.Layout(align_items='center')

    return slicer_obj

qim3d.viz.slicer_orthogonal

slicer_orthogonal(volume, colormap='magma', min_value=None, max_value=None, image_height=3, image_width=3, display_positions=False, interpolation=None, image_size=None, colorbar=None, mask=None, mask_alpha=0.4, mask_colormap='gray', default_z=0.5, default_y=0.5, default_x=0.5)

Interactive tool to visualize three orthogonal views (Z, Y, X) side-by-side.

Creates a composite widget displaying Axial, Coronal, and Sagittal slices simultaneously.
This is often called a Multi-Planar Reconstruction (MPR) view. It allows users to verify isotropy,
check feature continuity across dimensions, or inspect segmentation masks in all three orientations at once.

**Key Features:**

* **Simultaneous Views:** Generates three independent sliders for Z, Y, and X axes.
* **Independent ROI:** Each view has its own row/column range sliders for cropping.
* **Linked Settings:** Applies colormaps, contrast settings, and masks uniformly across all three views.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume.	required
colormap	str or LinearSegmentedColormap	Matplotlib colormap name.	'magma'
min_value	float	Minimum value for color scaling. If None, inferred from data.	None
max_value	float	Maximum value for color scaling. If None, inferred from data.	None
image_height	int	Height of each individual figure in inches.	3
image_width	int	Width of each individual figure in inches.	3
display_positions	bool	If True, displays the slice index on each image.	False
interpolation	str	Matplotlib interpolation method (e.g., 'nearest', 'bilinear').	None
image_size	int	Overrides image_height and image_width to make figures square.	None
colorbar	str	Strategy for the color bar range. 'volume': Constant range based on the global min/max of the volume. 'slices': Dynamic range calculated per individual slice. None: No color bar is displayed.	None
mask	ndarray	A 3D segmentation mask to overlay on all views.	None
mask_alpha	float	Opacity of the mask overlay (0.0 to 1.0).	0.4
mask_colormap	str	Matplotlib colormap name for the mask.	'gray'
default_z	float or int	Initial position for the Z-axis slider (0.0-1.0 relative or exact index).	0.5
default_y	float or int	Initial position for the Y-axis slider (0.0-1.0 relative or exact index).	0.5
default_x	float or int	Initial position for the X-axis slider (0.0-1.0 relative or exact index).	0.5

Returns:

Name	Type	Description
slicer_orthogonal_obj	HBox	A container widget holding the three interactive slicers arranged horizontally.

Example:

        import qim3d

        # Load sample data
        vol = qim3d.examples.fly_150x256x256

        # View all three axes side-by-side
        qim3d.viz.slicer_orthogonal(vol, colormap="magma")

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def slicer_orthogonal(
    volume: np.ndarray,
    colormap: str = 'magma',
    min_value: float = None,
    max_value: float = None,
    image_height: int = 3,
    image_width: int = 3,
    display_positions: bool = False,
    interpolation: str | None = None,
    image_size: int = None,
    colorbar: str = None,
    mask: np.ndarray = None,
    mask_alpha: float = 0.4,
    mask_colormap: str = 'gray',
    default_z: float = 0.5,
    default_y: float = 0.5,
    default_x: float = 0.5,
) -> widgets.interactive:
    """
        Interactive tool to visualize three orthogonal views (Z, Y, X) side-by-side.

        Creates a composite widget displaying Axial, Coronal, and Sagittal slices simultaneously.
        This is often called a Multi-Planar Reconstruction (MPR) view. It allows users to verify isotropy,
        check feature continuity across dimensions, or inspect segmentation masks in all three orientations at once.

        **Key Features:**

        * **Simultaneous Views:** Generates three independent sliders for Z, Y, and X axes.
        * **Independent ROI:** Each view has its own row/column range sliders for cropping.
        * **Linked Settings:** Applies colormaps, contrast settings, and masks uniformly across all three views.

    Args:
            volume (numpy.ndarray): The 3D input volume.
            colormap (str or matplotlib.colors.LinearSegmentedColormap, optional): Matplotlib colormap name.
            min_value (float, optional): Minimum value for color scaling. If `None`, inferred from data.
            max_value (float, optional): Maximum value for color scaling. If `None`, inferred from data.
            image_height (int, optional): Height of each individual figure in inches.
            image_width (int, optional): Width of each individual figure in inches.
            display_positions (bool, optional): If `True`, displays the slice index on each image.
            interpolation (str, optional): Matplotlib interpolation method (e.g., 'nearest', 'bilinear').
            image_size (int, optional): Overrides `image_height` and `image_width` to make figures square.
            colorbar (str, optional): Strategy for the color bar range.

                * `'volume'`: Constant range based on the global min/max of the volume.
                * `'slices'`: Dynamic range calculated per individual slice.
                * `None`: No color bar is displayed.

            mask (numpy.ndarray, optional): A 3D segmentation mask to overlay on all views.
            mask_alpha (float, optional): Opacity of the mask overlay (0.0 to 1.0).
            mask_colormap (str, optional): Matplotlib colormap name for the mask.
            default_z (float or int, optional): Initial position for the Z-axis slider (0.0-1.0 relative or exact index).
            default_y (float or int, optional): Initial position for the Y-axis slider (0.0-1.0 relative or exact index).
            default_x (float or int, optional): Initial position for the X-axis slider (0.0-1.0 relative or exact index).

    Returns:
            slicer_orthogonal_obj (ipywidgets.HBox):
                A container widget holding the three interactive slicers arranged horizontally.

    Example:
    ```python
            import qim3d

            # Load sample data
            vol = qim3d.examples.fly_150x256x256

            # View all three axes side-by-side
            qim3d.viz.slicer_orthogonal(vol, colormap="magma")
    ```
            ![viz slicer_orthogonal](../../assets/screenshots/viz-orthogonal.gif)

    """

    if image_size:
        image_height = image_size
        image_width = image_size

    def get_slicer_for_axis(
        slice_axis: int, default_position: float
    ) -> widgets.interactive:
        return slicer(
            volume,
            slice_axis=slice_axis,
            colormap=colormap,
            min_value=min_value,
            max_value=max_value,
            image_height=image_height,
            image_width=image_width,
            display_positions=display_positions,
            interpolation=interpolation,
            colorbar=colorbar,
            mask=mask,
            mask_alpha=mask_alpha,
            mask_colormap=mask_colormap,
            default_position=default_position,
        )

    panels = [
        get_slicer_for_axis(0, default_z),
        get_slicer_for_axis(1, default_y),
        get_slicer_for_axis(2, default_x),
    ]

    def _find(panel: widgets.Widget, desc: str) -> widgets.Widget | None:
        for c in getattr(panel, 'children', []):
            if getattr(c, 'description', '') == desc:
                return c
            hit = _find(c, desc)
            if hit is not None:
                return hit
        return None

    # Relabel each panel's position slider (locate by 'Slice' before renaming)
    for p, name in zip(panels, ['Z', 'Y', 'X']):
        _find(p, 'Slice').description = name

    return widgets.HBox(panels)

qim3d.viz.slices_grid

slices_grid(volume, slice_axis=0, slice_positions=None, n_slices=15, max_columns=5, colormap='magma', min_value=None, max_value=None, image_size=None, image_height=2, image_width=2, display_figure=False, display_positions=True, interpolation=None, colorbar=False, colorbar_style='small', mask=None, mask_alpha=0.4, mask_colormap='gray', row_range=None, col_range=None, **matplotlib_imshow_kwargs)

Creates a static grid visualization (montage) of multiple 2D slices from a 3D volume.

Generates a mosaic or gallery view of the dataset, ideal for reports, publications, or quick overviews. Unlike interactive tools, this function produces a static matplotlib figure that can be saved easily. It supports batch visualization of specific indices, relative positions (e.g., 'mid'), or automatically spaced intervals.

Key Features:

• Flexible Selection: Choose slices by specific index, relative strings ('start', 'mid', 'end'), or automatic linear spacing.
• Publication Ready: Control layout (max_columns), sizing, and colorbars for export-ready figures.
• Mask Overlays: Superimpose segmentation masks directly onto the slice grid.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume to be sliced.	required
slice_axis	int	The axis to slice along (e.g., 0 for Z, 1 for Y, 2 for X).	0
slice_positions	int, list[int], str, or None	Determines which slices to display. None: Displays n_slices linearly spaced across the volume. list[int]: Displays exactly the slices at these indices (n_slices is ignored). int: Displays n_slices centered around this specific index. str: Displays n_slices around a relative position ('start', 'mid', 'end').	None
n_slices	int	The number of slices to display. Ignored if slice_positions is a list.	15
max_columns	int	The maximum number of columns in the grid layout.	5
colormap	str or LinearSegmentedColormap	Matplotlib colormap name.	'magma'
min_value	float	Minimum value for color scaling. If None, inferred from data.	None
max_value	float	Maximum value for color scaling. If None, inferred from data.	None
image_size	int	Overrides both image_height and image_width to create square subplots.	None
image_height	int	Height of each subplot in inches.	2
image_width	int	Width of each subplot in inches.	2
display_figure	bool	If True, calls plt.show() immediately.	False
display_positions	bool	If True, adds text labels indicating slice index and axis.	True
interpolation	str	Matplotlib interpolation method (e.g., 'nearest', 'bilinear').	None
colorbar	bool	If True, adds a global colorbar to the figure.	False
colorbar_style	str	Visual style of the colorbar. 'small': Matches the height of a single image row. 'large': Spans the full height of the grid.	'small'
mask	ndarray	A 3D segmentation mask to overlay on the slices.	None
mask_alpha	float	Opacity of the mask overlay (0.0 to 1.0).	0.4
mask_colormap	str	Matplotlib colormap name for the mask.	'gray'
row_range	tuple[int, int]	Vertical cropping region (start, stop) for rows.	None
col_range	tuple[int, int]	Horizontal cropping region (start, stop) for columns.	None
**matplotlib_imshow_kwargs		Additional keyword arguments passed to matplotlib.pyplot.imshow.	{}

Returns:

Name	Type	Description
fig	Figure	The generated matplotlib figure object containing the grid of slices.

Raises:

Type	Description
ValueError	If volume is not 3D or if slice_axis is invalid.
ValueError	If slice_positions is an invalid string.
ValueError	If colorbar_style is not 'small' or 'large'.

Example

import qim3d

# Load sample data
vol = qim3d.examples.shell_225x128x128

# Create a grid of 15 linearly spaced slices
qim3d.viz.slices_grid(vol, n_slices=15)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def slices_grid(
    volume: np.ndarray,
    slice_axis: int = 0,
    slice_positions: str | int | list[int] | None = None,
    n_slices: int = 15,
    max_columns: int = 5,
    colormap: str = 'magma',
    min_value: float = None,
    max_value: float = None,
    image_size: int = None,
    image_height: int = 2,
    image_width: int = 2,
    display_figure: bool = False,
    display_positions: bool = True,
    interpolation: str | None = None,
    colorbar: bool = False,
    colorbar_style: str = 'small',
    mask: np.ndarray = None,
    mask_alpha: float = 0.4,
    mask_colormap: str = 'gray',
    row_range: tuple[int, int] | None = None,
    col_range: tuple[int, int] | None = None,
    **matplotlib_imshow_kwargs,
) -> matplotlib.figure.Figure:
    """
    Creates a static grid visualization (montage) of multiple 2D slices from a 3D volume.

    Generates a mosaic or gallery view of the dataset, ideal for reports, publications, or quick overviews.
    Unlike interactive tools, this function produces a static `matplotlib` figure that can be saved easily.
    It supports batch visualization of specific indices, relative positions (e.g., 'mid'), or automatically spaced intervals.

    **Key Features:**

    * **Flexible Selection:** Choose slices by specific index, relative strings ('start', 'mid', 'end'), or automatic linear spacing.
    * **Publication Ready:** Control layout (`max_columns`), sizing, and colorbars for export-ready figures.
    * **Mask Overlays:** Superimpose segmentation masks directly onto the slice grid.

    Args:
        volume (numpy.ndarray): The 3D input volume to be sliced.
        slice_axis (int, optional): The axis to slice along (e.g., 0 for Z, 1 for Y, 2 for X).
        slice_positions (int, list[int], str, or None, optional): Determines which slices to display.

            * **None**: Displays `n_slices` linearly spaced across the volume.
            * **list[int]**: Displays exactly the slices at these indices (`n_slices` is ignored).
            * **int**: Displays `n_slices` centered around this specific index.
            * **str**: Displays `n_slices` around a relative position ('start', 'mid', 'end').

        n_slices (int, optional): The number of slices to display. Ignored if `slice_positions` is a list.
        max_columns (int, optional): The maximum number of columns in the grid layout.
        colormap (str or matplotlib.colors.LinearSegmentedColormap, optional): Matplotlib colormap name.
        min_value (float, optional): Minimum value for color scaling. If `None`, inferred from data.
        max_value (float, optional): Maximum value for color scaling. If `None`, inferred from data.
        image_size (int, optional): Overrides both `image_height` and `image_width` to create square subplots.
        image_height (int, optional): Height of each subplot in inches.
        image_width (int, optional): Width of each subplot in inches.
        display_figure (bool, optional): If `True`, calls `plt.show()` immediately.
        display_positions (bool, optional): If `True`, adds text labels indicating slice index and axis.
        interpolation (str, optional): Matplotlib interpolation method (e.g., 'nearest', 'bilinear').
        colorbar (bool, optional): If `True`, adds a global colorbar to the figure.
        colorbar_style (str, optional): Visual style of the colorbar.

            * `'small'`: Matches the height of a single image row.
            * `'large'`: Spans the full height of the grid.

        mask (numpy.ndarray, optional): A 3D segmentation mask to overlay on the slices.
        mask_alpha (float, optional): Opacity of the mask overlay (0.0 to 1.0).
        mask_colormap (str, optional): Matplotlib colormap name for the mask.
        row_range (tuple[int, int], optional): Vertical cropping region (start, stop) for rows.
        col_range (tuple[int, int], optional): Horizontal cropping region (start, stop) for columns.
        **matplotlib_imshow_kwargs: Additional keyword arguments passed to `matplotlib.pyplot.imshow`.

    Returns:
        fig (matplotlib.figure.Figure):
            The generated matplotlib figure object containing the grid of slices.

    Raises:
        ValueError: If `volume` is not 3D or if `slice_axis` is invalid.
        ValueError: If `slice_positions` is an invalid string.
        ValueError: If `colorbar_style` is not 'small' or 'large'.

    Example:
        ```python
        import qim3d

        # Load sample data
        vol = qim3d.examples.shell_225x128x128

        # Create a grid of 15 linearly spaced slices
        qim3d.viz.slices_grid(vol, n_slices=15)
        ```
        ![Grid of slices](../../assets/screenshots/viz-slices.png)

    """
    if image_size:
        image_height = image_size
        image_width = image_size

    # If we pass python None to the imshow function, it will set to
    # default value 'antialiased'
    if interpolation is None:
        interpolation = 'none'

    # Numpy array or Torch tensor input
    if not isinstance(volume, np.ndarray | da.Array):
        msg = 'Data type not supported'
        raise ValueError(msg)

    if volume.ndim < 3:
        msg = 'The provided object is not a volume as it has less than 3 dimensions.'
        raise ValueError(msg)

    colorbar_style_options = ['small', 'large']
    if colorbar_style not in colorbar_style_options:
        msg = f"Value '{colorbar_style}' is not valid for colorbar style. Please select from {colorbar_style_options}."
        raise ValueError(msg)

    if isinstance(volume, da.Array):
        volume = volume.compute()

    # Ensure axis is a valid choice
    if not (0 <= slice_axis < volume.ndim):
        msg = f"Invalid value for 'slice_axis'. It should be an integer between 0 and {volume.ndim - 1}."
        raise ValueError(msg)

    # Here we deal with the case that the user wants to use the objects colormap directly
    if (
        isinstance(colormap, matplotlib.colors.LinearSegmentedColormap)
        or colormap == 'segmentation'
    ):
        num_labels = int(volume.max())

        if colormap == 'segmentation':
            colormap = qim3d.viz.colormaps.segmentation(num_labels)
        # If min_value and max_value are not set like this, then in case the
        # number of objects changes on new slice, objects might change
        # colors. So when using a slider, the same object suddently
        # changes color (flickers), which is confusing and annoying.
        min_value = 0
        max_value = num_labels

    # Get total number of slices in the specified dimension
    n_total = volume.shape[slice_axis]

    # Position is not provided - will use linearly spaced slices
    if slice_positions is None:
        slice_idxs = np.linspace(0, n_total - 1, n_slices, dtype=int)
    # Position is a string
    elif isinstance(slice_positions, str) and slice_positions.lower() in [
        'start',
        'mid',
        'end',
    ]:
        if slice_positions.lower() == 'start':
            slice_idxs = _get_slice_range(0, n_slices, n_total)
        elif slice_positions.lower() == 'mid':
            slice_idxs = _get_slice_range(n_total // 2, n_slices, n_total)
        elif slice_positions.lower() == 'end':
            slice_idxs = _get_slice_range(n_total - 1, n_slices, n_total)
    #  Position is an integer
    elif isinstance(slice_positions, int):
        slice_idxs = _get_slice_range(slice_positions, n_slices, n_total)
    # Position is a list of integers
    elif isinstance(slice_positions, list) and all(
        isinstance(x, int) for x in slice_positions
    ):
        slice_idxs = np.array(slice_positions)
        if any(slice_idxs < 0):
            dim = volume.shape[slice_axis]
            slice_idxs[np.where(slice_idxs < 0)] += dim
        n_slices = len(slice_idxs)

    else:
        msg = 'Position not recognized. Choose an integer, list of integers or one of the following strings: "start", "mid" or "end".'
        raise ValueError(msg)

    # Make grid
    nrows = math.ceil(n_slices / max_columns)
    ncols = min(n_slices, max_columns)

    # Generate figure
    fig, axs = plt.subplots(
        nrows=nrows,
        ncols=ncols,
        figsize=(ncols * image_height, nrows * image_width),
        constrained_layout=True,
    )

    if nrows == 1:
        axs = [axs]  # Convert to a list for uniformity

    # Convert to NumPy array in order to use the numpy.take method
    if isinstance(volume, da.Array):
        volume = volume.compute()

    if colorbar:
        # In this case, we want the vrange to be constant across the
        # slices, which makes them all comparable to a single colorbar.
        new_min_value = min_value if min_value is not None else np.min(volume)
        new_max_value = max_value if max_value is not None else np.max(volume)

    # Run through each ax of the grid
    for i, ax_row in enumerate(axs):
        for j, ax in enumerate(np.atleast_1d(ax_row)):
            slice_idx = i * max_columns + j
            try:
                slice_img = volume.take(slice_idxs[slice_idx], axis=slice_axis)
                slice_mask = (
                    None
                    if mask is None
                    else mask.take(slice_idxs[slice_idx], axis=slice_axis)
                )

                row_slice = _range_to_slice(row_range)
                col_slice = _range_to_slice(col_range)
                slice_img = slice_img[row_slice, col_slice]

                if slice_mask is not None:
                    slice_mask = slice_mask[row_slice, col_slice]

                if not colorbar:
                    # If min_value is higher than the highest value in the
                    # image ValueError is raised. We don't want to
                    # override the values because next slices might be okay
                    new_min_value = (
                        None
                        if (
                            isinstance(min_value, float | int)
                            and min_value > np.max(slice_img)
                        )
                        else min_value
                    )
                    new_max_value = (
                        None
                        if (
                            isinstance(max_value, float | int)
                            and max_value < np.min(slice_img)
                        )
                        else max_value
                    )

                ax.imshow(
                    slice_img,
                    cmap=colormap,
                    interpolation=interpolation,
                    vmin=new_min_value,
                    vmax=new_max_value,
                    **matplotlib_imshow_kwargs,
                )
                if slice_mask is not None:
                    ax.imshow(slice_mask, cmap=mask_colormap, alpha=mask_alpha)

                if display_positions:
                    ax.text(
                        0.0,
                        1.0,
                        f'slice {slice_idxs[slice_idx]} ',
                        transform=ax.transAxes,
                        color='white',
                        fontsize=8,
                        va='top',
                        ha='left',
                        bbox={'facecolor': '#303030', 'linewidth': 0, 'pad': 0},
                    )

                    ax.text(
                        1.0,
                        0.0,
                        f'axis {slice_axis} ',
                        transform=ax.transAxes,
                        color='white',
                        fontsize=8,
                        va='bottom',
                        ha='right',
                        bbox={'facecolor': '#303030', 'linewidth': 0, 'pad': 0},
                    )

            except IndexError:
                # Not a problem, because we simply do not have a slice to show
                pass

            # Hide the axis, so that we have a nice grid
            ax.axis('off')

    if colorbar:
        with warnings.catch_warnings():
            warnings.simplefilter('ignore', category=UserWarning)
            fig.tight_layout()

        norm = matplotlib.colors.Normalize(
            vmin=new_min_value, vmax=new_max_value, clip=True
        )
        mappable = matplotlib.cm.ScalarMappable(norm=norm, cmap=colormap)

        if colorbar_style == 'small':
            # Figure coordinates of top-right axis
            tr_pos = np.atleast_1d(axs[0])[-1].get_position()
            # The width is divided by ncols to make it the same relative size to the images
            colorbar_ax = fig.add_axes(
                [tr_pos.x1 + 0.05 / ncols, tr_pos.y0, 0.05 / ncols, tr_pos.height]
            )
            fig.colorbar(mappable=mappable, cax=colorbar_ax, orientation='vertical')
        elif colorbar_style == 'large':
            # Figure coordinates of bottom- and top-right axis
            br_pos = np.atleast_1d(axs[-1])[-1].get_position()
            tr_pos = np.atleast_1d(axs[0])[-1].get_position()
            # The width is divided by ncols to make it the same relative size to the images
            colorbar_ax = fig.add_axes(
                [
                    br_pos.xmax + 0.05 / ncols,
                    br_pos.y0 + 0.0015,
                    0.05 / ncols,
                    (tr_pos.y1 - br_pos.y0) - 0.0015,
                ]
            )
            fig.colorbar(mappable=mappable, cax=colorbar_ax, orientation='vertical')

    if display_figure:
        plt.show()

    plt.close()

    return fig

qim3d.viz.streamlines

streamlines(volume, eigenvectors, eigenvalues, background_threshold=None, fiber_spacing=20, initial_step_size=0.5, max_step_size=2.5, max_fiber_length=300, terminal_speed=1e-10, show_volume=False, show_starting_points=False, camera_position='iso')

Visualizes fiber orientations as 3D streamlines by tracing paths through the
eigenvector field of the structure tensor.

Starting from a uniform grid of seed points placed inside the foreground of the volume,
each fiber is traced in both directions by following the local eigenvector orientation.
Tracing stops when the fiber reaches the maximum allowed length or enters a region
where the vector magnitude drops below the terminal speed threshold, which happens
naturally in background regions and areas with low structural coherence.

Fibers are colored using the fan-based color scheme from Dahl 2026, designed for
planar fiber distributions. The in-plane azimuthal angle of the eigenvector is mapped
to hue via the HSV color wheel, while the out-of-plane component desaturates the color
toward gray. Fibers lying flat in the XY plane appear as fully saturated colors, while
fibers pointing out of plane appear gray. Sign ambiguity is resolved by using mod π
when computing the angle, so that v and -v always map to the same color.

For background on structure tensors, eigenvalues, and orientation analysis, see:
https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume with shape (Z, Y, X). Used for background detection and optional volume rendering.	required
eigenvectors	ndarray	Structure tensor eigenvectors with shape (3, 3, Z, Y, X) or (3, Z, Y, X). The first eigenvector, corresponding to the direction of minimum intensity change, is used as the fiber direction.	required
eigenvalues	ndarray	Structure tensor eigenvalues with shape (3, Z, Y, X). The smallest eigenvalue λ1 is used to scale the eigenvectors so that tracing stops naturally in noisy or incoherent regions.	required
background_threshold	float	Intensity value below which seed points are rejected as background. If not provided, it is computed automatically using Otsu thresholding. Set to 0 to use all non-zero regions. Defaults to None.	None
fiber_spacing	int	Distance in voxels between fiber seed points. Lower values produce denser fiber visualizations but increase computation time. Defaults to 20.	20
initial_step_size	float	Starting step length for fiber integration in voxels. Smaller values follow fiber paths more accurately but are slower. Defaults to 0.5.	0.5
max_step_size	float	Maximum allowed step length in voxels. Larger values produce smoother fibers but may skip fine details. Defaults to 2.5.	2.5
max_fiber_length	int	Maximum number of integration steps per fiber. Higher values allow longer fibers but increase computation time. Defaults to 300.	300
terminal_speed	float	Minimum vector magnitude below which fiber tracing stops. Since eigenvectors are scaled by the inverse of λ1, this threshold naturally stops fibers in background and incoherent regions. Lower values allow fibers to continue longer into uncertain areas. Defaults to 1e-10.	1e-10
show_volume	bool	If True, renders the original volume as a semi-transparent gray background behind the fibers for spatial context. Defaults to False.	False
show_starting_points	bool	If True, shows the fiber seed points as red spheres. Useful for understanding the seeding distribution. Defaults to False.	False
camera_position	str	Initial camera viewpoint for the 3D render. Options are 'iso' for isometric, 'xy', 'xz', or 'yz'. Defaults to 'iso'.	'iso'

Returns:

Name	Type	Description
None		Displays the visualization directly in a PyVista window.

Example:

python import qim3d val, vec = qim3d.processing.structure_tensor(volume, sigma=2.0, rho=6) qim3d.viz.streamlines(volume, vec, val) qim3d.viz.streamlines(volume, vec, val, fiber_spacing=8, initial_step_size=0.3) qim3d.viz.streamlines(volume, vec, val, fiber_spacing=25, show_volume=True) qim3d.viz.streamlines(volume, vec, val, max_fiber_length=600, show_starting_points=True)

Source code in qim3d/viz/_structure_tensor.py

def streamlines(
    volume,
    eigenvectors,
    eigenvalues,
    background_threshold=None,
    fiber_spacing=20,
    initial_step_size=0.5,
    max_step_size=2.5,
    max_fiber_length=300,
    terminal_speed=1e-10,
    show_volume=False,
    show_starting_points=False,
    camera_position='iso',
):
    """
        Visualizes fiber orientations as 3D streamlines by tracing paths through the
        eigenvector field of the structure tensor.

        Starting from a uniform grid of seed points placed inside the foreground of the volume,
        each fiber is traced in both directions by following the local eigenvector orientation.
        Tracing stops when the fiber reaches the maximum allowed length or enters a region
        where the vector magnitude drops below the terminal speed threshold, which happens
        naturally in background regions and areas with low structural coherence.

        Fibers are colored using the fan-based color scheme from Dahl 2026, designed for
        planar fiber distributions. The in-plane azimuthal angle of the eigenvector is mapped
        to hue via the HSV color wheel, while the out-of-plane component desaturates the color
        toward gray. Fibers lying flat in the XY plane appear as fully saturated colors, while
        fibers pointing out of plane appear gray. Sign ambiguity is resolved by using mod π
        when computing the angle, so that v and -v always map to the same color.

        For background on structure tensors, eigenvalues, and orientation analysis, see:
        https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

    Parameters:
            volume (np.ndarray): The 3D input volume with shape (Z, Y, X). Used for background
                detection and optional volume rendering.
            eigenvectors (np.ndarray): Structure tensor eigenvectors with shape (3, 3, Z, Y, X)
                or (3, Z, Y, X). The first eigenvector, corresponding to the direction of minimum
                intensity change, is used as the fiber direction.
            eigenvalues (np.ndarray): Structure tensor eigenvalues with shape (3, Z, Y, X).
                The smallest eigenvalue λ1 is used to scale the eigenvectors so that tracing
                stops naturally in noisy or incoherent regions.
            background_threshold (float, optional): Intensity value below which seed points are
                rejected as background. If not provided, it is computed automatically using
                Otsu thresholding. Set to 0 to use all non-zero regions. Defaults to None.
            fiber_spacing (int, optional): Distance in voxels between fiber seed points. Lower
                values produce denser fiber visualizations but increase computation time.
                Defaults to 20.
            initial_step_size (float, optional): Starting step length for fiber integration in
                voxels. Smaller values follow fiber paths more accurately but are slower.
                Defaults to 0.5.
            max_step_size (float, optional): Maximum allowed step length in voxels. Larger values
                produce smoother fibers but may skip fine details. Defaults to 2.5.
            max_fiber_length (int, optional): Maximum number of integration steps per fiber.
                Higher values allow longer fibers but increase computation time. Defaults to 300.
            terminal_speed (float, optional): Minimum vector magnitude below which fiber tracing
                stops. Since eigenvectors are scaled by the inverse of λ1, this threshold
                naturally stops fibers in background and incoherent regions. Lower values allow
                fibers to continue longer into uncertain areas. Defaults to 1e-10.
            show_volume (bool, optional): If True, renders the original volume as a semi-transparent
                gray background behind the fibers for spatial context. Defaults to False.
            show_starting_points (bool, optional): If True, shows the fiber seed points as red
                spheres. Useful for understanding the seeding distribution. Defaults to False.
            camera_position (str, optional): Initial camera viewpoint for the 3D render.
                Options are 'iso' for isometric, 'xy', 'xz', or 'yz'. Defaults to 'iso'.

    Returns:
            None: Displays the visualization directly in a PyVista window.

        Example:
    ```python
            import qim3d

            val, vec = qim3d.processing.structure_tensor(volume, sigma=2.0, rho=6)

            qim3d.viz.streamlines(volume, vec, val)

            qim3d.viz.streamlines(volume, vec, val, fiber_spacing=8, initial_step_size=0.3)

            qim3d.viz.streamlines(volume, vec, val, fiber_spacing=25, show_volume=True)

            qim3d.viz.streamlines(volume, vec, val, max_fiber_length=600, show_starting_points=True)
    ```

    """
    import numpy as np
    import pyvista as pv

    # Compute the background threshold automatically using Otsu thresholding if not provided
    if background_threshold is None:
        nonzero = volume[volume > 0]
        if len(nonzero) > 0:
            vmin, vmax = int(volume.min()), int(volume.max())
            hist, bin_edges = np.histogram(volume, bins=4096, range=(vmin, vmax))
            bin_centers = (bin_edges[:-1] + bin_edges[1:]) / 2
            w0 = np.cumsum(hist)
            w1 = hist.sum() - w0
            mu0 = np.cumsum(hist * bin_centers) / np.maximum(w0, 1)
            mu1 = (np.cumsum((hist * bin_centers)[::-1]) / np.maximum(w1[::-1], 1))[
                ::-1
            ]
            sigma_b2 = w0 * w1 * (mu0 - mu1) ** 2
            background_threshold = bin_centers[np.argmax(sigma_b2)] * 1.05
        else:
            background_threshold = 0

    print(f'Background threshold: {background_threshold:.2f}')

    # Use the first eigenvector which corresponds to the direction of minimum intensity
    # change, representing the dominant fiber orientation in structure tensor analysis
    if eigenvectors.ndim == 5:
        vec_fiber = eigenvectors[0].copy()
    else:
        vec_fiber = eigenvectors.copy()

    # Scale the eigenvectors by the inverse of the smallest eigenvalue λ1.
    # λ1 is small where the local structure is coherent and the fiber direction is reliable.
    # Inverting it produces large magnitudes in well-defined structural regions and small
    # magnitudes in noisy or background regions, causing fiber tracing to stop there naturally.
    epsilon = 1e-12
    l1 = eigenvalues[0]

    l1_valid = l1.ravel()[l1.ravel() > 0]
    inv_l1 = np.clip(1.0 / (l1 + epsilon), 0, 1.0 / epsilon)
    inv_l1_max = np.percentile(inv_l1[l1 > 0], 99) if len(l1_valid) > 0 else 1.0
    inv_l1_norm = np.clip(inv_l1 / (inv_l1_max + epsilon), 0, 1)

    # Explicitly zero out background voxels so fibers stop at the volume boundary
    inv_l1_norm[volume == 0] = 0

    vec_scaled = vec_fiber * inv_l1_norm[np.newaxis, ...]

    print(
        f'Inverse λ1 normalized range: {inv_l1_norm.min():.4f} to {inv_l1_norm.max():.4f}'
    )
    print(
        f'  Mean (foreground): {inv_l1_norm[volume > background_threshold].mean():.4f}'
    )

    # Set up the PyVista structured grid with the volume dimensions and unit spacing
    grid = pv.ImageData()
    grid.dimensions = (volume.shape[2], volume.shape[1], volume.shape[0])
    grid.origin = (0, 0, 0)
    grid.spacing = (1, 1, 1)

    # Reorder arrays from (Z, Y, X) to (X, Y, Z) as required by PyVista
    vectors_reordered = vec_scaled.transpose(3, 2, 1, 0)
    grid.point_data['vectors'] = vectors_reordered.reshape(-1, 3, order='F')

    intensity_reordered = volume.transpose(2, 1, 0)
    grid.point_data['intensity'] = intensity_reordered.flatten(order='F')

    # Compute the fan-based RGB color for each voxel following Dahl 2026, Fig. 6 col. 3:
    # (r, g, b) = (1 - vz²) · hsv2rgb(arctan(vy/vx), 1, 1) + 0.5·vz²
    # Hue encodes the in-plane azimuthal angle, vz² desaturates out-of-plane fibers toward gray
    vx = vec_fiber[0]
    vy = vec_fiber[1]
    vz = vec_fiber[2]

    # Use mod π to resolve sign ambiguity: arctan2(-vy, -vx) = arctan2(vy, vx) + π,
    # and mod π makes them equal, so v and -v always get the same hue
    hue = (np.arctan2(vy, vx) % np.pi) / np.pi
    h6 = hue * 6.0
    i = h6.astype(int) % 6
    f = h6 - np.floor(h6)

    # Vectorized HSV to RGB conversion with saturation=1 and value=1 (pure hue colors)
    hsv_r = np.select(
        [i == 0, i == 1, i == 2, i == 3, i == 4, i == 5], [1, 1 - f, 0, 0, f, 1]
    ).astype(np.float32)
    hsv_g = np.select(
        [i == 0, i == 1, i == 2, i == 3, i == 4, i == 5], [f, 1, 1, 1 - f, 0, 0]
    ).astype(np.float32)
    hsv_b = np.select(
        [i == 0, i == 1, i == 2, i == 3, i == 4, i == 5], [0, 0, f, 1, 1, 1 - f]
    ).astype(np.float32)

    vz2 = vz**2
    fan_r = (1 - vz2) * hsv_r + 0.5 * vz2
    fan_g = (1 - vz2) * hsv_g + 0.5 * vz2
    fan_b = (1 - vz2) * hsv_b + 0.5 * vz2

    fan_rgb = np.stack([fan_r, fan_g, fan_b], axis=-1)
    fan_rgb_reordered = fan_rgb.transpose(2, 1, 0, 3)
    fan_rgb_flat = (
        np.clip(fan_rgb_reordered, 0, 1).reshape(-1, 3, order='F') * 255
    ).astype(np.uint8)
    grid.point_data['fan_rgb'] = fan_rgb_flat

    # Place seed points on a uniform grid within the bounding box of the foreground
    threshold = (
        np.percentile(intensity_reordered[intensity_reordered > 0], 10)
        if (intensity_reordered > 0).any()
        else 0
    )
    nonzero_coords = np.argwhere(intensity_reordered > threshold)

    if len(nonzero_coords) == 0:
        print('WARNING: No foreground voxels found!')
        return

    x_min, y_min, z_min = nonzero_coords.min(axis=0)
    x_max, y_max, z_max = nonzero_coords.max(axis=0)

    x_seeds = np.arange(x_min, x_max, fiber_spacing)
    y_seeds = np.arange(y_min, y_max, fiber_spacing)
    z_seeds = np.arange(z_min, z_max, fiber_spacing)
    seed_grid = np.array(
        np.meshgrid(x_seeds, y_seeds, z_seeds, indexing='ij')
    ).T.reshape(-1, 3)

    # Keep only seed points where the volume intensity is above the background threshold
    seed_indices = seed_grid.astype(int)
    intensity_3d_grid = grid.point_data['intensity'].reshape(grid.dimensions, order='F')
    seed_intensities = intensity_3d_grid[
        seed_indices[:, 0], seed_indices[:, 1], seed_indices[:, 2]
    ]
    valid_seeds = seed_grid[seed_intensities > background_threshold]

    print(f'Seeds: {len(seed_grid)} → {len(valid_seeds)} after filtering')

    if len(valid_seeds) == 0:
        print('WARNING: No valid seeds after filtering!')
        return

    seed_points = pv.PolyData(valid_seeds)

    print('Generating streamlines...')
    print(f'  Max steps: {max_fiber_length}')
    print(f'  Step size: {initial_step_size} to {max_step_size}')

    streamlines_mesh = grid.streamlines_from_source(
        seed_points,
        vectors='vectors',
        max_steps=max_fiber_length,
        initial_step_length=initial_step_size,
        max_step_length=max_step_size,
        integration_direction='both',
        terminal_speed=terminal_speed,
        surface_streamlines=False,
        interpolator_type='cell',  # cell locator is more robust than point locator
        compute_vorticity=False,  # not needed for line visualization, saves computation
        progress_bar=True,
    )

    print(
        f'Generated {streamlines_mesh.n_lines} fibers with {streamlines_mesh.n_points} total points'
    )

    plotter = pv.Plotter()

    if show_volume:
        plotter.add_volume(
            grid,
            scalars='intensity',
            opacity='linear',
            cmap='gray',
            opacity_unit_distance=20,
        )

    plotter.add_mesh(
        streamlines_mesh,
        scalars='fan_rgb',
        rgb=True,
        line_width=2,
        render_lines_as_tubes=False,
        show_scalar_bar=False,
    )

    if show_starting_points:
        plotter.add_mesh(
            seed_points, color='red', point_size=8, render_points_as_spheres=True
        )

    plotter.camera_position = camera_position
    plotter.add_text(
        f'Fiber Visualization ({streamlines_mesh.n_lines} fibers)', font_size=12
    )
    plotter.show()

qim3d.viz.threshold

threshold(volume, colormap='magma', min_value=None, max_value=None)

Launches an interactive widget to perform 3D image segmentation via thresholding (binarization).

This tool allows you to explore the volume slice-by-slice to determine the optimal cut-off value for creating a binary mask. It is essential for separating objects of interest from the background based on intensity. The interface provides real-time feedback by displaying the intensity histogram and overlaying the resulting mask on the original data.

Key Features:

• Visualization: Simultaneously views the original slice, intensity histogram, binary mask, and a color overlay.
• Manual Control: Adjust the threshold value precisely using a slider.
• Automatic Algorithms: Applies standard skimage auto-thresholding methods including Otsu, Isodata, Li, Mean, Minimum, Triangle, and Yen.
• Slice Navigation: Scroll through the 3D stack to ensure the chosen threshold works across different depths.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input data (image stack) to threshold.	required
colormap	str	The Matplotlib colormap for the original image display.	'magma'
min_value	float	Custom minimum value for display contrast (vmin). If None, uses the data minimum.	None
max_value	float	Custom maximum value for display contrast (vmax). If None, uses the data maximum.	None

Returns:

Name	Type	Description
slicer_obj	VBox	The interactive Jupyter widget containing the visualization plots and control sliders.

Example

import qim3d

# Load a sample volume
vol = qim3d.examples.bone_128x128x128

# Visualize interactive thresholding
qim3d.viz.threshold(vol)

Source code in qim3d/viz/_data_exploration.py

@coarseness('volume')
def threshold(
    volume: np.ndarray,
    colormap: str = 'magma',
    min_value: float = None,
    max_value: float = None,
) -> widgets.VBox:
    """
    Launches an interactive widget to perform 3D image segmentation via thresholding (binarization).

    This tool allows you to explore the volume slice-by-slice to determine the optimal cut-off value for creating a binary mask. It is essential for separating objects of interest from the background based on intensity. The interface provides real-time feedback by displaying the intensity histogram and overlaying the resulting mask on the original data.

    **Key Features:**

    * **Visualization:** Simultaneously views the original slice, intensity histogram, binary mask, and a color overlay.
    * **Manual Control:** Adjust the threshold value precisely using a slider.
    * **Automatic Algorithms:** Applies standard `skimage` auto-thresholding methods including Otsu, Isodata, Li, Mean, Minimum, Triangle, and Yen.
    * **Slice Navigation:** Scroll through the 3D stack to ensure the chosen threshold works across different depths.

    Args:
        volume (np.ndarray): The 3D input data (image stack) to threshold.
        colormap (str, optional): The Matplotlib colormap for the original image display.
        min_value (float, optional): Custom minimum value for display contrast (vmin). If `None`, uses the data minimum.
        max_value (float, optional): Custom maximum value for display contrast (vmax). If `None`, uses the data maximum.

    Returns:
        slicer_obj (widgets.VBox):
            The interactive Jupyter widget containing the visualization plots and control sliders.

    Example:
        ```python
        import qim3d

        # Load a sample volume
        vol = qim3d.examples.bone_128x128x128

        # Visualize interactive thresholding
        qim3d.viz.threshold(vol)
        ```
        ![interactive threshold](../../assets/screenshots/interactive_thresholding.gif)

    """

    # Centralized state dictionary to track current parameters
    state = {
        'position': volume.shape[0] // 2,
        'method': 'Manual',
    }

    if np.issubdtype(volume.dtype, np.integer):
        step = 1
        state['threshold'] = int((volume.min() + volume.max()) / 2)
    elif np.issubdtype(volume.dtype, np.floating):
        step = (volume.max() - volume.min()) / 1000
        state['threshold'] = (volume.min() + volume.max()) / 2
    else:
        pass

    threshold_methods = {
        'Otsu': threshold_otsu,
        'Isodata': threshold_isodata,
        'Li': threshold_li,
        'Mean': threshold_mean,
        'Minimum': threshold_minimum,
        'Triangle': threshold_triangle,
        'Yen': threshold_yen,
    }

    # Create an output widget to display the plot
    output = widgets.Output()

    # Function to update the state and trigger visualization
    def update_state(change: dict[str, Any]) -> None:
        # Update state based on widget values
        state['position'] = position_slider.value
        state['method'] = method_dropdown.value

        if state['method'] == 'Manual':
            state['threshold'] = threshold_slider.value
            threshold_slider.disabled = False
        else:
            threshold_func = threshold_methods.get(state['method'])
            if threshold_func:
                slice_img = volume[state['position'], :, :]
                computed_threshold = threshold_func(slice_img)
                state['threshold'] = computed_threshold

                # Programmatically update the slider without triggering callbacks
                threshold_slider.unobserve_all()
                threshold_slider.value = computed_threshold
                threshold_slider.disabled = True
                threshold_slider.observe(update_state, names='value')
            else:
                msg = f'Unsupported thresholding method: {state["method"]}'
                raise ValueError(msg)

        # Trigger visualization
        update_visualization()

    # Visualization function
    def update_visualization() -> None:
        slice_img = volume[state['position'], :, :]
        with output:
            output.clear_output(wait=True)  # Clear previous plot
            fig, axes = plt.subplots(1, 4, figsize=(25, 5))

            # Original image
            new_min_value = (
                None
                if (
                    isinstance(min_value, float | int) and min_value > np.max(slice_img)
                )
                else min_value
            )
            new_max_value = (
                None
                if (
                    isinstance(max_value, float | int) and max_value < np.min(slice_img)
                )
                else max_value
            )
            axes[0].imshow(
                slice_img, cmap=colormap, vmin=new_min_value, vmax=new_max_value
            )
            axes[0].set_title('Original')
            axes[0].axis('off')

            # Histogram
            histogram(
                volume=volume,
                bins=32,
                slice_index=state['position'],
                vertical_line=state['threshold'],
                kde=False,
                ax=axes[1],
                show=False,
            )
            thr = state['threshold']
            thr = (
                f'{state["threshold"]:.3f}'
                if isinstance(step, float)
                else int(state['threshold'])
            )
            axes[1].set_title(f'Histogram with Threshold = {thr}')

            # Binary mask
            mask = slice_img >= state['threshold']
            axes[2].imshow(mask, cmap='gray')
            axes[2].set_title('Binary mask')
            axes[2].axis('off')

            # Overlay
            mask_rgb = np.zeros((mask.shape[0], mask.shape[1], 3), dtype=np.uint8)
            mask_rgb[:, :, 0] = mask
            masked_volume = qim3d.operations.overlay_rgb_images(
                background=slice_img,
                foreground=mask_rgb,
            )
            axes[3].imshow(masked_volume, vmin=new_min_value, vmax=new_max_value)
            axes[3].set_title('Overlay')
            axes[3].axis('off')

            plt.show()

    # Widgets
    position_slider = widgets.IntSlider(
        value=state['position'],
        min=0,
        max=volume.shape[0] - 1,
        description='Slice',
    )

    threshold_slider = widgets.FloatSlider(
        value=state['threshold'],
        min=volume.min(),
        max=volume.max(),
        step=step,
        description='Threshold',
        readout_format='d' if step == 1 else '.3f',
    )

    method_dropdown = widgets.Dropdown(
        options=[
            'Manual',
            'Otsu',
            'Isodata',
            'Li',
            'Mean',
            'Minimum',
            'Triangle',
            'Yen',
        ],
        value=state['method'],
        description='Method',
    )

    # Attach the state update function to widgets
    position_slider.observe(update_state, names='value')
    threshold_slider.observe(update_state, names='value')
    method_dropdown.observe(update_state, names='value')

    # Layout
    controls_left = widgets.VBox([position_slider, threshold_slider])
    controls_right = widgets.VBox([method_dropdown])
    controls_layout = widgets.HBox(
        [controls_left, controls_right],
        layout=widgets.Layout(justify_content='flex-start'),
    )
    interactive_ui = widgets.VBox([controls_layout, output])
    update_visualization()

    return interactive_ui

qim3d.viz.vector_field_3d

vector_field_3d(vec, val, volume, select_eigen='smallest', sampling_step=4, cone_size=1, verbose=True, cmin=None, cmax=None, **kwargs)

Visualizes the 3D eigenvector field of a structure tensor as a bidirectional cone plot.

Each sampled location in the volume is represented by two mirrored cones pointing in
opposite directions along the eigenvector axis. Two cones are used because eigenvectors
are direction-less: the structure tensor tells us the orientation axis but not which end
points where.

Color and cone size both encode the eigenvalue corresponding to the selected eigenvector,
inverted and normalized to [0, 1]. This means cones are larger and brighter where the
local structure is most coherent (low eigenvalue) and smaller and darker in noisy or
ambiguous regions (high eigenvalue).

Note: Plotly's go.Cone colors each cone by the magnitude of its vector, which means
color and size cannot be decoupled. Any scalar encoded as color will automatically also
control size. This rules out direction-based coloring schemes. For full RGB coloring
based on fiber orientation, use the streamlines function instead.

Background voxels where the volume is zero are masked out before sampling.

For background on structure tensors and eigenvalue interpretation, see:
https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

Parameters:

Name	Type	Description	Default
vec	ndarray	Eigenvectors of the structure tensor with shape (3, 3, Z, Y, X). The first dimension indexes the eigenvector (0 = smallest, 1 = middle, 2 = largest).	required
val	ndarray	Eigenvalues of the structure tensor with shape (3, Z, Y, X). The first dimension indexes the eigenvalue (0 = smallest, 1 = middle, 2 = largest).	required
volume	ndarray	The original 3D volume with shape (Z, Y, X). Used to mask out background regions where the volume intensity is zero.	required
select_eigen	str	Which eigenvector to visualize. Use 'smallest' for the direction of minimum intensity change (fiber direction in structure tensors), 'largest' for the direction of maximum change, or 'middle' for the intermediate direction. Defaults to 'smallest'.	'smallest'
sampling_step	int	Spacing in voxels between sampled locations. Higher values produce fewer but faster cones. Lower values produce denser visualizations but are slower to compute. Defaults to 4.	4
cone_size	float	Global scale factor controlling the size of all cones. Increase to make cones larger, decrease to make them smaller. Defaults to 1.	1
verbose	bool	If True, prints information about the number of cones plotted and the eigenvalue range. Defaults to True.	True
cmin	float	Minimum value for the colorscale. If None, uses the minimum value in the data. Defaults to None.	None
cmax	float	Maximum value for the colorscale. If None, uses the maximum value in the data. Defaults to None.	None
**kwargs		Additional keyword arguments passed directly to Plotly's go.Cone.	{}

Returns:

Type	Description
Figure	go.Figure: An interactive Plotly 3D figure showing the cone plot.

Example:

        import qim3d

        vol = qim3d.examples.fiber_150x256x256
        val, vec = qim3d.processing.structure_tensor(vol, sigma=2.0, rho=6)

        fig = qim3d.viz.vector_field_3d(vec, val, vol, select_eigen='smallest')
        fig.show()

Source code in qim3d/viz/_structure_tensor.py

def vector_field_3d(
    vec: np.ndarray,
    val: np.ndarray,
    volume: np.ndarray,
    select_eigen: Literal['smallest', 'largest', 'middle'] = 'smallest',
    sampling_step: int = 4,
    cone_size: float = 1,
    verbose: bool = True,
    cmin: float = None,
    cmax: float = None,
    **kwargs,
) -> go.Figure:
    """
        Visualizes the 3D eigenvector field of a structure tensor as a bidirectional cone plot.

        Each sampled location in the volume is represented by two mirrored cones pointing in
        opposite directions along the eigenvector axis. Two cones are used because eigenvectors
        are direction-less: the structure tensor tells us the orientation axis but not which end
        points where.

        Color and cone size both encode the eigenvalue corresponding to the selected eigenvector,
        inverted and normalized to [0, 1]. This means cones are larger and brighter where the
        local structure is most coherent (low eigenvalue) and smaller and darker in noisy or
        ambiguous regions (high eigenvalue).

        Note: Plotly's go.Cone colors each cone by the magnitude of its vector, which means
        color and size cannot be decoupled. Any scalar encoded as color will automatically also
        control size. This rules out direction-based coloring schemes. For full RGB coloring
        based on fiber orientation, use the streamlines function instead.

        Background voxels where the volume is zero are masked out before sampling.

        For background on structure tensors and eigenvalue interpretation, see:
        https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

    Args:
            vec (np.ndarray): Eigenvectors of the structure tensor with shape (3, 3, Z, Y, X).
                The first dimension indexes the eigenvector (0 = smallest, 1 = middle, 2 = largest).
            val (np.ndarray): Eigenvalues of the structure tensor with shape (3, Z, Y, X).
                The first dimension indexes the eigenvalue (0 = smallest, 1 = middle, 2 = largest).
            volume (np.ndarray): The original 3D volume with shape (Z, Y, X). Used to mask out
                background regions where the volume intensity is zero.
            select_eigen (str, optional): Which eigenvector to visualize. Use 'smallest' for the
                direction of minimum intensity change (fiber direction in structure tensors),
                'largest' for the direction of maximum change, or 'middle' for the intermediate
                direction. Defaults to 'smallest'.
            sampling_step (int, optional): Spacing in voxels between sampled locations. Higher
                values produce fewer but faster cones. Lower values produce denser visualizations
                but are slower to compute. Defaults to 4.
            cone_size (float, optional): Global scale factor controlling the size of all cones.
                Increase to make cones larger, decrease to make them smaller. Defaults to 1.
            verbose (bool, optional): If True, prints information about the number of cones
                plotted and the eigenvalue range. Defaults to True.
            cmin (float, optional): Minimum value for the colorscale. If None, uses the minimum
                value in the data. Defaults to None.
            cmax (float, optional): Maximum value for the colorscale. If None, uses the maximum
                value in the data. Defaults to None.
            **kwargs: Additional keyword arguments passed directly to Plotly's go.Cone.

    Returns:
            go.Figure: An interactive Plotly 3D figure showing the cone plot.

    Example:
    ```python
            import qim3d

            vol = qim3d.examples.fiber_150x256x256
            val, vec = qim3d.processing.structure_tensor(vol, sigma=2.0, rho=6)

            fig = qim3d.viz.vector_field_3d(vec, val, vol, select_eigen='smallest')
            fig.show()
    ```

    """

    eps = 1e-12

    # Select the eigenvector and its corresponding eigenvalue based on user choice
    if vec.ndim == 5:
        if select_eigen == 'largest':
            vec = vec[2, :, ...]
            eigen_val = val[2]
        elif select_eigen == 'smallest':
            vec = vec[0, :, ...]
            eigen_val = val[0]
        elif select_eigen == 'middle':
            vec = vec[1, :, ...]
            eigen_val = val[1]
        else:
            raise ValueError(
                f'Invalid select_eigen: {select_eigen}. '
                'Choose "smallest", "largest", or "middle".'
            )

    # Rearrange axes from (3, Z, Y, X) to (Z, Y, X, 3) for easier spatial indexing
    vec = np.transpose(vec, (1, 2, 3, 0))

    # Zero out eigenvectors in background voxels to avoid plotting cones in empty space
    vec[volume == 0] = 0

    # Normalize the eigenvalue to [0, 1] using the 99th percentile to avoid outlier spikes,
    # then invert so that low eigenvalues (strong coherent structure) produce large bright cones
    ev_flat = eigen_val.ravel()
    ev_max = np.percentile(ev_flat[ev_flat > 0], 99)
    eigen_val_norm = np.clip(eigen_val / (ev_max + eps), 0, 1)
    eigen_val_norm = 1 - eigen_val_norm

    if verbose:
        log.info(
            f'Eigenvalue range: {eigen_val[eigen_val > 0].min():.4f} to {eigen_val.max():.4f}'
        )
        log.info(
            f'Normalized eigenvalue range: {eigen_val_norm.min():.4f} to {eigen_val_norm.max():.4f}'
        )

    nx, ny, nz, _ = vec.shape
    half = sampling_step // 2

    if verbose:
        log.info(f'Original number of grid points: {nx * ny * nz}')

    points, vectors, val_values = [], [], []

    # Average vectors and eigenvalues within each sampling cube across the volume
    for px in np.arange(0, nx, sampling_step):
        for py in np.arange(0, ny, sampling_step):
            for pz in np.arange(0, nz, sampling_step):
                x0, x1 = max(px - half, 0), min(px + half + 1, nx)
                y0, y1 = max(py - half, 0), min(py + half + 1, ny)
                z0, z1 = max(pz - half, 0), min(pz + half + 1, nz)

                avg_vec = vec[x0:x1, y0:y1, z0:z1, :].mean(axis=(0, 1, 2))
                avg_val = eigen_val_norm[x0:x1, y0:y1, z0:z1].mean()

                # Skip cubes that are entirely background or have no valid data
                if (
                    not np.isfinite(avg_vec).all()
                    or np.all(avg_vec == 0)
                    or avg_val <= 0
                ):
                    continue

                points.append((px, py, pz))
                vectors.append(avg_vec)
                val_values.append(avg_val)

    if not points:
        raise ValueError('No valid cones to plot. Try lowering sampling_step.')

    points = np.array(points)
    vectors = np.array(vectors)
    val_values = np.array(val_values)

    if verbose:
        log.info(f'Cones plotted: {len(points)}')
        log.info(
            f'Eigenvalue (normalized) range: {val_values.min():.4f} to {val_values.max():.4f}'
        )

    # Normalize each vector to unit length for consistent cone direction
    norms = np.linalg.norm(vectors, axis=1, keepdims=True)
    norms[norms == 0] = 1
    unit_vecs = vectors / norms

    # Resolve sign ambiguity by forcing vz >= 0
    # Eigenvectors have no preferred sense (v and -v are equivalent), so we
    # standardize the direction to ensure consistent orientation across the field
    flip = unit_vecs[:, 2] < 0
    unit_vecs[flip] *= -1

    # Scale the unit vectors by the normalized eigenvalue so that the cone magnitude
    # encodes structural coherence — go.Cone uses magnitude for both color and size
    u = unit_vecs[:, 0] * val_values
    v = unit_vecs[:, 1] * val_values
    w = unit_vecs[:, 2] * val_values

    if cmin is None:
        cmin = val_values.min()
    if cmax is None:
        cmax = val_values.max()

    shared = dict(
        x=points[:, 2],
        y=points[:, 1],
        z=points[:, 0],
        sizemode='scaled',
        sizeref=cone_size,
        colorscale='Hot',
        cmin=cmin,
        cmax=cmax,
        anchor='tail',
        **kwargs,
    )

    # Plot two mirrored cones per point to represent the bidirectional nature of eigenvectors
    fig = go.Figure(
        data=[
            go.Cone(u=u, v=v, w=w, colorbar_title=f'λ ({select_eigen})', **shared),
            go.Cone(u=-u, v=-v, w=-w, showscale=False, **shared),
        ],
        layout={'width': 900, 'height': 700},
    )

    return fig

qim3d.viz.vectors

vectors(volume, vectors, axis=0, volume_colormap='grey', min_value=None, max_value=None, slice_index=None, grid_size=10, interactive=True, figsize=(10, 5), background=None, show=False)

Visualizes the local orientation of structures using structure tensor eigenvectors
overlaid on a 2D slice of the volume.

Generates a three-panel visualization:

1. **Quiver Plot:** Arrows showing the dominant orientation direction in the slice plane.
2. **Orientation Histogram:** Distribution of orientation angles in the current slice,
   colored by the same HSV scheme used in the color map.
3. **Color Map:** The slice colored by orientation using an HSV scheme where hue encodes
   the in-plane angle and saturation encodes how much the fiber points out of the plane
   (fibers pointing out of the screen appear desaturated toward gray).

The color scheme follows the fan-based approach described in Dahl 2026:
https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input volume with shape (Z, Y, X).	required
vectors	ndarray	The eigenvectors of the structure tensor with shape (3, Z, Y, X). If the full eigenvector array of shape (3, 3, Z, Y, X) is provided, only the first eigenvector (corresponding to the smallest eigenvalue) will be used.	required
axis	int	The axis along which to slice the volume. 0 slices along Z, 1 along Y, 2 along X. Defaults to 0.	0
volume_colormap	str	The colormap used to display the background volume slice in the quiver plot. Defaults to 'grey'.	'grey'
min_value	float	Minimum intensity value for display contrast adjustment. Useful for highlighting specific intensity ranges. Defaults to None.	None
max_value	float	Maximum intensity value for display contrast adjustment. Useful for highlighting specific intensity ranges. Defaults to None.	None
slice_index	int or float	Which slice to display initially. Provide an integer for the exact slice index, a float between 0.0 and 1.0 for a relative position, or None to default to the middle slice.	None
grid_size	int	Spacing between arrows in the quiver plot in pixels. Lower values produce denser arrow fields. Defaults to 10.	10
interactive	bool	If True, returns a widget with sliders to scroll through slices and adjust arrow density. If False, returns a static figure. Defaults to True.	True
figsize	tuple[int, int]	Width and height of the figure in inches. Defaults to (10, 5).	(10, 5)
background	float	Intensity threshold below which orientation vectors are hidden. Useful for suppressing arrows in background regions. Set to 0 to hide all zero-intensity regions. Defaults to None (no filtering).	None
show	bool	If True, immediately displays the plot by calling plt.show(). Defaults to False.	False

Returns:

Name	Type	Description
object	interactive or Figure	A widget with interactive sliders if interactive is True, or a static matplotlib figure if interactive is False.

Raises:

Type	Description
ValueError	If axis is not 0, 1, or 2, or if slice_index is out of bounds.

Example:

        import qim3d

        vol = qim3d.examples.NT_128x128x128
        val, vec = qim3d.processing.structure_tensor(vol)

        qim3d.viz.vectors(vol, vec, axis=2, interactive=True)

Source code in qim3d/viz/_structure_tensor.py

def vectors(
    volume: np.ndarray,
    vectors: np.ndarray,
    axis: int = 0,
    volume_colormap: str = 'grey',
    min_value: float | None = None,
    max_value: float | None = None,
    slice_index: int | float | None = None,
    grid_size: int = 10,
    interactive: bool = True,
    figsize: tuple[int, int] = (10, 5),
    background: int | None = None,
    show: bool = False,
) -> plt.Figure | widgets.interactive:
    """
        Visualizes the local orientation of structures using structure tensor eigenvectors
        overlaid on a 2D slice of the volume.

        Generates a three-panel visualization:

        1. **Quiver Plot:** Arrows showing the dominant orientation direction in the slice plane.
        2. **Orientation Histogram:** Distribution of orientation angles in the current slice,
           colored by the same HSV scheme used in the color map.
        3. **Color Map:** The slice colored by orientation using an HSV scheme where hue encodes
           the in-plane angle and saturation encodes how much the fiber points out of the plane
           (fibers pointing out of the screen appear desaturated toward gray).

        The color scheme follows the fan-based approach described in Dahl 2026:
        https://people.compute.dtu.dk/vand/notes/ST_intro.pdf

    Args:
            volume (np.ndarray): The 3D input volume with shape (Z, Y, X).
            vectors (np.ndarray): The eigenvectors of the structure tensor with shape (3, Z, Y, X).
                If the full eigenvector array of shape (3, 3, Z, Y, X) is provided, only the
                first eigenvector (corresponding to the smallest eigenvalue) will be used.
            axis (int, optional): The axis along which to slice the volume.
                0 slices along Z, 1 along Y, 2 along X. Defaults to 0.
            volume_colormap (str, optional): The colormap used to display the background volume
                slice in the quiver plot. Defaults to 'grey'.
            min_value (float, optional): Minimum intensity value for display contrast adjustment.
                Useful for highlighting specific intensity ranges. Defaults to None.
            max_value (float, optional): Maximum intensity value for display contrast adjustment.
                Useful for highlighting specific intensity ranges. Defaults to None.
            slice_index (int or float, optional): Which slice to display initially.
                Provide an integer for the exact slice index, a float between 0.0 and 1.0
                for a relative position, or None to default to the middle slice.
            grid_size (int, optional): Spacing between arrows in the quiver plot in pixels.
                Lower values produce denser arrow fields. Defaults to 10.
            interactive (bool, optional): If True, returns a widget with sliders to scroll
                through slices and adjust arrow density. If False, returns a static figure.
                Defaults to True.
            figsize (tuple[int, int], optional): Width and height of the figure in inches.
                Defaults to (10, 5).
            background (float, optional): Intensity threshold below which orientation vectors
                are hidden. Useful for suppressing arrows in background regions. Set to 0 to
                hide all zero-intensity regions. Defaults to None (no filtering).
            show (bool, optional): If True, immediately displays the plot by calling
                plt.show(). Defaults to False.

    Returns:
            object (widgets.interactive or matplotlib.figure.Figure):
                A widget with interactive sliders if interactive is True,
                or a static matplotlib figure if interactive is False.

    Raises:
            ValueError: If axis is not 0, 1, or 2, or if slice_index is out of bounds.

    Example:
    ```python
            import qim3d

            vol = qim3d.examples.NT_128x128x128
            val, vec = qim3d.processing.structure_tensor(vol)

            qim3d.viz.vectors(vol, vec, axis=2, interactive=True)
    ```
            ![structure tensor](../../assets/screenshots/structure_tensor_visualization.gif)

    """

    # Ensure volume is a float array for correct normalization
    if volume.dtype != np.float32 and volume.dtype != np.float64:
        volume = volume.astype(np.float32)

    # Normalize volume to [0, 1] if values are in [0, 255]
    if volume.max() > 1.0:
        volume = volume / 255.0

    # Compute valid grid size range based on volume dimensions
    min_grid_size = max(1, volume.shape[axis] // 50)
    max_grid_size = max(1, volume.shape[axis] // 10)
    if max_grid_size <= min_grid_size:
        max_grid_size = min_grid_size * 5

    if not grid_size:
        grid_size = (min_grid_size + max_grid_size) // 2

    if grid_size < min_grid_size or grid_size > max_grid_size:
        grid_size = min(max(min_grid_size, grid_size), max_grid_size)
        log.warning(f'Adjusting grid size to {grid_size} as it is out of bounds.')

    def _structure_tensor(volume, vectors, axis, slice_index, grid_size, figsize, show):
        # Extract the 2D slice and corresponding vector components based on the chosen axis
        if axis == 0:
            data_slice = volume[slice_index, :, :]
            vectors_slice_x = vectors[0, slice_index, :, :]
            vectors_slice_y = vectors[1, slice_index, :, :]
            vectors_slice_z = vectors[2, slice_index, :, :]
        elif axis == 1:
            data_slice = volume[:, slice_index, :]
            vectors_slice_x = vectors[0, :, slice_index, :]
            vectors_slice_y = vectors[2, :, slice_index, :]
            vectors_slice_z = vectors[1, :, slice_index, :]
        elif axis == 2:
            data_slice = volume[:, :, slice_index]
            vectors_slice_x = vectors[1, :, :, slice_index]
            vectors_slice_y = vectors[2, :, :, slice_index]
            vectors_slice_z = vectors[0, :, :, slice_index]
        else:
            msg = 'Invalid dimension. Use 0 for Z, 1 for Y, or 2 for X.'
            raise ValueError(msg)

        fig, ax = plt.subplots(1, 3, figsize=figsize, layout='constrained')

        # Blending function: mixes pure hue color toward gray (0.5) based on saturation
        # When saturation is 0 the color is pure hue, when 1 it becomes gray
        blend_hue_saturation = lambda hue, sat: hue * (1 - sat) + 0.5 * sat

        # ===================== PANEL 1: QUIVER PLOT =====================

        xmesh, ymesh = np.mgrid[0 : data_slice.shape[0], 0 : data_slice.shape[1]]

        # Sample grid points at regular intervals defined by grid_size
        g = slice(grid_size // 2, None, grid_size)  # noqa: A002

        # Only show arrows where the volume intensity is above zero
        intensity_mask = data_slice[g, g] > 0

        x_valid = xmesh[g, g][intensity_mask]
        y_valid = ymesh[g, g][intensity_mask]
        vx_valid = vectors_slice_x[g, g][intensity_mask]
        vy_valid = vectors_slice_y[g, g][intensity_mask]

        # Compute in-plane angle in [0, π] using mod π to handle sign ambiguity
        # (v and -v represent the same orientation, mod π maps them to the same angle)
        angles_quiver = np.mod(
            np.arctan2(vectors_slice_y[g, g], vectors_slice_x[g, g]),
            np.pi,
        )

        # The z-component squared gives how much the fiber points out of the slice plane
        # This is used as saturation: high vz means the fiber is out of plane → gray color
        saturation_quiver = (vectors_slice_z[g, g] ** 2)[:, :, np.newaxis]

        hue_quiver = plt.cm.hsv(angles_quiver / np.pi)
        rgba_quiver = blend_hue_saturation(hue_quiver, saturation_quiver)
        rgba_quiver = np.clip(rgba_quiver, 0, 1)
        rgba_quiver_flat = rgba_quiver.reshape(
            (rgba_quiver.shape[0] * rgba_quiver.shape[1], 4)
        )

        # Plot bidirectional arrows (both +v and -v) since eigenvectors have no preferred sense
        ax[0].quiver(
            y_valid, x_valid, vx_valid, vy_valid, color=rgba_quiver_flat, angles='xy'
        )
        ax[0].quiver(
            y_valid, x_valid, -vx_valid, -vy_valid, color=rgba_quiver_flat, angles='xy'
        )
        ax[0].imshow(data_slice, cmap=volume_colormap, vmin=min_value, vmax=max_value)
        ax[0].set_title(
            f'Orientation vectors (slice {slice_index})'
            if not interactive
            else 'Orientation vectors'
        )
        ax[0].set_axis_off()

        # ===================== PANEL 2: ORIENTATION HISTOGRAM =====================

        nbins = 36

        # Compute angles for the full slice, optionally filtered by background threshold
        angles = np.mod(np.arctan2(vectors_slice_y, vectors_slice_x), np.pi)
        intensity_mask_full = (
            data_slice > background
            if background is not None
            else np.ones_like(data_slice, dtype=bool)
        )
        angles_filtered = angles[intensity_mask_full]

        distribution, bin_edges = np.histogram(
            angles_filtered, bins=nbins, range=(0.0, np.pi)
        )
        bin_centers = (np.arange(nbins) + 0.5) * np.pi / nbins

        # Compute mean out-of-plane component per bin for saturation coloring
        bins = np.digitize(angles.ravel(), bin_edges)
        saturation_bin = np.array(
            [
                np.mean((vectors_slice_z**2).ravel()[bins == i])
                if np.sum(bins == i) > 0
                else 0
                for i in range(1, len(bin_edges))
            ]
        )

        hue_bin = plt.cm.hsv(bin_centers / np.pi)
        rgba_bin = hue_bin.copy()
        rgba_bin[:, :3] = blend_hue_saturation(
            hue_bin[:, :3], saturation_bin[:, np.newaxis]
        )

        ax[1].bar(bin_centers, distribution, width=np.pi / nbins, color=rgba_bin)
        ax[1].set_xlabel('Angle [radians]')
        ax[1].set_xlim([0, np.pi])
        ax[1].set_aspect(np.pi / ax[1].get_ylim()[1])
        ax[1].set_xticks([0, np.pi / 2, np.pi])
        ax[1].set_xticklabels(['0', '$\\frac{\\pi}{2}$', '$\\pi$'])
        ax[1].set_yticks([])
        ax[1].set_ylabel('Frequency')
        ax[1].set_title('Histogram over orientation angles')

        # ===================== PANEL 3: COLOR MAP =====================

        saturation = (vectors_slice_z**2)[:, :, np.newaxis]
        hue = plt.cm.hsv(angles / np.pi)
        rgba = blend_hue_saturation(hue, saturation)

        # Only color pixels above the background threshold, keep the rest as grayscale
        intensity_mask_2d = (
            data_slice > background
            if background is not None
            else np.ones_like(data_slice, dtype=bool)
        )

        gray_slice = plt.cm.gray(data_slice)[:, :, :3]
        data_slice_orientation_colored = gray_slice.copy()
        data_slice_orientation_colored[intensity_mask_2d] = 0.5 * (
            gray_slice[intensity_mask_2d] + rgba[:, :, :3][intensity_mask_2d]
        )
        data_slice_orientation_colored = (data_slice_orientation_colored * 255).astype(
            'uint8'
        )

        ax[2].imshow(data_slice_orientation_colored)
        ax[2].set_title(
            f'Colored orientations (slice {slice_index})'
            if not interactive
            else 'Colored orientations'
        )
        ax[2].set_axis_off()

        if show:
            plt.show()

        plt.close()
        return fig

    # If the full eigenvector array is provided, use only the first eigenvector
    if vectors.ndim == 5:
        vectors = vectors[0, ...]
        log.warning(
            'Eigenvector array is full. Only the eigenvectors corresponding to the first eigenvalue will be used.'
        )

    # Determine the initial slice index
    if slice_index is None:
        slice_index = volume.shape[axis] // 2
    elif isinstance(slice_index, float):
        if slice_index < 0 or slice_index > 1:
            raise ValueError(
                'Values of slice_index of float type must be between 0 and 1.'
            )
        slice_index = int(slice_index * volume.shape[0]) - 1

    if interactive:
        slice_index_slider = widgets.IntSlider(
            min=0,
            max=volume.shape[axis] - 1,
            step=1,
            value=slice_index,
            description='Slice index',
            layout=widgets.Layout(width='450px'),
        )
        grid_size_slider = widgets.IntSlider(
            min=min_grid_size,
            max=max_grid_size,
            step=1,
            value=grid_size,
            description='Grid size',
            layout=widgets.Layout(width='450px'),
        )
        widget_obj = widgets.interactive(
            _structure_tensor,
            volume=widgets.fixed(volume),
            vectors=widgets.fixed(vectors),
            axis=widgets.fixed(axis),
            slice_index=slice_index_slider,
            grid_size=grid_size_slider,
            figsize=widgets.fixed(figsize),
            show=widgets.fixed(True),
        )
        sliders_box = widgets.HBox([slice_index_slider, grid_size_slider])
        widget_obj = widgets.VBox([sliders_box, widget_obj.children[-1]])
        widget_obj.layout.align_items = 'center'

        if show:
            display(widget_obj)

        return widget_obj

    else:
        return _structure_tensor(
            volume, vectors, axis, slice_index, grid_size, figsize, show
        )

qim3d.viz.vol_masked

vol_masked(volume, volume_mask, viz_delta=128)

Applies masking to a volume based on a binary volume mask.

This function takes a volume array volume and a corresponding binary volume mask volume_mask. It computes the masked volume where pixels outside the mask are set to the background value, and pixels inside the mask are set to foreground.

Parameters:

Name	Type	Description	Default
volume	ndarray	The input volume as a NumPy array.	required
volume_mask	ndarray	The binary mask volume as a NumPy array with the same shape as volume.	required
viz_delta	int	Value added to the volume before applying the mask to visualize masked regions. Defaults to 128.	128

Returns:

Name	Type	Description
ndarray	ndarray	The masked volume with the same shape as volume, where pixels outside the mask are set to the background value (negative).

Source code in qim3d/viz/_metrics.py

def vol_masked(
    volume: np.ndarray, volume_mask: np.ndarray, viz_delta: int = 128
) -> np.ndarray:
    """
    Applies masking to a volume based on a binary volume mask.

    This function takes a volume array `volume` and a corresponding binary volume mask `volume_mask`.
    It computes the masked volume where pixels outside the mask are set to the background value,
    and pixels inside the mask are set to foreground.


    Args:
        volume (ndarray): The input volume as a NumPy array.
        volume_mask (ndarray): The binary mask volume as a NumPy array with the same shape as `volume`.
        viz_delta (int, optional): Value added to the volume before applying the mask to visualize masked regions.
            Defaults to 128.

    Returns:
        ndarray: The masked volume with the same shape as `volume`, where pixels outside the mask are set
            to the background value (negative).


    """

    background = (volume.astype('float') + viz_delta) * (1 - volume_mask) * -1
    foreground = (volume.astype('float') + viz_delta) * volume_mask
    volume_masked_result = background + foreground

    return volume_masked_result

qim3d.viz.volumetric

volumetric(volume, aspectmode='data', show=True, save=False, grid_visible=False, colormap='magma', constant_opacity=False, opacity_function=None, min_value=None, max_value=None, samples='auto', max_voxels=256 ** 3, data_type='scaled_float16', camera_mode='orbit', **kwargs)

Renders a 3D volume using high-performance hardware-accelerated ray-casting.

Creates an interactive 3D visualization in the browser using K3D. This function is ideal for inspecting complex voxel data, understanding 3D spatial relationships, or creating exportable HTML representations of a stack. It handles large datasets by automatically downsampling if the size exceeds a set threshold.

Key Features:

• Browser-Based: Renders directly in Jupyter notebooks or exports to standalone HTML.
• Performance: Automatically manages sampling rates and data types (float16) for smooth interaction.
• Customization: Supports custom colormaps, opacity transfer functions, and camera modes.

Parameters:

Name	Type	Description	Default
volume	ndarray	The 3D input data to be rendered.	required
aspectmode	str	Controls the proportions of the scene axes. 'data': Axes are drawn in proportion to the physical data range. 'cube': Axes are constrained to a cube regardless of data range.	'data'
show	bool	If True, displays the plot immediately.	True
save	bool or str	Controls saving the output. str: Saves the visualization to the specified HTML file path. True: Saves as 'snapshot.html' (default behavior of save). False: Does not save the file.	False
grid_visible	bool	If True, displays a grid around the volume.	False
colormap	str, matplotlib.colors.Colormap, or list	Colormap for the rendering. Can be a Matplotlib name (e.g., 'magma') or object.	'magma'
constant_opacity	bool	Deprecated. Use opacity_function='constant' instead.	False
opacity_function	str or list	Defines the transparency transfer function. 'constant': Sets a uniform opacity for segmentation masks. list: A specific list defining the opacity curve.	None
min_value	float	Minimum value for color scaling. If None, inferred from data.	None
max_value	float	Maximum value for color scaling. If None, inferred from data.	None
samples	int or str	Number of ray-marching samples. 'auto': Calculates optimal samples based on volume size. int: Specific number of samples (lower is faster, higher is better quality).	'auto'
max_voxels	int	Maximum number of voxels allowed before downsampling occurs (defaults to approx. 16 million).	256 ** 3
data_type	str	Internal data type for rendering. 'scaled_float16' reduces memory usage.	'scaled_float16'
camera_mode	str	Interaction mode for the camera ('orbit', 'trackball', or 'fly').	'orbit'
**kwargs		Additional keyword arguments passed to k3d.plot.	{}

Returns:

Name	Type	Description
plot	Plot	The K3D plot object. Returned if show=False.

Raises:

Type	Description
ValueError	If aspectmode is not 'data' or 'cube'.
ValueError	If camera_mode is not 'orbit', 'trackball', or 'fly'.

Tip

The function can be used for object label visualization using a colormap created with qim3d.viz.colormaps.objects along with setting objects=True. The latter ensures appropriate rendering.

Example

Display a volume inline:

import qim3d

vol = qim3d.examples.bone_128x128x128
qim3d.viz.volumetric(vol)

Save the rendering to an HTML file without displaying it:

plot = qim3d.viz.volumetric(vol, show=False, save="my_render.html")

Source code in qim3d/viz/_k3d.py

@coarseness('volume')
def volumetric(
    volume: np.ndarray,
    aspectmode: str = 'data',
    show: bool = True,
    save: bool = False,
    grid_visible: bool = False,
    colormap: str = 'magma',
    constant_opacity: bool = False,
    opacity_function: str | list = None,
    min_value: float | None = None,
    max_value: float | None = None,
    samples: int | str = 'auto',
    max_voxels: int = 256**3,
    data_type: str = 'scaled_float16',
    camera_mode: str = 'orbit',
    **kwargs,
) -> k3d.Plot | None:
    """
    Renders a 3D volume using high-performance hardware-accelerated ray-casting.

    Creates an interactive 3D visualization in the browser using K3D. This function is ideal for inspecting complex voxel data, understanding 3D spatial relationships, or creating exportable HTML representations of a stack. It handles large datasets by automatically downsampling if the size exceeds a set threshold.

    **Key Features:**

    * **Browser-Based:** Renders directly in Jupyter notebooks or exports to standalone HTML.
    * **Performance:** Automatically manages sampling rates and data types (`float16`) for smooth interaction.
    * **Customization:** Supports custom colormaps, opacity transfer functions, and camera modes.

    Args:
        volume (numpy.ndarray): The 3D input data to be rendered.
        aspectmode (str, optional): Controls the proportions of the scene axes.

            * `'data'`: Axes are drawn in proportion to the physical data range.
            * `'cube'`: Axes are constrained to a cube regardless of data range.

        show (bool, optional): If `True`, displays the plot immediately.
        save (bool or str, optional): Controls saving the output.

            * **str**: Saves the visualization to the specified HTML file path.
            * **True**: Saves as 'snapshot.html' (default behavior of save).
            * **False**: Does not save the file.

        grid_visible (bool, optional): If `True`, displays a grid around the volume.
        colormap (str, matplotlib.colors.Colormap, or list, optional): Colormap for the rendering. Can be a Matplotlib name (e.g., 'magma') or object.
        constant_opacity (bool, optional): **Deprecated**. Use `opacity_function='constant'` instead.
        opacity_function (str or list, optional): Defines the transparency transfer function.

            * `'constant'`: Sets a uniform opacity for segmentation masks.
            * **list**: A specific list defining the opacity curve.

        min_value (float, optional): Minimum value for color scaling. If `None`, inferred from data.
        max_value (float, optional): Maximum value for color scaling. If `None`, inferred from data.
        samples (int or str, optional): Number of ray-marching samples.

            * `'auto'`: Calculates optimal samples based on volume size.
            * **int**: Specific number of samples (lower is faster, higher is better quality).

        max_voxels (int, optional): Maximum number of voxels allowed before downsampling occurs (defaults to approx. 16 million).
        data_type (str, optional): Internal data type for rendering. `'scaled_float16'` reduces memory usage.
        camera_mode (str, optional): Interaction mode for the camera (`'orbit'`, `'trackball'`, or `'fly'`).
        **kwargs: Additional keyword arguments passed to `k3d.plot`.

    Returns:
        plot (k3d.Plot):
            The K3D plot object. Returned if `show=False`.

    Raises:
        ValueError: If `aspectmode` is not 'data' or 'cube'.
        ValueError: If `camera_mode` is not 'orbit', 'trackball', or 'fly'.

    Tip:
        The function can be used for object label visualization using a `colormap` created with `qim3d.viz.colormaps.objects` along with setting `objects=True`. The latter ensures appropriate rendering.

    Example:
        Display a volume inline:
        ```python
        import qim3d

        vol = qim3d.examples.bone_128x128x128
        qim3d.viz.volumetric(vol)
        ```
        <iframe src="https://platform.qim.dk/k3d/fima-bone_128x128x128-20240221113459.html" width="100%" height="500" frameborder="0"></iframe>

        Save the rendering to an HTML file without displaying it:
        ```python
        plot = qim3d.viz.volumetric(vol, show=False, save="my_render.html")
        ```
    """

    pixel_count = volume.shape[0] * volume.shape[1] * volume.shape[2]
    # target is 60fps on m1 macbook pro, using test volume: https://data.qim.dk/pages/foam.html
    if samples == 'auto':
        y1, x1 = 256, 16777216  # 256 samples at res 256*256*256=16.777.216
        y2, x2 = 32, 134217728  # 32 samples at res 512*512*512=134.217.728

        # we fit linear function to the two points
        a = (y1 - y2) / (x1 - x2)
        b = y1 - a * x1

        samples = int(min(max(a * pixel_count + b, 64), 512))
    else:
        samples = int(samples)  # make sure it's an integer

    if aspectmode.lower() not in ['data', 'cube']:
        msg = "aspectmode should be either 'data' or 'cube'"
        raise ValueError(msg)

    if camera_mode not in ['orbit', 'trackball', 'fly']:
        msg = "camera_mode should be either 'orbit', 'trackbal' or 'fly'"
        raise ValueError(msg)

    # check if image should be downsampled for visualization
    original_shape = volume.shape
    volume = downscale_img(volume, max_voxels=max_voxels)

    new_shape = volume.shape

    if original_shape != new_shape:
        log.warning(
            f'Downsampled image for visualization, from {original_shape} to {new_shape}'
        )

    # Scale the image to float16 if needed
    if save:
        # When saving, we need float64
        volume = volume.astype(np.float64)
    else:
        if data_type == 'scaled_float16':
            volume = scale_to_float16(volume)
        else:
            volume = volume.astype(data_type)

    # Set color ranges
    color_range = [np.min(volume), np.max(volume)]
    if min_value:
        color_range[0] = min_value
    if max_value:
        color_range[1] = max_value

    # Handle the different formats that colormap can take
    if colormap:
        if isinstance(colormap, str):
            colormap = plt.get_cmap(colormap)  # Convert to Colormap object
        if isinstance(colormap, Colormap):
            # Convert to the format of colormap required by k3d.volume
            attr_vals = np.linspace(0.0, 1.0, num=colormap.N)
            rgb_vals = colormap(np.arange(0, colormap.N))[:, :3]
            colormap = np.column_stack((attr_vals, rgb_vals)).tolist()

    # Default k3d.volume settings
    interpolation = True

    if constant_opacity:
        log.warning(
            'Deprecation warning: Keyword argument "constant_opacity" is deprecated and will be removed next release. Instead use opacity_function="constant".'
        )
        # without these settings, the plot will look bad when colormap is created with qim3d.viz.colormaps.objects
        opacity_function = [0.0, float(constant_opacity), 1.0, float(constant_opacity)]
        interpolation = False
    else:
        if opacity_function == 'constant':
            # without these settings, the plot will look bad when colormap is created with qim3d.viz.colormaps.objects
            opacity_function = [0.0, float(True), 1.0, float(True)]
            interpolation = False
        elif opacity_function is None:
            opacity_function = []

    # Create the volume plot
    plt_volume = k3d.volume(
        volume,
        bounds=(
            [0, volume.shape[2], 0, volume.shape[1], 0, volume.shape[0]]
            if aspectmode.lower() == 'data'
            else None
        ),
        colormap=colormap,
        samples=samples,
        color_range=color_range,
        opacity_function=opacity_function,
        interpolation=interpolation,
    )
    plot = k3d.plot(grid_visible=grid_visible, **kwargs)
    plot += plt_volume
    plot.camera_mode = camera_mode
    if save:
        # Save html to disk
        with open(str(save), 'w', encoding='utf-8') as fp:
            fp.write(plot.get_snapshot())

    if show:
        plot.display()
    else:
        return plot

qim3d.viz.colormaps.qim module-attribute

qim = from_list('qim', [(0.6, 0.0, 0.0), (1.0, 0.6, 0.0)])

Defines colormap in QIM logo colors. Can be accessed as module attribute or easily by cmap = 'qim'

Example

import qim3d

display(qim3d.viz.colormaps.qim)

qim3d.viz.colormaps.segmentation

segmentation(n_labels, style='bright', first_color_background=True, last_color_background=False, background_color=(0.0, 0.0, 0.0), min_dist=0.5, seed=19)

Creates a randomized matplotlib colormap optimized for visualizing segmentation masks.

Generates a set of distinct colors to differentiate between multiple labels or objects in a volume. It supports various color palettes and allows specific control over background colors to ensure clear separation between classes.

Key Features:

• Distinct Palettes: Choose from 'bright', 'soft', 'earth', or 'ocean' styles.
• Contrast Control: Ensure neighboring labels are distinguishable with the min_dist parameter.
• Background Handling: Explicitly set background colors (black/white) to transparency or neutral tones.

Parameters:

Name	Type	Description	Default
n_labels	int	Total number of distinct labels or classes.	required
style	str	The color theme of the map. 'bright': High saturation colors for maximum contrast. 'soft': Pastel tones for a gentler visualization. 'earth': Nature-inspired tones (greens, browns). 'ocean': Cool tones (blues, purples).	'bright'
first_color_background	bool	If True, sets the first color (index 0) to background_color.	True
last_color_background	bool	If True, sets the last color to background_color.	False
background_color	tuple or str	The RGB tuple or string ('black', 'white') for the background.	(0.0, 0.0, 0.0)
min_dist	float	Minimum perceptual distance between adjacent colors in the map. Higher values reduce the chance of similar colors appearing next to each other.	0.5
seed	int	Seed for the random number generator to ensure reproducibility.	19

Returns:

Name	Type	Description
color_map	LinearSegmentedColormap	The generated matplotlib colormap object.

Tip

It can be easily used when calling visualization functions as:

qim3d.viz.slices_grid(segmented_volume, color_map = 'objects')

which automatically detects the number of unique classes and creates the colormap object with default arguments.

Tip

The min_dist parameter can be used to control the distance between neighboring colors.

Example

import qim3d

cmap_bright = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'bright', first_color_background=True, background_color="black", min_dist=0.7)
cmap_soft = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'soft', first_color_background=True, background_color="black", min_dist=0.2)
cmap_earth = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'earth', first_color_background=True, background_color="black", min_dist=0.8)
cmap_ocean = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'ocean', first_color_background=True, background_color="black", min_dist=0.9)

display(cmap_bright)
display(cmap_soft)
display(cmap_earth)
display(cmap_ocean)

import qim3d

vol = qim3d.examples.cement_128x128x128
binary = qim3d.filters.gaussian(vol, sigma = 2) < 60
labeled_volume, n_labels = qim3d.segmentation.watershed(binary)

color_map = qim3d.viz.colormaps.segmentation(n_labels, style = 'bright')
qim3d.viz.slicer(labeled_volume, slice_axis = 1, color_map=color_map)

Source code in qim3d/viz/colormaps/_segmentation.py

def segmentation(
    n_labels: int,
    style: str = 'bright',
    first_color_background: bool = True,
    last_color_background: bool = False,
    background_color: Union[Tuple[float, float, float], str] = (0.0, 0.0, 0.0),
    min_dist: int = 0.5,
    seed: int = 19,
) -> LinearSegmentedColormap:
    """
    Creates a randomized matplotlib colormap optimized for visualizing segmentation masks.

    Generates a set of distinct colors to differentiate between multiple labels or objects in a volume. It supports various color palettes and allows specific control over background colors to ensure clear separation between classes.

    **Key Features:**

    * **Distinct Palettes:** Choose from 'bright', 'soft', 'earth', or 'ocean' styles.
    * **Contrast Control:** Ensure neighboring labels are distinguishable with the `min_dist` parameter.
    * **Background Handling:** Explicitly set background colors (black/white) to transparency or neutral tones.

    Args:
        n_labels (int): Total number of distinct labels or classes.
        style (str, optional): The color theme of the map.

            * `'bright'`: High saturation colors for maximum contrast.
            * `'soft'`: Pastel tones for a gentler visualization.
            * `'earth'`: Nature-inspired tones (greens, browns).
            * `'ocean'`: Cool tones (blues, purples).

        first_color_background (bool, optional): If `True`, sets the first color (index 0) to `background_color`.
        last_color_background (bool, optional): If `True`, sets the last color to `background_color`.
        background_color (tuple or str, optional): The RGB tuple or string ('black', 'white') for the background.
        min_dist (float, optional): Minimum perceptual distance between adjacent colors in the map. Higher values reduce the chance of similar colors appearing next to each other.
        seed (int, optional): Seed for the random number generator to ensure reproducibility.

    Returns:
        color_map (matplotlib.colors.LinearSegmentedColormap):
            The generated matplotlib colormap object.

    Tip:
        It can be easily used when calling visualization functions as:
        ```python
        qim3d.viz.slices_grid(segmented_volume, color_map = 'objects')
        ```
        which automatically detects the number of unique classes and creates the colormap object with default arguments.

    Tip:
        The `min_dist` parameter can be used to control the distance between neighboring colors.
        ![colormap objects mind_dist](../../assets/screenshots/viz-colormaps-min_dist.gif)

    Example:
        ```python
        import qim3d

        cmap_bright = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'bright', first_color_background=True, background_color="black", min_dist=0.7)
        cmap_soft = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'soft', first_color_background=True, background_color="black", min_dist=0.2)
        cmap_earth = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'earth', first_color_background=True, background_color="black", min_dist=0.8)
        cmap_ocean = qim3d.viz.colormaps.segmentation(n_labels=100, style = 'ocean', first_color_background=True, background_color="black", min_dist=0.9)

        display(cmap_bright)
        display(cmap_soft)
        display(cmap_earth)
        display(cmap_ocean)
        ```
        ![colormap objects](../../assets/screenshots/viz-colormaps-objects-all.png)

        ```python
        import qim3d

        vol = qim3d.examples.cement_128x128x128
        binary = qim3d.filters.gaussian(vol, sigma = 2) < 60
        labeled_volume, n_labels = qim3d.segmentation.watershed(binary)

        color_map = qim3d.viz.colormaps.segmentation(n_labels, style = 'bright')
        qim3d.viz.slicer(labeled_volume, slice_axis = 1, color_map=color_map)
        ```
        ![colormap objects](../../assets/screenshots/viz-colormaps-objects.gif)
    """
    from skimage import color

    # Check style
    if style not in ('bright', 'soft', 'earth', 'ocean'):
        raise ValueError(
            f'Please choose "bright", "soft", "earth" or "ocean" for style in qim3dCmap not "{style}"'
        )

    # Translate strings to background color
    color_dict = {'black': (0.0, 0.0, 0.0), 'white': (1.0, 1.0, 1.0)}
    if not isinstance(background_color, tuple):
        try:
            background_color = color_dict[background_color]
        except KeyError:
            raise ValueError(
                f'Invalid color name "{background_color}". Please choose from {list(color_dict.keys())}.'
            )

    # Add one to n_labels to include the background color
    n_labels += 1

    # Create a new random generator, to locally set seed
    rng = np.random.default_rng(seed)

    # Generate color map for bright colors, based on hsv
    if style == 'bright':
        randHSVcolors = [
            (
                rng.uniform(low=0.0, high=1),
                rng.uniform(low=0.4, high=1),
                rng.uniform(low=0.9, high=1),
            )
            for i in range(n_labels)
        ]

        # Convert HSV list to RGB
        randRGBcolors = []
        for HSVcolor in randHSVcolors:
            randRGBcolors.append(
                colorsys.hsv_to_rgb(HSVcolor[0], HSVcolor[1], HSVcolor[2])
            )

    # Generate soft pastel colors, by limiting the RGB spectrum
    if style == 'soft':
        low = 0.6
        high = 0.95
        randRGBcolors = [
            (
                rng.uniform(low=low, high=high),
                rng.uniform(low=low, high=high),
                rng.uniform(low=low, high=high),
            )
            for i in range(n_labels)
        ]

    # Generate color map for earthy colors, based on LAB
    if style == 'earth':
        randLABColors = [
            (
                rng.uniform(low=25, high=110),
                rng.uniform(low=-120, high=70),
                rng.uniform(low=-70, high=70),
            )
            for i in range(n_labels)
        ]

        # Convert LAB list to RGB
        randRGBcolors = []
        for LabColor in randLABColors:
            randRGBcolors.append(color.lab2rgb([[LabColor]])[0][0].tolist())

    # Generate color map for ocean colors, based on LAB
    if style == 'ocean':
        randLABColors = [
            (
                rng.uniform(low=0, high=110),
                rng.uniform(low=-128, high=160),
                rng.uniform(low=-128, high=0),
            )
            for i in range(n_labels)
        ]

        # Convert LAB list to RGB
        randRGBcolors = []
        for LabColor in randLABColors:
            randRGBcolors.append(color.lab2rgb([[LabColor]])[0][0].tolist())

    # Re-arrange colors to have a minimum distance between neighboring colors
    randRGBcolors = rearrange_colors(randRGBcolors, min_dist)

    # Set first and last color to background
    if first_color_background:
        randRGBcolors[0] = background_color

    if last_color_background:
        randRGBcolors[-1] = background_color

    # Create colormap
    objects = LinearSegmentedColormap.from_list('objects', randRGBcolors, N=n_labels)

    return objects