Show3D#

class quantem.widget.Show3D(**kwargs: Any)[source]#

Bases: AnyWidget

Interactive 3D stack viewer with advanced features for electron microscopy.

View a stack of 2D images along a specific dimension (e.g., defocus sweep, time series, depth stack, in-situ movies). Includes playback controls, statistics panel, ROI selection, FFT view, and more.

Parameters:

data (array_like) – 3D array of shape (N, height, width) where N is the stack dimension.
labels (list of str, optional) – Labels for each slice (e.g., [“C10=-500nm”, “C10=-400nm”, …]). If None, uses slice indices.
title (str, optional) – Title to display above the image.
cmap (str or Colormap, default Colormap.MAGMA) – Colormap name. Use Colormap enum (Colormap.MAGMA, Colormap.VIRIDIS, etc.) or string (“magma”, “viridis”, “gray”, “inferno”, “plasma”).
vmin (float, optional) – Minimum value for colormap. If None, uses data min.
vmax (float, optional) – Maximum value for colormap. If None, uses data max.
pixel_size (float, optional) – Pixel size in Å for scale bar display.
log_scale (bool, default False) – Use log scale for intensity mapping.
auto_contrast (bool, default False) – Use percentile-based contrast (ignores vmin/vmax).
percentile_low (float, default 1.0) – Lower percentile for auto-contrast.
percentile_high (float, default 99.0) – Upper percentile for auto-contrast.
fps (float, default 5.0) – Frames per second for playback.
timestamps (list of float, optional) – Timestamps for each frame (e.g., seconds or dose values).
timestamp_unit (str, default "s") – Unit for timestamps (e.g., “s”, “ms”, “e/A2”).
disabled_tools (list of str, optional) – Tool groups to lock while still showing controls. Supported: "display", "histogram", "stats", "playback", "view", "export", "roi", "profile", "all". "navigation" is accepted as an alias of "playback".
disable_* (bool, optional) – Convenience flags mirroring disabled_tools. Includes disable_navigation as an alias of disable_playback.
hidden_tools (list of str, optional) – Tool groups to hide from the UI. Uses the same keys as disabled_tools.
hide_* (bool, optional) – Convenience flags mirroring disable_* for hidden_tools.

Examples

>>> import numpy as np
>>> from quantem.widget import Show3D
>>>
>>> # View defocus sweep
>>> labels = [f"C10={c10:.0f}nm" for c10 in np.linspace(-500, -200, 12)]
>>> Show3D(stack, labels=labels, title="Defocus Sweep")
>>>
>>> # View in-situ movie with timestamps
>>> times = np.arange(100) * 0.1  # 100 frames at 10 fps
>>> Show3D(movie, timestamps=times, timestamp_unit="s", fps=30)
>>>
>>> # With scale bar
>>> Show3D(data, pixel_size=0.5, title="HRTEM")

Key Methods

Show3D.set_image(data, labels=None)[source]#: Replace the stack data. Preserves all display settings.

Show3D.save_image(path: str | Path, *, frame_idx: int | None = None, format: str | None = None, dpi: int = 150) → Path[source]#

Save a single frame as PNG, PDF, or TIFF.

Parameters:

path (str or pathlib.Path) – Output file path.
frame_idx (int, optional) – Frame index to export. Defaults to current slice_idx.
format (str, optional) – ‘png’, ‘pdf’, or ‘tiff’. If omitted, inferred from file extension.
dpi (int, default 150) – Output DPI metadata.

Returns:

The written file path.

Return type:

pathlib.Path

Playback

Show3D.play() → Self[source]#: Start playback.

Show3D.pause() → Self[source]#: Pause playback.

Show3D.stop() → Self[source]#: Stop playback and reset to beginning.

Show3D.goto(index: int) → Self[source]#: Jump to a specific frame index.

Show3D.set_playback_path(path) → Self[source]#: Set custom playback order (list of frame indices).

Show3D.clear_playback_path() → Self[source]#: Clear custom playback path (revert to sequential).

Line Profile

Show3D.profile_all_frames(start: tuple | None = None, end: tuple | None = None) → ndarray[source]#

Extract the line profile from every frame, returning (n_slices, n_points).

Uses the current profile_line unless start/end are provided. Always samples raw data (ignores diff_mode).

Parameters:

start (tuple of (row, col), optional) – Start point. Overrides current profile_line.
end (tuple of (row, col), optional) – End point. Overrides current profile_line.

Returns:

Shape (n_slices, n_points) float32 array.

Return type:

np.ndarray

Show3D.set_profile(start: tuple, end: tuple) → Self[source]#

Set a line profile between two points (image pixel coordinates).

Parameters:

start (tuple of (row, col)) – Start point in pixel coordinates.
end (tuple of (row, col)) – End point in pixel coordinates.

Show3D.clear_profile() → Self[source]#: Clear the current line profile.

ROI

Show3D.add_roi(row: int | None = None, col: int | None = None, shape: str = 'square') → Self[source]#

Show3D.set_roi(row: int, col: int, radius: int = 10) → Self[source]#: Set selected ROI position and size (creates one if needed).

Show3D.clear_rois() → Self[source]#

Show3D.delete_selected_roi() → Self[source]#: Delete the currently selected ROI.

Show3D.duplicate_selected_roi(row_offset: int = 3, col_offset: int = 3) → Self[source]#: Duplicate selected ROI with a small offset and auto-assigned color.

Show3D.roi_circle(radius: int = 10) → Self[source]#: Set selected ROI shape to circle.

Show3D.roi_square(half_size: int = 10) → Self[source]#: Set selected ROI shape to square.

Show3D.roi_rectangle(width: int = 20, height: int = 10) → Self[source]#: Set selected ROI shape to rectangle.

Show3D.roi_annular(inner: int = 5, outer: int = 10) → Self[source]#: Set selected ROI shape to annular (donut).

State Persistence

Show3D.state_dict()[source]#

Show3D.save(path: str)[source]#

Show3D.load_state_dict(state)[source]#

Show3D.summary()[source]#

Show3D#

This Page