Show3DSlices

Show3DSlices#

Linked top and arbitrary-angle side cuts through a 3D volume. See the Show3DSlices tutorial.

Viewer UI#

Show3DSlices takes the shared show_title and show_scale_bar names at construction; show_controls, controls_collapsed and show_crosshair are synced traits set after construction, as the browser controls do. The saved-state scale-bar trait is show_scale_bar. See Viewer UI controls.

Reference#

class quantem.widget.show3dslices.Show3DSlices(*args: t.Any, **kwargs: t.Any)#

Bases: StateFileMixin, HtmlExportMixin, AnyWidget

Linked top-slice and oblique vertical-slice viewer for 3D volumes.

Parameters:

  • data (array_like or Dataset3d) – (slices, rows, cols) volume, (panel, slices, rows, cols) panels, or pages: (page, panel, slices, rows, cols), or (page, slices, rows, cols) together with page_labels. A Dataset3d supplies title, sampling and units.

  • title (str) – Title above the viewer.

  • panel_titles (sequence of str, optional) – One title per panel (or per panel slot for pages).

  • page_labels (sequence of str, optional) – One label per page. Page switching keeps the slice geometry, zoom and display settings so depths compare directly.

  • show_title (bool) – Show the title row.

  • cmap (str) – Colormap for every panel.

  • sampling (float or (slice, row, col), optional) – Voxel sampling for the scale bars, paired with units.

  • units (str or sequence of str, optional) – Unit of sampling ("A" or "nm"); one value applies to every axis. Angstrom when omitted.

  • show_scale_bar (bool) – Draw calibrated scale bars when a sampling is known.

  • slice_stretch (float) – Display stretch of the depth axis, 1 to 50, for volumes with far fewer slices than lateral pixels.

  • panel_width_px (int) – Display width per panel in CSS pixels; 0 uses the frontend default.

  • show_fft (bool) – Show the power spectrum of the active plane.

  • fft_window (bool) – Hann-window each plane before its FFT to suppress edge streaks.

  • smooth (bool) – Bilinear interpolation when the canvas enlarges a slice. Default False paints every data pixel as a sharp block (nearest neighbour).

  • auto_contrast (bool) – Percentile contrast (image_vmin_pct to image_vmax_pct); long-tailed phase histograms are crushed by the raw min/max. Applies only while vmin and vmax are both None.

  • vmin (float, optional) – Manual contrast limits, used exactly as given: setting either one turns Auto off for the display, so the window is never narrowed to percentiles.

  • vmax (float, optional) – Manual contrast limits, used exactly as given: setting either one turns Auto off for the display, so the window is never narrowed to percentiles.

  • image_vmin_pct (float) – Percentiles for the automatic contrast window.

  • image_vmax_pct (float) – Percentiles for the automatic contrast window.

  • slice_alignment ({"off", "auto", "manual"}) – Display-only global post-alignment. "auto" estimates one row/col shift per slice from adjacent-slice registration; the raw volume is never modified.

  • dim_labels (list of str, optional) – Names of axes 0, 1, 2; default ["slice", "row", "col"].

  • offline (bool) – Pack the volume as uint8 against its global range (256 levels) for small standalone HTML, and print one line saying so; False keeps exact float32 in the browser.

Flatten the volume to (panel, slices, rows, cols) float32 and send it with the display traits in one sync.

estimate_slice_alignment(*, panel: int | None = None, apply: bool = True, force: bool = False) → dict#

Fit one global row/col display shift per slice for a panel.

See alignment.estimate_global_slice_alignment for the method. The estimate is cached per panel so the Align toggle in the browser does not re-register the stack on every raw/aligned switch; force recomputes. With apply the slopes are written to row_shift_px_per_slice / col_shift_px_per_slice and slice_alignment becomes "auto".

reset_slice_alignment() → Self#

Turn off post-alignment and discard the cached estimates.

state_dict() → dict#

JSON-serializable snapshot of every user-tunable trait (no pixels).

load_state_dict(state: dict | str | Path) → None#

