Show3D#

Interactive 3D stack viewer with playback, multi-ROI analysis, FFT, and export.

Usage#

import numpy as np
from quantem.widget import Show3D

stack = np.random.rand(50, 256, 256)
Show3D(stack, title="My Stack", fps=10, cmap="gray")

# With timestamps
defocus = np.linspace(-60, 60, 50)
Show3D(
    stack,
    labels=[f"C10={d:.0f} nm" for d in defocus],
    pixel_size=2.5,
    timestamps=defocus.tolist(),
    timestamp_unit="nm",
)

Features#

  • Playback — Play/pause/stop with configurable FPS, loop, boomerang modes

  • ROI analysis — Multiple ROIs (circle, square, rectangle, annular) with live stats

  • ROI interaction — Click empty image to add ROI at cursor, Delete selected, duplicate selected, hover edge to resize

  • ROI legend — Per-ROI visibility, lock state, focus toggle, and live stats for quick comparison

  • Focus mode — Adjustable dim strength outside focused ROIs

  • FFT — Toggle Fourier transform display

  • Histogram — Live intensity histogram

  • Scale bar — Calibrated scale bar when pixel_size is set

  • Export — Figure/frame PNG, GIF, PNG ZIP, and one-click bundle export (PNG + ROI CSV + state JSON)

  • File/folder loading — Use IO.file() / IO.folder() for any EM format

  • Tool customization — Disable or hide control groups (including playback)

File Loading#

from quantem.widget import IO, Show3D

# Single file (any format: PNG, TIFF, EMD, DM3/DM4, MRC, SER, NPY)
Show3D(IO.file("data/focal_series.tiff"))

# Folder of images
Show3D(IO.folder("data/png_stack", file_type="png"))

Methods#

w = Show3D(stack)

# Playback
w.play()
w.pause()
w.stop()
w.goto(25)  # Jump to frame 25
w.set_playback_path([0, 10, 20, 10, 0])  # Custom frame order

# ROI analysis (multi-ROI)
w.add_roi(shape="circle")                 # add at center
w.add_roi(row=96, col=128, shape="annular")
w.roi_selected_idx = 0                    # edit selected ROI
w.set_roi(row=128, col=128, radius=20)    # helper for selected ROI
w.roi_circle(radius=15)
w.roi_square(half_size=10)
w.roi_rectangle(width=20, height=10)
w.roi_annular(inner=5, outer=15)
w.duplicate_selected_roi()
w.delete_selected_roi()
w.clear_rois()
w.roi_list
w.roi_stats

# Line profile
w.set_profile((10, 10), (200, 200))
w.clear_profile()

# Export from toolbar: Figure/PNG/GIF/ZIP/Bundle

Control Groups#

# Lock groups (visible but non-interactive)
w = Show3D(
    stack,
    disable_display=True,
    disable_playback=True,   # disable_navigation also works
    disable_roi=True,
)

# Hide groups entirely
w = Show3D(
    stack,
    hide_histogram=True,
    hide_stats=True,
    hidden_tools=["profile"],
)

State Persistence#

w = Show3D(stack, cmap="gray", fps=12, boomerang=True)
w.bookmarked_frames = [0, 15, 29]

w.summary()          # Print human-readable state
state = w.state_dict()  # Snapshot full state
w.save("state.json") # Save versioned envelope JSON file

# Restore in three ways
w.load_state_dict(state)               # 1) apply dict in-place
w2 = Show3D(stack, state="state.json") # 2) from saved file
w3 = Show3D(stack, state=state)        # 3) from dict at init

Examples#

API Reference#

See quantem.widget.Show3D for full documentation.