Images, channels, and masks

Organize one 2D TIFF per field and channel in a single dataset folder. The example phase image is C1, but channel identifiers are configurable.

dataset/
  sample_XY1_C1.tiff
  sample_XY1_C2.tiff
  sample_XY1_C3.tiff
  sample_XY2_C1.tiff
  sample_XY2_C2.tiff
  sample_XY2_C3.tiff
  masks/
    sample_XY1_C1_cp_masks.tif
    sample_XY2_C1_cp_masks.tif

Field matching

The loaders use TIFF suffixes and natural sorting. The collection matches phase images, masks, and channels by field identity rather than trusting array position. The helper bactoscoop.utilities.image_field_key() removes the recognized channel/mask suffix. Duplicate, missing, or mismatched identities can produce errors. Use consistent names and one unambiguous TIFF per field and channel.

Label masks

Masks must be 2D integer label images, with background 0 and cells labeled consecutively from 1 to N. Each matching channel and mask must have the same height and width as the phase image. Binary foreground masks containing many cells under label 1 do not encode distinct cells.

Generate masks through Omnipose or place externally generated masks in masks/ using the matching naming convention. Inspect the overlays before meshing. Relabel nonconsecutive labels in a separate preprocessing copy if needed. The pipeline handles separate 2D images, not a raw multichannel stack or a 3D volume passed directly to these loaders.

Calibration and registration

Pass the physical calibration into ImageCollection(..., px=...). px is µm per pixel and defaults to 0.065. Pixel coordinates in geometry arrays are not converted to µm; individual measurement functions apply the scale. Check that fluorescence channels are registered to phase contrast. Per-cell shift correction is a specific measurement operation, not a replacement for correct acquisition geometry. See Channel alignment and shift correction.