Mask2D

Mask2D turns one region drawn on a 2D image into a Boolean NumPy mask. The ordinary workflow has only two steps:

from quantem.widget import Mask2D

selector = Mask2D(image)
selector

After drawing or replacing the region, use the mask directly:

mask = selector.mask
selected_values = image[mask]

There is no result dictionary to unpack. selector.mask has the same (row, col) shape as the input and Boolean dtype. selector.geometry is optional metadata for workflows that also need the selected center, bounds, or radius.

Configuration

Choose the initial shape and the display settings that matter for the image:

selector = Mask2D(
    image,
    shape="circle",
    title="Gold particle region",
    cmap="magma",
    auto_contrast=True,
    sampling=0.02,
    units="nm",
)

The dedicated Mask2D toolbar can switch among rectangle, square, and circle, change the image color, adjust contrast, reset the view, and clear the region. A new drag replaces the previous region. Clear returns an all-false mask. The selection is synchronized to Python when the pointer is released, so dragging remains browser-local and responsive.

Display binning remains fixed at 1 so selector.mask always matches the input image shape. Mask2D is separate from Show2D: using it does not add controls or selection behavior to a Show2D widget.

Standalone HTML export likewise keeps downsample=1; choose either full float32 or uint8 encoding without changing the selection coordinates.

For a native-resolution image, pass the full array or dataset directly. This real gold HAADF example keeps all 4096 by 4096 pixels:

from quantem.widget.datasets import show2d_gold

gold = show2d_gold(size="full")
selector = Mask2D(
    gold,
    title="Select a gold region",
    cmap="inferno",
)
selector

mask = selector.mask  # Boolean shape: (4096, 4096)

Reference

class quantem.widget.mask2d.Mask2D(*args: t.Any, **kwargs: t.Any)

Bases: Show2D

Draw one reusable Boolean mask over a two-dimensional image.

Mask2D has its own focused browser interface: choose a shape and drag the desired region. The committed region is synchronized to Python only on release. Its display does not alter Show2D.

Parameters:

• data (array-like or Dataset2d) – Numerical image with shape (row, col). Dataset sampling and units are preserved for calibrated display.

• shape ({"rectangle", "square", "circle"}, default="rectangle") – Initial drawing shape.

• title (str, default="Select region") – Compact title shown above the image.

• cmap (str or Colormap, default="gray") – Image colormap.

• **kwargs – Image display options accepted by Show2D. display_bin must remain 1 so the returned mask matches the input.

Examples

>>> region = Mask2D(image)
>>> region
>>> mask = region.mask
>>> selected_values = image[mask]

property mask: ndarray

Union of selected regions as one (row, col) Boolean mask.

property geometry: dict[str, object] | None

Selected JSON-friendly geometry in (row, col) coordinates.

Most workflows only need mask. Geometry is available when a downstream calculation also needs the selected center, bounds, or radius.

clear() → Self

Clear the selected region and return this widget.

state_dict() → dict

Return display state including the active selection shape.

load_state_dict(state) → None

Restore display and selection state.

Interactive controls

Control	Trait	Expected effect
Shape	mask_shape	Chooses rectangle, square, or circle for the next drag
Image drag	roi_list, roi_selected_idx	Shows a live preview, then replaces and synchronizes the selected region on release
Clear	roi_list	Removes the region; selector.mask becomes all false