Apply a state_dict snapshot, its envelope or a save file onto this widget’s volume.

Page topology comes from the data, so n_pages / panels_per_page are not part of the state and labels of the wrong length are dropped. vmin / vmax are cleared first so either bound can land regardless of the current limits. A file of another schema or an unknown key raises before anything is applied.

free() → None#

Release the volume and its synced bytes.

del widget alone does not free memory: traitlets observers pin the widget’s refcount. Playback is stopped first so the browser’s animation loop tears down before the buffer it reads goes away. Idempotent.

export_html(path: str | Path | None = None, *, title: str | None = None, encoding: str = 'full') → Path#

Write a standalone HTML viewer that opens with no kernel and no network.

encoding="full" embeds the exact float32 volume; "uint8" packs it against the global range for a file about a quarter the size. The default path is the kernel cwd with the title, volume shape and encoding in the name.

Interactive controls#

Control

Trait

Expected effect

Page slider / play

page_idx, n_pages, page_labels

Switches or plays comparable volumes while preserving the same slice geometry and view state

Panel menu

active_panel, panels_per_page, panel_titles

Selects one panel slot within the active page

Crosshair drag

col_index, row_index, slice_index

Moves the cut position; all panels update together

Oblique line drag

oblique_profile_line, oblique_angle, col_index, row_index

Drag either endpoint to rotate/resize the side cut, or drag the line body to translate the whole cut freely in row/col while staying inside the top slice

Oblique angle

oblique_angle

Rotates the oblique cut plane

Colormap dropdown

cmap

Recolors all panels

Contrast min / max

vmin, vmax

The display window, used exactly as given; while either is set, Auto is off and its switch is disabled

Auto-contrast toggle

auto_contrast

Re-fits the 2/98 percentile range of the volume; only when vmin and vmax are both None

Log-scale toggle

log_scale

Log intensity mapping

Smooth toggle

smooth

Off by default: each voxel of a slice is drawn as a sharp block (nearest neighbour). On: bilinear interpolation where the canvas enlarges a slice. Display only

Slice alignment

slice_alignment, row_shift_px_per_slice, col_shift_px_per_slice

Open Advanced and enable Slice alignment. The first enable estimates one global row/col shift per slice automatically; later raw/aligned toggles reuse the cached estimate and aligned display volume. The sliders refine the cached result without modifying the raw volume.

FFT toggle

show_fft, fft_window

Panels show power spectra

Z-stretch

slice_stretch

Depth axis scaled for anisotropic voxels

Scale bar toggle

show_scale_bar

Calibrated bar shows/hides

Export button

export_request, export_status

Writes a standalone HTML viewer (exact / quantized)

Automatic slice alignment (quantem.widget.show3dslices.alignment) high-pass filters adjacent reconstructed slices with a Gaussian sigma capped at 12 pixels, then refines each translation on a 20x local matrix-DFT grid. The 12-pixel scale is an empirical preprocessing setting, not a physical microscope parameter. The subpixel method follows Guizar-Sicairos, Thurman, and Fienup (2008), DOI 10.1364/OL.33.000156. The resulting row/col trajectory is reduced to one global linear shift per slice. This is reversible display post-processing; it does not add sample tilt to the ptychographic forward model or modify the reconstructed volume.

Compare volumes with pages#

Pass a 4D stack plus page_labels when every page contains one volume. The same top slice, side cut, oblique angle, zoom, contrast, and playback settings remain active as the page changes:

# Shape: page, depth, rows, cols
w = Show3DSlices(
    np.stack([raw_volume, aligned_volume]),
    page_labels=["raw", "aligned"],
    panel_titles=["object phase"],
)

Use a 5D array when each page has the same small panel set:

# Shape: page, panel, depth, rows, cols
w = Show3DSlices(
    comparison_5d,
    page_labels=["single-slice", "multislice"],
    panel_titles=["object", "absolute error"],
)

Set page_idx to switch pages from Python. A 4D array without page_labels is a multi-panel volume, as before.