Show3D

Show3D scrubs a 3D stack slice by slice: a focal series, time series, tomographic reconstruction, or a sequence of related images. Drag the slider, press the play controls, or use the arrow keys to move through the stack.

This tutorial uses a real gold HAADF image from bobleesj/quantem-data. show3d_gold(size="small") makes a calibrated moving-crop stack from that image, so the documentation and Colab examples use real microscope data while still loading quickly.

Tip

Run this exact notebook with the Colab badge above, or View or download this notebook on GitHub. For finished results, use HTML and file export to export interactive HTML or share a trusted notebook with widget state.

import quantem.widget as qw
qw.profile()

import numpy as np
import torch

from quantem.widget import Show3D
from quantem.widget.datasets import show3d_gold

volume_dataset = show3d_gold(size="small")

quantem.widget  0.0.1rc39
  install       editable checkout
quantem.gpu     0.0.1rc8
  install       published package
quantem         0.1.9
torch           2.14.1+cu130  device=cpu
python          3.12.15

Source: gold-haadf (widget-tutorials/shared) from Hugging Face
Full image: 4096 x 4096 uint16
Stack: (32, 256, 256), stride 8, pixel size 0.1489 nm

Scrub the real-data stack

The helper returns a quantem Dataset3d, so depth and lateral calibration travel with the stack. Show3D reads that metadata automatically and draws a physical scale bar without widget-level pixel-size arguments. Here the FFT starts at 2.0×; every FFT tile or inset keeps its live N.N× multiplier visible while you zoom.

stack = Show3D(volume_dataset, show_fft=True, fft_layout="right", fft_overlay_zoom=2.0)
stack

  Display bin 4×: 256×256 → 64×64

Compare one plane with a moving average

Set Avg to 3 or 4, scrub, and press Play. This is a moving mean, not a depth projection or a reconstruction update. The centered window shifts inward at the ends, without wrapping or shortening: with Avg 3, centers 0 and 1 use frames 0–2; center 2 uses 1–3. Return to Avg 1 to inspect individual planes. The source array remains unchanged.

This demonstration stack contains moving crops, not measured depth slices. Apply the same controls to your own (depth, row, col) volume to inspect depth. For an actual projected phase, first check whether your array stores phase per plane or potential requiring an interaction constant and thickness conversion; averaging is not interchangeable with summing.

stack.avg_window = 3

Page through related 3D views

Pages are useful when every parameter value has the same multi-panel movie layout. This synthetic torch example keeps the notebook light and fast while exercising the same paged Show3D controls used for real reconstruction sweeps.

Show code cell source

Hide code cell source

torch.manual_seed(4)
page_labels = ["lambda 0.01", "lambda 0.03", "lambda 0.10"]
panel_titles = ["raw", "filtered", "residual", "probe"]

frames, n = 16, 144
t = torch.linspace(0, 1, frames)[:, None, None]
y, x = torch.meshgrid(
    torch.linspace(-1, 1, n),
    torch.linspace(-1, 1, n),
    indexing="ij",
)
x = x[None]
y = y[None]
center_x = -0.45 + 0.90 * t
center_y = 0.18 * torch.sin(2 * torch.pi * t)
base_stack = torch.exp(-((x - center_x) ** 2 + (y - center_y) ** 2) / 0.060)
base_stack += 0.45 * torch.exp(-((x + 0.28) ** 2 + (y + 0.35) ** 2) / 0.035)
base_stack += 0.12 * torch.sin(18 * x + 6 * t) * torch.cos(14 * y)
base_stack = base_stack.to(torch.float32)

page_stacks = []
for lam, denoise, artifact_strength in zip([0.01, 0.03, 0.10], [0.15, 0.42, 0.70], [0.20, 0.10, 0.03]):
    noise = artifact_strength * torch.randn_like(base_stack)
    drift = artifact_strength * torch.sin((16 + 80 * lam) * x + 4 * t) * torch.cos(12 * y)
    raw = base_stack + noise + drift
    filtered = (1 - denoise) * raw + denoise * base_stack.mean(dim=0, keepdim=True)
    residual = raw - filtered
    probe = torch.roll(base_stack, shifts=int(90 * lam), dims=2) + 0.4 * lam * torch.cos(24 * x) * torch.cos(24 * y)
    page_stacks.append(torch.stack([raw, filtered, residual, probe]))
page_stacks = torch.stack(page_stacks).numpy().astype(np.float32)

paged_show3d = Show3D(
    page_stacks,
    panel_titles=panel_titles,
    page_labels=page_labels,
    max_cols=4,
    sampling=0.03,
    units="nm",
    show_fft=False,
    link_contrast=False,
)
paged_show3d.star_page(1)
paged_show3d

  Multi-panel display bin 4x before concat: 144x144 -> 36x36 per panel

Trigger a fresh render in an existing widget

For live stacks, display one Show3D object and update it with set_image() as new frames arrive. set_image() is the render trigger: it writes a fresh current-frame transfer, bumps the frame sequence used by the frontend renderer, invalidates playback buffers, and clamps the current slice to the new stack.

In a real acquisition loop, pass offline=False so frames stream from the kernel instead of being re-embedded on every append:

live3d = Show3D(np.stack(live_frames), offline=False, fps=4)  # streams, nothing embedded
while acquiring:
    live_frames.append(next_frame())
    live3d.set_image(np.stack(live_frames))

The executed example below keeps the default offline embedding instead, so the widget on this documentation page stays scrubbable without a kernel - the set_image() mechanics are identical either way.

live_frames = [frame for frame in volume_dataset.array[:4]]
live3d = Show3D(
    np.stack(live_frames),
    labels=[f"frame {i + 1}" for i in range(len(live_frames))],
    fps=4,
)
live3d

  Display bin 4×: 256×256 → 64×64

live_frames.extend(volume_dataset.array[4:8])
live3d.set_image(
    np.stack(live_frames),
    labels=[f"frame {i + 1}" for i in range(len(live_frames))],
)
live3d.slice_idx = len(live_frames) - 1