quantem.widget

Interactive, GPU-accelerated visualization widgets for 4D-STEM and electron microscopy. Use them in Jupyter notebooks, as local HTML files, or from the command line. NumPy, PyTorch, CuPy, CUDA, Apple Silicon, and browser WebGPU workflows are supported.

Demo: Show4DSTEM HTML with WebGPU. Explore live diffraction-pattern and virtual-detector views locally in a browser on a personal laptop or supported phone, without a Python kernel or remote compute server. Thanks to Serin Lee for sharing this liquid-cell Au nanoparticle 4D-STEM dataset. Check Serin's 4D-STEM and 5D-STEM segmentation and clustering work (paper) and the source data (Zenodo).

Start with the documentation to load ARINA 4D-STEM data in Jupyter, open Show4DSTEM, and explore the interactive widgets.

quantem.widget is currently a prototype on TestPyPI. It installs quantem core and its readers return quantem datasets, except on an Intel Mac and Windows on ARM, which cannot install quantem core (see Load data).

Install

Use Python 3.11 or newer and keep both index URLs: QuantEM pre-releases come from TestPyPI; dependencies such as anywidget come from PyPI. Copy the complete line for your machine:

# NVIDIA GPU
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "quantem.widget[cuda]"

# Apple silicon Mac
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "quantem.widget[mps]"

# no GPU, or an Intel Mac
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "quantem.widget[cpu]"

Using uv? In your activated environment, use the same indexes:

uv pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ "quantem.widget[cuda]"

Replace [cuda] with [mps] or [cpu] for the other machines above. An error saying anywidget was not found usually means the PyPI index was omitted. See installation troubleshooting.

Then run import quantem.widget as qw; qw.profile() to see what was installed and which device the widgets will use. What each machine gets and what was tested is on the platform support page.

On Windows, torch needs the Microsoft Visual C++ Redistributable for the architecture of your Python (x64 or ARM64); installing it needs administrator rights. PyPI has no torch for ARM64 Python on Windows on ARM: install it first with pip install torch --index-url https://download.pytorch.org/whl/cpu (Python 3.11 to 3.13). hdf5plugin has no ARM64 wheel, so .npy files and HDF5 files without its filters (uncompressed or gzip) open there, and compressed Arina masters need x64 Python with pip install hdf5plugin. CUDA on Windows is untested.

A wrong pick installs nothing harmful: [cuda] installs nothing extra on a Mac, [mps] nothing outside Apple silicon. Every widget takes device="auto" (CUDA, then Apple MPS, then CPU) and prints the device it chose once. When a GPU is present but its quantem.gpu path is not installed, the widget prints one line with the pip command for that GPU. See the installation guide for Colab instructions and verification.

Load data

The readers return the dataset type of the machine, so the same code runs on every machine:

from quantem.widget import Show2D, Show4DSTEM, io

ds = io.read_image("overview.emd")          # quantem core Dataset2d
arr = ds.array                               # the pixels; ds.sampling and ds.units carry the calibration
Show2D(ds)

data = io.read_4dstem("scan_master.h5")      # Dataset4dstem on a GPU, quantem core Dataset4dstem elsewhere
Show4DSTEM(data)

Data	quantem.gpu and a GPU	No GPU route	Intel Mac, Windows on ARM
4D-STEM file (read_4dstem, datasets.show4dstem_gold)	quantem.gpu.io.Dataset4dstem	quantem core Dataset4dstem	stand-in
Image (read_image, read_images, datasets.show2d_gold)	quantem core Dataset2d	quantem core Dataset2d	stand-in
Image stack (read_image_stack, datasets.show3d_gold)	quantem core Dataset3d	quantem core Dataset3d	stand-in

On a GPU, a 4D-STEM file is a Dataset4dstem, not a torch tensor:

• counts are unsigned (uint16, uint32), and torch cannot add, multiply or take the max of those;
• the file stays compressed in GPU memory (the 512 x 512 x 192 x 192 gold scan: 5.6 GiB, against 18 GiB as dense uint16);
• quantem.gpu's CUDA and Metal kernels decode and sum it exactly in one pass.

Indexing and read(scan_region=...) still return torch tensors.

The stand-in, used where quantem core cannot install, has the same array, name, sampling, units, metadata, shape, ndim and dtype. A color PNG, JPEG or TIFF reads as an RgbImage with array, name, sampling and units, and a folder of color frames as an (N, H, W, 3) array; quantem core has no color-image dataset. Every widget also takes NumPy arrays and torch tensors on any device.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