quantem.widget

quantem.widget#

Interactive, GPU-aware Python widgets for electron microscopy, built on anywidget. Each widget renders a real-time canvas in JupyterLab, VS Code, or Colab.

from quantem.widget import Show1D, Show2D, Show3D, Show3DSlices, Show4DSTEM, ShowEDS, ShowDiffraction, ShowFolder, load

Quickest start: no notebook needed#

After installing, point the quantem command at a file or folder and it renders the right viewer in your browser:

quantem show2d image.tif         # an image            -> Show2D
quantem show3d ./frames/         # a folder of frames  -> Show3D scrub
quantem show4dstem ./masters/    # 4D-STEM master(s)   -> live viewer (or --html)

It saves to ~/Downloads, opens automatically, and picks the GPU (CUDA / Apple Metal) for you. Full details on the command line page.

Built for two platforms#

We serve two audiences first:

  • macOS on Apple M-chips - the Metal (MPS) GPU.

  • Linux with NVIDIA CUDA - workstations and HPC.

CUDA and MPS are the primary backends. Work stays on the GPU as PyTorch tensors; we avoid NumPy on the hot path. CPU is a fallback, not a target - it runs through the same PyTorch path, just slower. For large datasets, bin the detector at load (det_bin) to cut memory and speed first paint - see Load and I/O.

Widgets#

Widget

Use it for

Tutorial · API

Show1D

Interactive traces, live reconstruction metrics, line profiles, and linked image snapshots

tutorial · API

Show2D

One or many 2D images: contrast, FFT, ROIs, line profiles, scale bars

tutorial · API

Show3D

A 3D volume scrubbed slice-by-slice (e.g. a ptychographic object)

tutorial · API

Show3DSlices

Side-by-side slices of a 3D volume across an axis

tutorial · API

Show4DSTEM

4D-STEM: live virtual detectors over the diffraction stack

tutorial · API

ShowEDS

Experimental EDS/EELS spectrum image: linked element map, spectrum, energy band, and ROI

tutorial · API

ShowDiffraction

2D/3D diffraction d-spacing: Bragg spots, rings, center finding, k calibration

tutorial · API

ShowFolder

Folder-level microscopy browser: navigate a session, review thumbnails, select files/folders, and save curation state

tutorial · API

The Tutorials walk through each widget on real public data where practical, with compact synthetic data only where it keeps an example portable. Real tutorial datasets are downloaded from public data hosting such as Hugging Face and cached locally; they are not committed to this repository or bundled into the Python wheel. That keeps clone size and microscope-PC installs small while still letting the rendered docs use realistic microscopy examples. The ShowFolder tutorial covers folder browsing workflows and how to save and share widget exports. The API reference documents every parameter, method, and interactive control (and doubles as a UI-test spec for automated agents). All example data here is synthetic or pulled from a public Hugging Face dataset - no private data ships in the docs.

Every widget accepts a NumPy array, a PyTorch tensor (CPU or GPU), or a quantem Dataset (Dataset2d / Dataset3d / Dataset4dstem), pulling calibration and units automatically from the dataset when present.

Offline by default in these docs#

The Show2D, Show3D, and Show3DSlices examples on this site were exported with encoding="uint8", which bakes the display data into the widget as a uint8 stack (4x smaller than float32, and the colormap clamps to 256 levels anyway so it looks identical). The canvas below each example stays fully interactive in this static page with no running kernel: scrub, zoom, change contrast, toggle the FFT - all in the browser. Show4DSTEM goes further: for a small dataset its virtual-detector math runs in WebGPU, so dragging the aperture recomputes the virtual image in the browser. The browser stack is uint8-clipped for transport, so it is exact for detector counts <=255; use the CUDA/MPS kernel path when full uint16 count fidelity matters.

ShowEDS uses the same saved-widget model for synthetic and small cubes in single mode with exact data. For large native EDS/EELS files, the notebook keeps the interactive state while the exact count data stays in a data folder. Portable HTML demos can be exported with count-preserving sum downsampling when full-resolution data would be too large for public sharing.

See Installation to get started.

Getting help#