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.1rc44.dev0
  install       editable checkout
  commit        2d009a7f61ee (dirty checkout)
quantem.gpu     0.0.1rc18.dev0
  install       local build
  commit        not recorded
quantem         0.1.10
  install       installed package
  commit        not recorded
webgpu kernels  fa4a86c (fa4a86cfee85), pinned fa4a86cfee85ea719be2dd98206d2098f0dd3344
torch           2.14.1+cu130  device=cpu
python          3.12.15
show3d_gold(size='small') crops from every 8th pixel of the 4096x4096 image; size='full' crops native pixels.
Source: gold_haadf_npy 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.

Each data pixel is drawn as a sharp block (nearest neighbour), also when you zoom in. Switch on Smooth to interpolate bilinearly between pixels; it changes only the display.

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

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

/tmp/ipykernel_2884/1831082897.py:1: DeprecationWarning: max_cols is deprecated; use columns instead. It remains supported during the transition.
  paged_show3d = Show3D(

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 re-embeds the display stack the browser plays from, bumps the frame sequence used by the frontend renderer, and clamps the current slice to the new stack.

live3d = Show3D(np.stack(live_frames), fps=4)
while acquiring:
    live_frames.append(next_frame())
    live3d.set_image(np.stack(live_frames))

Each call re-sends the whole display stack to the browser.

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

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