ShowFolder

Use ShowFolder when you want a notebook widget for browsing an electron microscopy session folder before loading the heavy data. ShowFolder is the public folder-level API, matching the Show2D / Show3D naming style.

from quantem.widget import ShowFolder, prebuild_showfolder_cache, show_folder

w = ShowFolder("/data/session", group_by="fov")
w

ShowFolder is designed as a look-before-you-load browser. The first run scans the folder, builds calibrated thumbnails, and writes a small thumbnail/index cache in the user cache directory by default. The second run validates file path, size, and modification time, then reuses the cached thumbnails so users can browse large microscopy sessions quickly without loading full arrays again. The inventory includes per-pixel dwell time in microseconds when Velox records Scan.DwellTime. AutoExport TIFFs inherit it only from an exact matching EMD stem in the same folder or its parent; unmatched TIFFs remain blank.

w = ShowFolder("/data/session", thumb=256, group_by="fov")
w.cache_info
# {'enabled': True, 'hits': ..., 'misses': ..., 'path': ...}

Use cache="folder" when you want a project-local cache under .quantem/showfolder-cache, cache_dir="/fast/ssd/cache" for a shared SSD cache, rebuild_cache=True to force regeneration, or cache=False for a read-only/no-cache browser.

For large folders, warm the cache before opening the browser UI:

prebuild_showfolder_cache("/data/session", thumb=256, cache_dir="/fast/ssd/cache")
w = ShowFolder("/data/session", thumb=256, cache_dir="/fast/ssd/cache")

For folders that are still being written, start the watcher. It polls for new, changed, or removed files; reuses cached thumbnails for unchanged files; updates the displayed browser in place; and shows a small status line such as 2 cached · 1 read · 1 new.

w = ShowFolder("/data/live-session", thumb=256, cache_dir="/fast/ssd/cache")
w.watch(interval=2.0)

Use watch_once() in scripts or tests when you want one deterministic poll, and stop_watch() before shutting down a long-running notebook kernel.

ShowFolder owns watching for its thumbnail browser and selection workflow. When a viewer should follow scientific source data directly, use Show2D.from_folder(...), Show3D.from_folder(...), or Show4DSTEM.from_folder(...); those APIs have their own default watcher and do not depend on ShowFolder. Image selections opened through ShowFolder still update its active Show2D/Show3D viewer in place. For 4D-STEM selections, ShowFolder tracks *_master.h5 files and refreshes the active lazy Show4DSTEM view with the same paging options. The first dataset paints immediately; when the complete known shape/dtype footprint fits the selected GPUs, the remaining unhidden datasets preload in the background. Larger folders remain full-resolution and lazy.

stem = w.open_show4dstem(
    gpus=[0, 1],
    page_budget="auto",
    preload_all_if_fits=True,
)
stem.wait_for_dataset_preload(timeout=120)  # optional deterministic wait

Set preload_all_if_fits=False to force page-on-demand loading. The automatic fit check does not silently bin or narrow data; det_bin= and dtype= remain explicit scientific choices.

For acquisition folders where every new image should appear immediately, open both all-image viewers before starting the watcher:

w = ShowFolder("/data/live-session", thumb=256, group_by="none")
w.open_both(all_images=True)  # one live Show2D gallery and one live Show3D stack
w.watch(interval=2.0)

Use open_show2d(all_images=True) or open_show3d(all_images=True) when only one view is useful. Open All Both in the selection panel performs the same dual-view operation without Python calls.

The equivalent CLI shortcuts write that live notebook for you:

quantem show2d /data/live-session --watch
quantem show3d /data/live-session --watch

Folders with *_master.h5 files also show a 4D-STEM master QC table. This is a header-only readiness check: it opens the HDF5 headers, verifies inline or linked data chunks, and reports scan shape, detector shape, dtype, missing chunks, and the next step. It does not decompress detector frames or allocate GPU memory.

w.master_qc_rows
# [{'file': 'scan_000_master.h5', 'status': 'ready', ...}, ...]

Use these rows to decide whether a master is ready for Show4DSTEM or whether you should wait for sibling data files to finish copying. The status values are "ready", "incomplete", and "bad".

If you do not pass a path, ShowFolder() displays a folder chooser first:

w = show_folder()
w

After users star image panels, the Python object exposes the selected files and containing folders:

