Segmentation

“Segmentation” means splitting an image into meaningful regions — for example, marking exactly which pixels belong to a particle and which are background. juspice.segmentation_module gives you deep-learning segmentation through the spice.segmentation accessor: one call prepares your dataset, trains a U-Net model, and (if you give it test images) checks how well it worked.

Native interface — UNetSegmentationAccessor

spice.segmentation.train_unet() is the primary, recommended interface for U-Net segmentation. It is analogous to juspice.synth_data_module.SynthGenerationAccessor.generate(): the input spice provides history lineage context (not image data to transform), and a new SPICEData carrying the epoch-wise loss curves is returned, sharing that lineage:

seg_spice = spice.segmentation.train_unet(
    train_images_dir=x_train_dir,
    train_masks_dir=y_train_dir,
    val_images_dir=x_val_dir,
    val_masks_dir=y_val_dir,
    test_images_dir=x_test_dir,
    test_masks_dir=y_test_dir,
    arch='Unet',
    encoder_name='resnet34',
    epochs=20,
    batch_size=8,
    device=device,
)

seg_spice.data           # shape (epochs, 2) — [train_loss, val_loss] per row
seg_spice.metadata       # arch, encoder_name, final losses, test_loss, test_iou

train_unet() internally constructs Dataset, DataLoader, UNetModel, and runs train_model() (and optionally test_model() when test directories are provided) — no manual setup is needed.

Required (positional-style):

  • train_images_dir, train_masks_dir — directories of training images and masks (masks expected with _m suffix per Dataset).

Optional (keyword, with sensible defaults):

  • arch='Unet', encoder_name='resnet34'

  • epochs=20, batch_size=8, learning_rate=2e-4

  • val_images_dir, val_masks_dir (falls back to training set)

  • test_images_dir, test_masks_dir (skipped when omitted)

  • device='cpu' — use 'cuda' or 'mps' for GPU acceleration

  • loss_fn_name='DiceLoss' — also accepts 'FocalLoss'

Other notebooks (SAM1, SAM2, trackpy, NASA MicroNet)

The segmentation directory also contains notebooks for zero-shot and pretrained segmentation workflows that rely on external libraries (Meta SAM, NASA MicroNet / pretrained_microscopy_models, Trackpy). These notebooks:

Reproducibility

spice.segmentation.train_unet() records a segmentation.train_unet operation into spice.history. Because model configuration (architecture, directory paths, device) cannot be faithfully serialised into a literal Python call, to_lines() renders it as a documentary comment pointing to the parameters:

# Segmentation: spice.segmentation.train_unet(...) with arch='Unet', ...

Legacy classes and functions

UNetModel, Dataset, train_model() and test_model() remain fully functional for advanced and direct use. spice.segmentation.train_unet() constructs and calls these internally.

See also