Bin#

class quantem.widget.Bin(**kwargs: Any)[source]#

Bases: AnyWidget

Interactive 4D-STEM binning widget with calibration tracking and BF/ADF QC.

Parameters:

  • data (Dataset4dstem or array_like) – 4D array (scan_rows, scan_cols, det_rows, det_cols) or flattened 3D (N, det_rows, det_cols) with explicit scan_shape. If a quantem dataset object is provided, calibration is auto-extracted.

  • scan_shape (tuple[int, int], optional) – Required for flattened 3D input.

  • pixel_size (float or tuple[float, float], optional) – Real-space sampling in Å/px for (row, col).

  • k_pixel_size (float or tuple[float, float], optional) – Detector sampling in mrad/px (or reciprocal-space units) for (row, col).

  • center (tuple[float, float], optional) – Detector center (row, col) used for BF/ADF preview masks.

  • bin_mode ({"mean", "sum"}, default "mean") – Reduction mode for block binning.

  • edge_mode ({"crop", "pad", "error"}, default "crop") – How non-divisible dimensions are handled.

  • bf_radius_ratio (float, default 0.125) – BF disk radius as fraction of min(det_rows, det_cols).

  • adf_inner_ratio (float, default 0.30) – ADF annulus inner radius as fraction of detector size.

  • adf_outer_ratio (float, default 0.45) – ADF annulus outer radius as fraction of detector size.

Notes

  • Real-space calibration is multiplied by scan bin factors.

  • Detector-space calibration is multiplied by detector bin factors.

  • BF/ADF previews are recomputed after every parameter change.

Key Methods

Bin.set_data(data, scan_shape: tuple[int, int] | None = None, pixel_size: float | tuple[float, float] | None = None, k_pixel_size: float | tuple[float, float] | None = None, center: tuple[float, float] | None = None) → Self[source]#

Replace the 4D data while preserving display settings.

Bin.get_binned_data(copy: bool = True, as_numpy: bool = False)[source]#

Return current binned data (torch by default).

Bin.to_show4dstem(**kwargs)[source]#

Create a Show4DSTEM instance from the current binned data.

Notes

Show4DSTEM currently accepts scalar calibrations; row/col calibrations are collapsed using arithmetic mean for compatibility.

Export

Bin.save_image(path: str | Path, view: str = 'binned_bf', cmap: str = 'inferno', scale_mode: str = 'linear', format: str | None = None, include_metadata: bool = True, metadata_path: str | Path | None = None, dpi: int = 300) → Path[source]#

Save one Bin preview view (or 2x2 grid) as PNG/PDF with metadata.

Bin.save_zip(path: str | Path, cmap: str = 'inferno', scale_mode: str = 'linear', include_arrays: bool = False) → Path[source]#

Export all Bin previews + metadata in a ZIP bundle.

Bin.save_gif(path: str | Path, channel: str = 'bf', cmap: str = 'inferno', scale_mode: str = 'linear', duration_ms: int = 800, loop: int = 0, include_metadata: bool = True, metadata_path: str | Path | None = None) → Path[source]#

Save a two-frame GIF comparing original vs binned BF/ADF previews.

State Persistence

Bin.state_dict() → dict[source]#
Bin.save(path: str | Path) → None[source]#
Bin.load_state_dict(state: dict) → None[source]#
Bin.summary() → None[source]#

Print compact binning + calibration summary.