segmentCells3D

Segment 3-D image volume using Cellpose

Since R2023b

Syntax

labels = segmentCells3D(cp,im)

labels = segmentCells3D(cp,im,Name=Value)

Description

labels = segmentCells3D(cp,im) segments a 3-D numeric intensity image volume using the model and options specified by the cellpose object cp.

labels = segmentCells3D(cp,im,Name=Value) specifies options using one or more name-value arguments. For example, specify ImageCellDiameter=50 if the cells in im are approximately 50 voxels in diameter.

Note

This functionality requires Deep Learning Toolbox™, Computer Vision Toolbox™, and the Medical Imaging Toolbox™ Interface for Cellpose Library. You can install the Medical Imaging Toolbox Interface for Cellpose Library from Add-On Explorer. For more information about installing add-ons, see Get and Manage Add-Ons.

Examples

Segment 3-D Image Using Cellpose

Create a simulated 3-D microscopy image volume of size 40-by-40-by-40 voxels that contains one cell. The diameter of the simulated cell is approximately 30 voxels.

vol = zeros(40,40,40,"uint8");
vol(15,23,21) = 255;
disk = strel("sphere",12);
vol = imfilter(vol,double(disk.Neighborhood));

Specify the approximate diameter of the simulated cell, in voxels.

averageCellDiameter = 30;

Create a cellpose object that configures the pretrained cyto2 model from the Cellpose Library.

cp = cellpose(Model="cyto2");

Segment the image, specifying the average cell diameter and the cell threshold.

labels = segmentCells3D(cp,vol, ...
    ImageCellDiameter=averageCellDiameter, ...
    CellThreshold=-6);

Display the simulated image volume with the predicted labels as an overlay. The label mask accurately covers the simulated cell, indicating the model was successful.

volshow(vol,RenderingStyle="SlicePlanes", ...
    OverlayData=labels, ...
    OverlayAlpha=0.5);

Input Arguments

cp — Cellpose model configuration

cellpose object

Cellpose model configuration, specified as a cellpose object. The cellpose object properties specify which model to use, and define options such as model ensembling and whether to use a GPU.

im — Intensity image volume

3-D numeric array

Intensity image volume to segment, specified as a 3-D numeric array. The Cellpose Library converts the values in im to data type single before segmenting the image volume.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: segmentCells3D(cp,im,ImageCellDiameter=50) specifies that the cells in im are approximately 50 voxels in diameter.

AuxiliaryChannelImage — Auxiliary channel image volume

zeros(size(im)) (default) | 3-D numeric array

Auxiliary channel image volume, specified as a 3-D numeric array the same size and data type as im. You can optionally specify this argument if the model accepts a nuclear channel. If you do not specify this value, the function passes an array of zeros the same size as im to the model. The Cellpose Library converts the auxiliary channel image volume to data type single. This argument corresponds to the chan2 parameter in the Cellpose Library.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

ImageCellDiameter — Cell diameter in input image volume

positive numeric scalar

Cell diameter in the input image volume im, specified as a positive numeric scalar, in voxels. By default, the function assumes that im contains cells the same size as in the training data set, and uses the diameter specified by the TrainingCellDiameter property of cp. This argument corresponds to the diameter parameter in the Cellpose Library.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

CellThreshold — Cell probability threshold

0 (default) | numeric scalar

Cell probability threshold, specified as a numeric scalar. The model applies this threshold to the network output, and includes voxels above the threshold in the label predictions. A value between -6 and 6 is suitable for most images. This argument corresponds to the cellprob_threshold parameter in the Cellpose Library.

• Increasing this value can cause the model to generate cleaner boundaries, but miss some cells.

• Decreasing this value can cause the model to detect more cells, but can generate less accurate boundaries between cells.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

NormalizeInput — Normalize input image volume

true or 1 (default) | false or 0

Normalize input image volume, specified as a numeric or logical 1 (true) or 0 (false). When set to true, the function rescales the input image volume and the auxiliary channel image volume, if specified, to the range [0, 1]. The function maps the bottom 1% of intensity values of each image volume to 0 and the top 1% of intensity values to 1. This argument corresponds to the normalize parameter in the Cellpose Library.

Data Types: logical

VoxelSpacing — Spacing between adjacent image voxels

[1 1 1] (default) | 3-element numeric row vector

Spacing between adjacent voxels, specified as a 3-element numeric row vector. The first two elements must be the same, corresponding to equal spacing in the first two dimensions. Spacing values can correspond to any units, such as millimeters or meters, but units must be the same for all three dimensions. This argument is used to compute the anisotropy parameter in the Cellpose Library.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

TileOverlap — Overlap between tiles

0.1 (default) | positive numeric scalar

Overlap between tiles, specified as a positive numeric scalar. This argument specifies the fractional overlap between adjacent tiles. For each voxel in overlapping regions, the function averages the results across tiles to obtain the final value for the voxel. A value between 0.05 and 0.5 is suitable for most images. This argument corresponds to the tile_overlap parameter in the Cellpose Library.

Note

The segmentCells3D function always uses tiling because the Cellpose Library automatically sets its tile parameter to true for 3-D image volumes.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

TileAndAugment — Augment image

false or 0 (default) | true or 1

Augment images, specified as a numeric or logical 0 (false) or 1 (true). When set to true, the function sets TileOverlap to 0.5, generating tiles with 50% overlap. The function flips multiple copies of each tile vertically and horizontally, and then averages results across orientations. Augmentation generally increases accuracy, but decreases speed. This argument corresponds to the augment parameter in the Cellpose Library.

Data Types: logical

GPUBatchSize — GPU batch size

8 (default) | positive integer

GPU batch size, specified as a positive integer. This argument has an effect only when processing images on a GPU. The batch size specifies the number of tiles per batch. Using a larger batch size increases speed, but requires more memory. This argument corresponds to the batchsize parameter in the Cellpose Library.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

PostprocessAtOriginalSize — Postprocess image at original size

true or 1 (default) | false or 0

Postprocess image at its original size, specified as a numeric or logical 1 (true) or 0 (false). When set to true, the function uses bilinear interpolation to resize the network outputs to the size of the input image before postprocessing them. Resizing before postprocessing can generate smoother boundaries when ImageCellDiameter is larger than the detectable cell diameter of the model. When set to false, the function uses nearest neighbor interpolation to resize label images to the input size after postprocessing. This argument is inversely related to the no_resample parameter in the Cellpose Library.

Data Types: logical

MinVolume — Minimum size of each cell

15 (default) | positive numeric scalar

Minimum size of each cell, specified as a positive numeric scalar, in voxels. The model excludes regions smaller than this value from the final labels, which can reduce noise. This argument corresponds to the min_size parameter in the Cellpose Library.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Output Arguments

labels — Segmentation label image

3-D array

Segmentation label image, returned as a 3-D array of data type double. Voxel values map to the labels returned by the model. For example, if the model detects two cells, labels has values in the range [0, 2], where background voxels have a value of 0, the first cell has voxel values of 1, and the second cell has voxel values of 2.

References

[1] Stringer, Carsen, Tim Wang, Michalis Michaelos, and Marius Pachitariu. “Cellpose: A Generalist Algorithm for Cellular Segmentation.” Nature Methods 18, no. 1 (January 2021): 100–106. https://doi.org/10.1038/s41592-020-01018-x.

[2] Pachitariu, Marius, and Carsen Stringer. “Cellpose 2.0: How to Train Your Own Model.” Nature Methods 19, no. 12 (December 2022): 1634–41. https://doi.org/10.1038/s41592-022-01663-4.

Version History

Introduced in R2023b