autoemx.core.em_runtime.particle_segmentation_models.SAM2 module

Particle segmentation with SAM2 (Segment Anything Model 2.1), each particle segmented on its own, so that touching particles are measured separately:

N. Ravi et al., “SAM 2: Segment Anything in Images and Videos”, arXiv:2408.00714 (2024). https://github.com/facebookresearch/sam2

SAM2 segments the whole frame (automatic mask generation, from a grid of points), through Hugging Face transformers with Meta’s weights (facebook/sam2.1-hiera-*, Apache-2.0, downloaded from the Hugging Face Hub on first use). The masks are then filtered (substrate, agglomerates, surface features, occluded particles; see _instance_filters). The brightness threshold is not used.

Install (optional): pip install "autoemx[segmentation]" (torch, torchvision, transformers), or, for an editable installation, pip install -e ".[segmentation]" from the repository folder.

Options (PowderMeasurementConfig.par_segmentation_params), with their defaults:

  • checkpoint: "facebook/sam2.1-hiera-large" (or -base-plus, -small, -tiny: faster, less accurate);

  • device: "auto" (CUDA if available, else CPU), or a torch device such as "cpu", "cuda", "mps";

  • points_per_batch (64), points_per_crop (32, grid of 32 × 32 points), crops_n_layers (0), pred_iou_thresh (0.8), stability_score_thresh (0.9), crops_nms_thresh (0.7): options of the transformers mask-generation pipeline;

  • the filter options of _instance_filters.FILTER_DEFAULTS (e.g. min_visible_fraction).

Created on Sat Oct 17 2026 @author: Andrea

autoemx.core.em_runtime.particle_segmentation_models.SAM2.GENERATOR_DEFAULTS: Dict[str, Any] = {'crops_n_layers': 0, 'crops_nms_thresh': 0.7, 'points_per_batch': 64, 'points_per_crop': 32, 'pred_iou_thresh': 0.8, 'stability_score_thresh': 0.9}

Options of the mask generation and their defaults

autoemx.core.em_runtime.particle_segmentation_models.SAM2.is_available() → bool[source]

Whether torch, torchvision and transformers are installed.

autoemx.core.em_runtime.particle_segmentation_models.SAM2.get_mask_generator(checkpoint: str = 'facebook/sam2.1-hiera-large', device: str = 'auto')[source]

The transformers mask-generation pipeline of a SAM2 checkpoint (loaded once per process).

autoemx.core.em_runtime.particle_segmentation_models.SAM2.generate_masks(frame_image: ndarray, params: Dict[str, Any]) → list[source]

Masks of every object SAM2 finds in a greyscale frame (bool arrays of the frame’s shape).

autoemx.core.em_runtime.particle_segmentation_models.SAM2.segment_particles(frame_image: ndarray, powder_meas_config: PowderMeasurementConfig = None, save_image: bool = False, EM: EM_controller = None) → ndarray[source]

Label image of the particles of a frame segmented by SAM2 (int32, background 0, one label per particle).

Parameters:

  • frame_image (ndarray) – Greyscale frame image.

  • powder_meas_config (PowderMeasurementConfig, optional) – Its par_segmentation_params are the options of the model (see the module documentation).

  • save_image (bool, optional) – Save the label image as a mask through EM (default: False).

  • EM (EM_controller, optional) – Used to save the mask image.