w.paths()
w.selected_folders()
w.save("session-selection.quantem-showfolder.json")
w.clear_cache()

To share the folder browser without a live kernel, export standalone HTML:

w.export_html("session-showfolder.html")

For the full visual workflow, see the ShowFolder tutorial.

Reference

class quantem.widget.showfolder.ShowFolder(path: str | Path | None = None, *, key: str = 'show_folder', default: str | Path | None = None, **browser_kwargs: Any)

Inspect and curate a microscopy folder in a notebook.

ShowFolder is the public folder-level API. It scans microscopy image files, builds thumbnails, groups related acquisitions, and stores lightweight image-selection state without embedding large raw arrays in the notebook.

Parameters:

• path – Folder to browse. If omitted, display a folder chooser and run the browser after the user selects a folder.

• key – Cache key for chooser mode. Reuses the last folder for that key.

• default – Starting folder for chooser mode when no cached folder exists.

• **browser_kwargs – Passed through to the internal ShowFolder builder.

property folder: Path | None

Current browsed folder, if one has been selected.

property items: list[Any]

Browsed file items.

property inventory_rows: list[dict[str, Any]]

JSON-serializable inventory rows.

property master_qc_rows: list[dict[str, Any]]

JSON-serializable readiness rows for *_master.h5 files.

property cache_info: dict[str, Any]

Thumbnail/index cache status for the latest folder-browser run.

property cache_path: Path | None

Folder containing the latest ShowFolder cache manifest and thumbnails.

selected(kind: str | None = None) → list[Any]

Return selected folder-browser items.

paths(kind: str | None = None) → list[Path]

Return selected file paths.

selected_paths(kind: str | None = None) → list[Path]

Compatibility alias for paths().

selected_folders() → list[Path]

Return parent folders containing selected files.

selection() → dict[str, Any]

Return the current JSON-serializable selection snapshot.

save(path: str | Path | None = None) → Path

Write the current selection JSON.

load(path: str | Path | None = None) → dict[str, Any]

Load selection JSON into the current folder browser.

clear_cache() → None

Delete the current ShowFolder thumbnail/index cache, if present.

export_html(path: str | Path | None = None, *, title: str | None = None) → Path

Write a standalone HTML folder browser and return its path.

show_selected()

Return a Show2D gallery containing the currently starred images.

show_selected_stack()

Return currently starred images as a Show3D frame stack.

show_all_as_show2d()

Return all readable folder images as a Show2D preview gallery.

show_all_as_show3d_stack()

Return all readable folder images as a Show3D frame stack.

open_show2d(*, all_images: bool = False)

Open a live Show2D viewer in the attached selection panel.

open_show3d(*, all_images: bool = False)

Open a live Show3D viewer in the attached selection panel.

open_both(*, all_images: bool = False)

Open live Show2D and Show3D viewers in the selection panel.

open_show4dstem(**kwargs: Any)

Open folder masters as one lazy Show4DSTEM viewer.

watch(interval: float = 2.0, *, start: bool = True) → ShowFolder

Watch the folder and update the displayed browser when files change.

The watcher uses the same thumbnail/index cache as normal ShowFolder construction. Unchanged files stay cached, new or modified files are read, and files removed from disk disappear from the in-memory browser and from the next cache manifest.

stop_watch() → ShowFolder

Stop a running ShowFolder folder watcher.

watch_once() → bool

Poll once and update the displayed browser if the folder changed.

refresh(path: str | Path | None = None) → ShowFolder

Run or rerun the microscopy folder browser.

close() → None

Stop background work and close this ShowFolder widget tree.

quantem.widget.showfolder.show_folder(path: str | Path | None = None, *, key: str = 'show_folder', default: str | Path | None = None, **browser_kwargs: Any) → ShowFolder

Open a microscopy folder browser widget.

quantem.widget.showfolder.prebuild_showfolder_cache(path: str | Path, *, cache_dir: str | Path | None = None, thumb: int = 256, glob: str = '*.emd', rebuild_cache: bool = False, **browser_kwargs: Any) → dict[str, Any]

Build or refresh a ShowFolder thumbnail/index cache without displaying UI.

This is useful on a workstation or SSD-backed scratch path before opening a large microscopy session in a notebook. It runs the same ShowFolder pipeline as ShowFolder, then returns cache_info.