Cellpose API Guide

CellposeModel

class cellpose.models.CellposeModel(gpu=False, pretrained_model='cpsam', model_type=None, diam_mean=None, device=None, nchan=None, use_bfloat16=True)[source]

Class representing a Cellpose model.

diam_mean

Mean “diameter” value for the model.

Type:: float

builtin

Whether the model is a built-in model or not.

Type:: bool

device

Device used for model running / training.

Type:: torch device

nclasses

Number of classes in the model.

Type:: int

nbase

List of base values for the model.

Type:: list

net

Cellpose network.

Type:: CPnet

pretrained_model

Path to pretrained cellpose model.

Type:: str

pretrained_model_ortho

Path or model_name for pretrained cellpose model for ortho views in 3D.

Type:: str

backbone

Type of network (“default” is the standard res-unet, “transformer” for the segformer).

Type:: str

__init__(self, gpu=False, pretrained_model=False, model_type=None, diam_mean=30., device=None)[source]: Initialize the CellposeModel.

eval(self, x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile_overlap=0.1, bsize=256, interp=True, compute_masks=True, progress=None)[source]: Segment list of images x, or 4D array - Z x C x Y x X.

eval(x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, flow3D_smooth=0, stitch_threshold=0.0, min_size=15, max_size_fraction=0.4, niter=None, augment=False, tile_overlap=0.1, bsize=256, compute_masks=True, progress=None)[source]

segment list of images x, or 4D array - Z x 3 x Y x X

Parameters:

x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images. Images must have 3 channels.
batch_size (int, optional) – number of 256x256 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 64.
resample (bool, optional) – run dynamics at original image size (will be slower but create more accurate boundaries).
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
- ”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
- ”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
- ”normalize”=True ; run normalization (if False, all following parameters ignored)
- ”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
- ”tile_norm_blocksize”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
- ”norm3D”=True ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – invert image pixel intensity before running network. Defaults to False.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float or list of float, optional) – diameters are used to rescale the image to 30 pix cell diameter.
flow_threshold (float, optional) – flow error threshold (all cells with errors below threshold are kept) (not used for 3D). Defaults to 0.4.
cellprob_threshold (float, optional) – all pixels with value above threshold kept for masks, decrease to find more and larger masks. Defaults to 0.0.
do_3D (bool, optional) – set to True to run 3D segmentation on 3D/4D image input. Defaults to False.
flow3D_smooth (int or float or list of (int or float), optional) – if do_3D and flow3D_smooth>0, smooth flows with gaussian filter of this stddev. If you are seeing increased fragmentation along the Z axis, or ring-artifacts, you can specify increased smoothing in the z-axis by providing a list, e.g. flow3D_smooth = [2, 1, 1]. List smooths the ZYX axes independently and must be length 3. Defaults to 0.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
stitch_threshold (float, optional) – if stitch_threshold>0.0 and not do_3D, masks are stitched in 3D to return volume segmentation. Defaults to 0.0.
min_size (int, optional) – all ROIs below this size, in pixels, will be discarded. Defaults to 15.
max_size_fraction (float, optional) – max_size_fraction (float, optional): Masks larger than max_size_fraction of total image size are removed. Default is 0.4.
niter (int, optional) – number of iterations for dynamics computation. if None, it is set proportional to the diameter. Defaults to None.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – block size for tiles, recommended to keep at 256, like in training. Defaults to 256.
interp (bool, optional) – interpolate during 2D dynamics (not available in 3D) . Defaults to True.
compute_masks (bool, optional) – Whether or not to compute dynamics and return masks. Returns empty array if False. Defaults to True.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.

Returns:

masks (list of 2D arrays or single 3D array): Labelled image, where 0=no masks; 1,2,…=mask labels; flows (list of lists 2D arrays or list of 3D arrays):

flows[k][0] = XY flow in HSV 0-255; flows[k][1] = XY flows at each pixel; flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics); flows[k][3] = final pixel locations after Euler integration;

styles (list of 1D arrays of length 256 or single 1D array): Style vector containing only zeros. Retained for compaibility with CP3.

Return type:

A tuple containing (masks, flows, styles)

Training

cellpose.train.train_seg(net, train_data=None, train_labels=None, train_files=None, train_labels_files=None, train_probs=None, test_data=None, test_labels=None, test_files=None, test_labels_files=None, test_probs=None, channel_axis=None, load_files=True, batch_size=1, learning_rate=1e-05, SGD=False, n_epochs=100, weight_decay=0.1, normalize=True, compute_flows=False, save_path=None, save_every=100, save_each=False, nimg_per_epoch=None, nimg_test_per_epoch=None, rescale=False, scale_range=None, bsize=256, min_train_masks=5, model_name=None, class_weights=None)[source]

Train the network with images for segmentation.

Parameters:

net (object) – The network model to train. If net is a bfloat16 model it will be converted to float32 for training. The saved models will be in float32, but the original model will be returned as the original dtype for consistency.
train_data (List[np.ndarray], optional) – List of arrays (2D or 3D) - images for training. Defaults to None.
train_labels (List[np.ndarray], optional) – List of arrays (2D or 3D) - labels for train_data, where 0=no masks; 1,2,…=mask labels. Defaults to None.
train_files (List[str], optional) – List of strings - file names for images in train_data (to save flows for future runs). Defaults to None.
train_labels_files (list or None) – List of training label file paths. Defaults to None.
train_probs (List[float], optional) – List of floats - probabilities for each image to be selected during training. Defaults to None.
test_data (List[np.ndarray], optional) – List of arrays (2D or 3D) - images for testing. Defaults to None.
test_labels (List[np.ndarray], optional) – List of arrays (2D or 3D) - labels for test_data, where 0=no masks; 1,2,…=mask labels. Defaults to None.
test_files (List[str], optional) – List of strings - file names for images in test_data (to save flows for future runs). Defaults to None.
test_labels_files (list or None) – List of test label file paths. Defaults to None.
test_probs (List[float], optional) – List of floats - probabilities for each image to be selected during testing. Defaults to None.
load_files (bool, optional) – Boolean - whether to load images and labels from files. Defaults to True.
batch_size (int, optional) – Integer - number of patches to run simultaneously on the GPU. Defaults to 1.
learning_rate (float or List[float], optional) – Float or list/np.ndarray - learning rate for training. Defaults to 1e-5.
n_epochs (int, optional) – Integer - number of times to go through the whole training set during training. Defaults to 100.
weight_decay (float, optional) – Float - weight decay for the optimizer. Defaults to 0.1.
SGD (bool, optional) – Deprecated in v4.0.1+ - AdamW always used.
normalize (bool or dict, optional) – Boolean or dictionary - whether to normalize the data. Defaults to True.
compute_flows (bool, optional) – Boolean - whether to compute flows during training. Defaults to False.
save_path (str, optional) – String - where to save the trained model. Defaults to None.
save_every (int, optional) – Integer - save the network every [save_every] epochs. Defaults to 100.
save_each (bool, optional) – Boolean - save the network to a new filename at every [save_each] epoch. Defaults to False.
nimg_per_epoch (int, optional) – Integer - minimum number of images to train on per epoch. Defaults to None.
nimg_test_per_epoch (int, optional) – Integer - minimum number of images to test on per epoch. Defaults to None.
rescale (bool, optional) – Boolean - whether or not to rescale images during training. Defaults to False.
min_train_masks (int, optional) – Integer - minimum number of masks an image must have to use in the training set. Defaults to 5.
model_name (str, optional) – String - name of the network. Defaults to None.

Returns:

A tuple containing the path to the saved model weights, training losses, and test losses.

Return type:

tuple

Metrics

cellpose.metrics.aggregated_jaccard_index(masks_true, masks_pred)[source]

AJI = intersection of all matched masks / union of all masks

Parameters:

masks_true (list of np.ndarrays (int) or np.ndarray (int)) – where 0=NO masks; 1,2… are mask labels
masks_pred (list of np.ndarrays (int) or np.ndarray (int)) – np.ndarray (int) where 0=NO masks; 1,2… are mask labels

Returns:

aggregated jaccard index for each set of masks

Return type:

aji (float)

cellpose.metrics.average_precision(masks_true, masks_pred, threshold=[0.5, 0.75, 0.9])[source]

Average precision estimation: AP = TP / (TP + FP + FN)

This function is based heavily on the fast stardist matching functions (https://github.com/mpicbg-csbd/stardist/blob/master/stardist/matching.py)

Parameters:

masks_true (list of np.ndarrays (int) or np.ndarray (int)) – where 0=NO masks; 1,2… are mask labels
masks_pred (list of np.ndarrays (int) or np.ndarray (int)) – np.ndarray (int) where 0=NO masks; 1,2… are mask labels

Returns:

average precision at thresholds tp (array [len(masks_true) x len(threshold)]):

number of true positives at thresholds

fp (array [len(masks_true) x len(threshold)]):: number of false positives at thresholds
fn (array [len(masks_true) x len(threshold)]):: number of false negatives at thresholds

Return type:

ap (array [len(masks_true) x len(threshold)])

cellpose.metrics.boundary_scores(masks_true, masks_pred, scales)[source]

Calculate boundary precision, recall, and F-score.

Parameters:

masks_true (list) – List of true masks.
masks_pred (list) – List of predicted masks.
scales (list) – List of scales.

Returns:

A tuple containing precision, recall, and F-score arrays.

Return type:

tuple

cellpose.metrics.mask_ious(masks_true, masks_pred)[source]: Return best-matched masks.

Flows <=> masks

cellpose.dynamics.compute_masks(dP, cellprob, p=None, niter=200, cellprob_threshold=0.0, flow_threshold=0.4, do_3D=False, min_size=-1, max_size_fraction=0.4, device=torch.device)[source]

Compute masks using dynamics from dP and cellprob.

Parameters:

dP (numpy.ndarray) – The dynamics flow field array.
cellprob (numpy.ndarray) – The cell probability array.
p (numpy.ndarray, optional) – The pixels on which to run dynamics. Defaults to None
niter (int, optional) – The number of iterations for mask computation. Defaults to 200.
cellprob_threshold (float, optional) – The threshold for cell probability. Defaults to 0.0.
flow_threshold (float, optional) – The threshold for quality control metrics. Defaults to 0.4.
interp (bool, optional) – Whether to interpolate during dynamics computation. Defaults to True.
do_3D (bool, optional) – Whether to perform mask computation in 3D. Defaults to False.
min_size (int, optional) – The minimum size of the masks. Defaults to 15.
max_size_fraction (float, optional) – Masks larger than max_size_fraction of total image size are removed. Default is 0.4.
device (torch.device, optional) – The device to use for computation. Defaults to torch.device(“cpu”).

Returns:

A tuple containing the computed masks and the final pixel locations.

Return type:

tuple

cellpose.dynamics.flow_error(maski, dP_net, device=None)[source]

Error in flows from predicted masks vs flows predicted by network run on image.

This function serves to benchmark the quality of masks. It works as follows: 1. The predicted masks are used to create a flow diagram. 2. The mask-flows are compared to the flows that the network predicted.

If there is a discrepancy between the flows, it suggests that the mask is incorrect. Masks with flow_errors greater than 0.4 are discarded by default. This setting can be changed in Cellpose.eval or CellposeModel.eval.

Parameters:

maski (np.ndarray, int) – Masks produced from running dynamics on dP_net, where 0=NO masks; 1,2… are mask labels.
dP_net (np.ndarray, float) – ND flows where dP_net.shape[1:] = maski.shape.

Returns:

flow_errors (np.ndarray, float): Mean squared error between predicted flows and flows from masks; dP_masks (np.ndarray, float): ND flows produced from the predicted masks.

Return type:

A tuple containing (flow_errors, dP_masks)

cellpose.dynamics.follow_flows(dP, inds, niter=200, device=torch.device)[source]

Run dynamics to recover masks in 2D or 3D.

Pixels are represented as a meshgrid. Only pixels with non-zero cell-probability are used (as defined by inds).

Parameters:

dP (np.ndarray) – Flows [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
mask (np.ndarray, optional) – Pixel mask to seed masks. Useful when flows have low magnitudes.
niter (int, optional) – Number of iterations of dynamics to run. Default is 200.
interp (bool, optional) – Interpolate during 2D dynamics (not available in 3D). Default is True.
device (torch.device, optional) – Device to use for computation. Default is None.

Returns:

p (np.ndarray): Final locations of each pixel after dynamics; [axis x Ly x Lx] or [axis x Lz x Ly x Lx]; inds (np.ndarray): Indices of pixels used for dynamics; [axis x Ly x Lx] or [axis x Lz x Ly x Lx].

Return type:

A tuple containing (p, inds)

cellpose.dynamics.get_masks_torch(pt, inds, shape0, rpad=20, max_size_fraction=0.4)[source]

Create masks using pixel convergence after running dynamics.

Makes a histogram of final pixel locations p, initializes masks at peaks of histogram and extends the masks from the peaks so that they include all pixels with more than 2 final pixels p. Discards masks with flow errors greater than the threshold.

Parameters:

p (float32, 3D or 4D array) – Final locations of each pixel after dynamics, size [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
iscell (bool, 2D or 3D array) – If iscell is not None, set pixels that are iscell False to stay in their original location.
rpad (int, optional) – Histogram edge padding. Default is 20.
max_size_fraction (float, optional) – Masks larger than max_size_fraction of total image size are removed. Default is 0.4.

Returns:

Masks with inconsistent flow masks removed,: 0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].

Return type:

M0 (int, 2D or 3D array)

cellpose.dynamics.labels_to_flows(labels, files=None, device=None, redo_flows=False, niter=None, return_flows=True)[source]

Converts labels (list of masks or flows) to flows for training model.

Parameters:

labels (list of ND-arrays) – The labels to convert. labels[k] can be 2D or 3D. If [3 x Ly x Lx], it is assumed that flows were precomputed. Otherwise, labels[k][0] or labels[k] (if 2D) is used to create flows and cell probabilities.
files (list of str, optional) – The files to save the flows to. If provided, flows are saved to files to be reused. Defaults to None.
device (str, optional) – The device to use for computation. Defaults to None.
redo_flows (bool, optional) – Whether to recompute the flows. Defaults to False.
niter (int, optional) – The number of iterations for computing flows. Defaults to None.

Returns:

The flows for training the model. flows[k][0] is labels[k], flows[k][1] is cell distance transform, flows[k][2] is Y flow, flows[k][3] is X flow, and flows[k][4] is heat distribution.

Return type:

list of [4 x Ly x Lx] arrays

cellpose.dynamics.masks_to_flows_gpu(masks, device=torch.device, niter=None)[source]

Convert masks to flows using diffusion from center pixel.

Center of masks where diffusion starts is defined by pixel closest to median within the mask.

Parameters:

masks (int, 2D or 3D array) – Labelled masks. 0=NO masks; 1,2,…=mask labels.
device (torch.device, optional) – The device to run the computation on. Defaults to torch.device(“cpu”).
niter (int, optional) – Number of iterations for the diffusion process. Defaults to None.

Returns:

A 4D array representing the flows for each pixel in Z, X, and Y.

Return type:

np.ndarray

Returns:

A tuple containing (mu, meds_p). mu is float 3D or 4D array of flows in (Z)XY. meds_p are cell centers.

cellpose.dynamics.masks_to_flows_gpu_3d(masks, device=torch.device, niter=None)[source]

Convert masks to flows using diffusion from center pixel.

Parameters:

masks (int, 2D or 3D array) – Labelled masks. 0=NO masks; 1,2,…=mask labels.
device (torch.device, optional) – The device to run the computation on. Defaults to torch.device(‘cpu’).
niter (int, optional) – Number of iterations for the diffusion process. Defaults to None.

Returns:

A 4D array representing the flows for each pixel in Z, X, and Y.

Return type:

np.ndarray

cellpose.dynamics.max_pool1d(h, kernel_size=5, axis=1, out=None)[source]

memory efficient max_pool thanks to Mark Kittisopikul

for stride=1, padding=kernel_size//2, requires odd kernel_size >= 3

cellpose.dynamics.max_pool_nd(h, kernel_size=5)[source]: memory efficient max_pool in 2d or 3d

cellpose.dynamics.remove_bad_flow_masks(masks, flows, threshold=0.4, device=torch.device)[source]

Remove masks which have inconsistent flows.

Uses metrics.flow_error to compute flows from predicted masks and compare flows to predicted flows from the network. Discards masks with flow errors greater than the threshold.

Parameters:

masks (int, 2D or 3D array) – Labelled masks, 0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].
flows (float, 3D or 4D array) – Flows [axis x Ly x Lx] or [axis x Lz x Ly x Lx].
threshold (float, optional) – Masks with flow error greater than threshold are discarded. Default is 0.4.

Returns:

Masks with inconsistent flow masks removed,: 0=NO masks; 1,2,…=mask labels, size [Ly x Lx] or [Lz x Ly x Lx].

Return type:

masks (int, 2D or 3D array)

cellpose.dynamics.resize_and_compute_masks(dP, cellprob, niter=200, cellprob_threshold=0.0, flow_threshold=0.4, do_3D=False, min_size=15, max_size_fraction=0.4, resize=None, device=torch.device)[source]

Compute masks using dynamics from dP and cellprob, and resizes masks if resize is not None.

Parameters:

dP (numpy.ndarray) – The dynamics flow field array.
cellprob (numpy.ndarray) – The cell probability array.
p (numpy.ndarray, optional) – The pixels on which to run dynamics. Defaults to None
niter (int, optional) – The number of iterations for mask computation. Defaults to 200.
cellprob_threshold (float, optional) – The threshold for cell probability. Defaults to 0.0.
flow_threshold (float, optional) – The threshold for quality control metrics. Defaults to 0.4.
interp (bool, optional) – Whether to interpolate during dynamics computation. Defaults to True.
do_3D (bool, optional) – Whether to perform mask computation in 3D. Defaults to False.
min_size (int, optional) – The minimum size of the masks. Defaults to 15.
max_size_fraction (float, optional) – Masks larger than max_size_fraction of total image size are removed. Default is 0.4.
resize (tuple, optional) – The desired size for resizing the masks. Defaults to None.
device (torch.device, optional) – The device to use for computation. Defaults to torch.device(“cpu”).

Returns:

A tuple containing the computed masks and the final pixel locations.

Return type:

tuple

cellpose.dynamics.steps_interp(dP, inds, niter, device=torch.device)[source]

Run dynamics of pixels to recover masks in 2D/3D, with interpolation between pixel values.

Euler integration of dynamics dP for niter steps.

Parameters:

p (numpy.ndarray) – Array of shape (n_points, 2 or 3) representing the initial pixel locations.
dP (numpy.ndarray) – Array of shape (2, Ly, Lx) or (3, Lz, Ly, Lx) representing the flow field.
niter (int) – Number of iterations to perform.
device (torch.device, optional) – Device to use for computation. Defaults to None.

Returns:

Array of shape (n_points, 2) or (n_points, 3) representing the final pixel locations.

Return type:

numpy.ndarray

Raises:

None –

Image transforms

cellpose.transforms.average_tiles(y, ysub, xsub, Ly, Lx)[source]

Average the results of the network over tiles.

Parameters:

y (float) – Output of cellpose network for each tile. Shape: [ntiles x nclasses x bsize x bsize]
ysub (list) – List of arrays with start and end of tiles in Y of length ntiles
xsub (list) – List of arrays with start and end of tiles in X of length ntiles
Ly (int) – Size of pre-tiled image in Y (may be larger than original image if image size is less than bsize)
Lx (int) – Size of pre-tiled image in X (may be larger than original image if image size is less than bsize)

Returns:

Network output averaged over tiles. Shape: [nclasses x Ly x Lx]

Return type:

yf (float32)

cellpose.transforms.convert_image(x, channel_axis=None, z_axis=None, do_3D=False)[source]

Converts the image to have the z-axis first, channels last. Image will be converted to 3 channels if it is not already. If more than 3 channels are provided, only the first 3 channels will be used.

Accepts:

2D images with no channel dimension: z_axis and channel_axis must be None
2D images with channel dimension: channel_axis will be guessed between first or last axis, can also specify channel_axis. z_axis must be None
Batch of 2D images having shape: [N, H, W, C] with N images in the batch
3D images with or without channels:

Parameters:

x (numpy.ndarray or torch.Tensor) – The input image.
channel_axis (int or None) – The axis of the channels in the input image. If None, the axis is determined automatically.
z_axis (int or None) – The axis of the z-dimension in the input image. If None, the axis is determined automatically.
do_3D (bool) – Whether to process the image in 3D mode. Defaults to False.

Returns:

The converted image with channels last.

Return type:

numpy.ndarray

Raises:

ValueError – If the input image is 2D and do_3D is True.

cellpose.transforms.gaussian_kernel(sigma, Ly, Lx, device=torch.device)[source]

Generates a 2D Gaussian kernel.

Parameters:

sigma (float) – Standard deviation of the Gaussian distribution.
Ly (int) – Number of pixels in the y-axis.
Lx (int) – Number of pixels in the x-axis.
device (torch.device, optional) – Device to store the kernel tensor. Defaults to torch.device(“cpu”).

Returns:

2D Gaussian kernel tensor.

Return type:

torch.Tensor

cellpose.transforms.make_tiles(imgi, bsize=224, augment=False, tile_overlap=0.1)[source]

Make tiles of image to run at test-time.

Parameters:

imgi (np.ndarray) – Array of shape (nchan, Ly, Lx) representing the input image.
bsize (int, optional) – Size of tiles. Defaults to 224.
augment (bool, optional) – Whether to flip tiles and set tile_overlap=2. Defaults to False.
tile_overlap (float, optional) – Fraction of overlap of tiles. Defaults to 0.1.

Returns:

IMG (np.ndarray): Array of shape (ntiles, nchan, bsize, bsize) representing the tiles. ysub (list): List of arrays with start and end of tiles in Y of length ntiles. xsub (list): List of arrays with start and end of tiles in X of length ntiles. Ly (int): Height of the input image. Lx (int): Width of the input image.

Return type:

A tuple containing (IMG, ysub, xsub, Ly, Lx)

cellpose.transforms.move_axis(img, m_axis=-1, first=True)[source]: move axis m_axis to first or last position

cellpose.transforms.move_min_dim(img, force=False)[source]

Move the minimum dimension last as channels if it is less than 10 or force is True.

Parameters:

img (ndarray) – The input image.
force (bool, optional) – If True, the minimum dimension will always be moved. Defaults to False.

Returns:

The image with the minimum dimension moved to the last axis as channels.

Return type:

ndarray

cellpose.transforms.normalize99(Y, lower=1, upper=99, copy=True, downsample=False)[source]

Normalize the image so that 0.0 corresponds to the 1st percentile and 1.0 corresponds to the 99th percentile.

Parameters:

Y (ndarray) – The input image (for downsample, use [Ly x Lx] or [Lz x Ly x Lx]).
lower (int, optional) – The lower percentile. Defaults to 1.
upper (int, optional) – The upper percentile. Defaults to 99.
copy (bool, optional) – Whether to create a copy of the input image. Defaults to True.
downsample (bool, optional) – Whether to downsample image to compute percentiles. Defaults to False.

Returns:

The normalized image.

Return type:

ndarray

cellpose.transforms.normalize99_tile(img, blocksize=100, lower=1.0, upper=99.0, tile_overlap=0.1, norm3D=False, smooth3D=1, is3D=False)[source]

Compute normalization like normalize99 function but in tiles.

Parameters:

img (numpy.ndarray) – Array of shape (Lz x) Ly x Lx (x nchan) containing the image.
blocksize (float, optional) – Size of tiles. Defaults to 100.
lower (float, optional) – Lower percentile for normalization. Defaults to 1.0.
upper (float, optional) – Upper percentile for normalization. Defaults to 99.0.
tile_overlap (float, optional) – Fraction of overlap of tiles. Defaults to 0.1.
norm3D (bool, optional) – Use same tiled normalization for each z-plane. Defaults to False.
smooth3D (int, optional) – Smoothing factor for 3D normalization. Defaults to 1.
is3D (bool, optional) – Set to True if image is a 3D stack. Defaults to False.

Returns:

Normalized image array of shape (Lz x) Ly x Lx (x nchan).

Return type:

numpy.ndarray

cellpose.transforms.normalize_img(img, normalize=True, norm3D=True, invert=False, lowhigh=None, percentile=(1.0, 99.0), sharpen_radius=0, smooth_radius=0, tile_norm_blocksize=0, tile_norm_smooth3D=1, axis=-1)[source]

Normalize each channel of the image with optional inversion, smoothing, and sharpening.

Parameters:

img (ndarray) – The input image. It should have at least 3 dimensions. If it is 4-dimensional, it assumes the first non-channel axis is the Z dimension.
normalize (bool, optional) – Whether to perform normalization. Defaults to True.
norm3D (bool, optional) – Whether to normalize in 3D. If True, the entire 3D stack will be normalized per channel. If False, normalization is applied per Z-slice. Defaults to False.
invert (bool, optional) – Whether to invert the image. Useful if cells are dark instead of bright. Defaults to False.
lowhigh (tuple or ndarray, optional) – The lower and upper bounds for normalization. Can be a tuple of two values (applied to all channels) or an array of shape (nchan, 2) for per-channel normalization. Incompatible with smoothing and sharpening. Defaults to None.
percentile (tuple, optional) – The lower and upper percentiles for normalization. If provided, it should be a tuple of two values. Each value should be between 0 and 100. Defaults to (1.0, 99.0).
sharpen_radius (int, optional) – The radius for sharpening the image. Defaults to 0.
smooth_radius (int, optional) – The radius for smoothing the image. Defaults to 0.
tile_norm_blocksize (int, optional) – The block size for tile-based normalization. Defaults to 0.
tile_norm_smooth3D (int, optional) – The smoothness factor for tile-based normalization in 3D. Defaults to 1.
axis (int, optional) – The channel axis to loop over for normalization. Defaults to -1.

Returns:

The normalized image of the same size.

Return type:

ndarray

Raises:

ValueError – If the image has less than 3 dimensions.
ValueError – If the provided lowhigh or percentile values are invalid.
ValueError – If the image is inverted without normalization.

cellpose.transforms.pad_image_ND(img0, div=16, extra=1, min_size=None, zpad=False)[source]

Pad image for test-time so that its dimensions are a multiple of 16 (2D or 3D).

Parameters:

img0 (ndarray) – Image of size [nchan (x Lz) x Ly x Lx].
div (int, optional) – Divisor for padding. Defaults to 16.
extra (int, optional) – Extra padding. Defaults to 1.
min_size (tuple, optional) – Minimum size of the image. Defaults to None.

Returns:

A tuple containing (I, ysub, xsub) or (I, ysub, xsub, zsub), I is padded image, -sub are ranges of pixels in the padded image corresponding to img0.

cellpose.transforms.random_rotate_and_resize(X, Y=None, scale_range=1.0, xy=(224, 224), do_3D=False, zcrop=48, do_flip=True, rotate=True, rescale=None, unet=False, random_per_image=True)[source]

Augmentation by random rotation and resizing.

Parameters:

X (list of ND-arrays, float) – List of image arrays of size [nchan x Ly x Lx] or [Ly x Lx].
Y (list of ND-arrays, float, optional) – List of image labels of size [nlabels x Ly x Lx] or [Ly x Lx]. The 1st channel of Y is always nearest-neighbor interpolated (assumed to be masks or 0-1 representation). If Y.shape[0]==3 and not unet, then the labels are assumed to be [cell probability, Y flow, X flow]. If unet, second channel is dist_to_bound. Defaults to None.
scale_range (float, optional) – Range of resizing of images for augmentation. Images are resized by (1-scale_range/2) + scale_range * np.random.rand(). Defaults to 1.0.
xy (tuple, int, optional) – Size of transformed images to return. Defaults to (224,224).
do_flip (bool, optional) – Whether or not to flip images horizontally. Defaults to True.
rotate (bool, optional) – Whether or not to rotate images. Defaults to True.
rescale (array, float, optional) – How much to resize images by before performing augmentations. Defaults to None.
unet (bool, optional) – Whether or not to use unet. Defaults to False.
random_per_image (bool, optional) – Different random rotate and resize per image. Defaults to True.

Returns:

imgi (ND-array, float): Transformed images in array [nimg x nchan x xy[0] x xy[1]]; lbl (ND-array, float): Transformed labels in array [nimg x nchan x xy[0] x xy[1]]; scale (array, float): Amount each image was resized by.

Return type:

A tuple containing (imgi, lbl, scale)

cellpose.transforms.resize_image(img0, Ly=None, Lx=None, rsz=None, interpolation=cv2.INTER_LINEAR, no_channels=False)[source]

Resize image for computing flows / unresize for computing dynamics.

Parameters:

img0 (ndarray) – Image of size [Y x X x nchan] or [Lz x Y x X x nchan] or [Lz x Y x X].
Ly (int, optional) – Desired height of the resized image. Defaults to None.
Lx (int, optional) – Desired width of the resized image. Defaults to None.
rsz (float, optional) – Resize coefficient(s) for the image. If Ly is None, rsz is used. Defaults to None.
interpolation (int, optional) – OpenCV interpolation method. Defaults to cv2.INTER_LINEAR.
no_channels (bool, optional) – Flag indicating whether to treat the third dimension as a channel. Defaults to False.

Returns:

Resized image of size [Ly x Lx x nchan] or [Lz x Ly x Lx x nchan].

Return type:

ndarray

Raises:

ValueError – If Ly is None and rsz is None.

cellpose.transforms.resize_safe(img, Ly, Lx, interpolation=cv2.INTER_LINEAR)[source]

OpenCV resize function does not support uint32.

This function converts the image to float32 before resizing and then converts it back to uint32. Not safe! References issue: https://github.com/MouseLand/cellpose/issues/937

Implications: * Runtime: Runtime increases by 5x-50x due to type casting. However, with resizing being very efficient, this is not a big issue. A 10,000x10,000 image takes 0.47s instead of 0.016s to cast and resize on 32 cores on GPU. * Memory: However, memory usage increases. Not tested by how much.

Parameters:

img (ndarray) – Image of size [Ly x Lx].
Ly (int) – Desired height of the resized image.
Lx (int) – Desired width of the resized image.
interpolation (int, optional) – OpenCV interpolation method. Defaults to cv2.INTER_LINEAR.

Returns:

Resized image of size [Ly x Lx].

Return type:

ndarray

cellpose.transforms.smooth_sharpen_img(img, smooth_radius=6, sharpen_radius=12, device=torch.device, is3D=False)[source]

Sharpen blurry images with surround subtraction and/or smooth noisy images.

Parameters:

img (float32) – Array that’s (Lz x) Ly x Lx (x nchan).
smooth_radius (float, optional) – Size of gaussian smoothing filter, recommended to be 1/10-1/4 of cell diameter (if also sharpening, should be 2-3x smaller than sharpen_radius). Defaults to 6.
sharpen_radius (float, optional) – Size of gaussian surround filter, recommended to be 1/8-1/2 of cell diameter (if also smoothing, should be 2-3x larger than smooth_radius). Defaults to 12.
device (torch.device, optional) – Device on which to perform sharpening. Will be faster on GPU but need to ensure GPU has RAM for image. Defaults to torch.device(“cpu”).
is3D (bool, optional) – If image is 3D stack (only necessary to set if img.ndim==3). Defaults to False.

Returns:

Array that’s (Lz x) Ly x Lx (x nchan).

Return type:

img_sharpen (float32)

cellpose.transforms.unaugment_tiles(y)[source]

Reverse test-time augmentations for averaging (includes flipping of flowsY and flowsX).

Parameters:: y (float32) – Array of shape (ntiles_y, ntiles_x, chan, Ly, Lx) where chan = (flowsY, flowsX, cell prob).
Returns:: Array of shape (ntiles_y, ntiles_x, chan, Ly, Lx).
Return type:: float32

cellpose.transforms.update_axis(m_axis, to_squeeze, ndim)[source]

Squeeze the axis value based on the given parameters.

Parameters:

m_axis (int) – The current axis value.
to_squeeze (numpy.ndarray) – An array of indices to squeeze.
ndim (int) – The number of dimensions.

Returns:

The updated axis value.

Return type:

m_axis (int or None)

I/O functions

cellpose.io.add_model(filename)[source]: add model to .cellpose models folder to use with GUI or CLI

cellpose.io.get_image_files(folder, mask_filter, imf=None, look_one_level_down=False)[source]

Finds all images in a folder and its subfolders (if specified) with the given file extensions.

Parameters:

folder (str) – The path to the folder to search for images.
mask_filter (str) – The filter for mask files.
imf (str, optional) – The additional filter for image files. Defaults to None.
look_one_level_down (bool, optional) – Whether to search for images in subfolders. Defaults to False.

Returns:

A list of image file paths.

Return type:

list

Raises:

ValueError – If no files are found in the specified folder.
ValueError – If no images are found in the specified folder with the supported file extensions.
ValueError – If no images are found in the specified folder without the mask or flow file endings.

cellpose.io.get_label_files(image_names, mask_filter, imf=None)[source]

Get the label files corresponding to the given image names and mask filter.

Parameters:

image_names (list) – List of image names.
mask_filter (str) – Mask filter to be applied.
imf (str, optional) – Image file extension. Defaults to None.

Returns:

A tuple containing the label file names and flow file names (if present).

Return type:

tuple

cellpose.io.imread(filename)[source]

Read in an image file with tif or image file type supported by cv2.

Parameters:: filename (str) – The path to the image file.
Returns:: The image data as a NumPy array.
Return type:: numpy.ndarray
Raises:: None –

Raises an error if the image file format is not supported.

Examples

>>> img = imread("image.tif")

cellpose.io.imread_2D(img_file)[source]

Read in a 2D image file and convert it to a 3-channel image. Attempts to do this for multi-channel and grayscale images. If the image has more than 3 channels, only the first 3 channels are kept.

Parameters:: img_file (str) – The path to the image file.
Returns:: The 3-channel image data as a NumPy array.
Return type:: img_out (numpy.ndarray)

cellpose.io.imread_3D(img_file)[source]

Read in a 3D image file and convert it to have a channel axis last automatically. Attempts to do this for multi-channel and grayscale images.

For grayscale images (3D array), axis 0 is assumed to be the Z axis (e.g., Z x Y x X). For multichannel images (4D array), the channel axis is assumed to be the smallest dimension, and the Z axis is assumed to be the first remaining axis after the channel axis is removed.

Use cellpose.io.imread() to load the full image without automatic axis selection, then specify z_axis and channel_axis manually when calling model.eval.

Parameters:: img_file (str) – The path to the image file.
Returns:: The image data as a NumPy array with channels last, or None if loading fails.
Return type:: img_out (numpy.ndarray)

cellpose.io.imsave(filename, arr)[source]

Saves an image array to a file.

Parameters:

filename (str) – The name of the file to save the image to.
arr (numpy.ndarray) – The image array to be saved.

Returns:

None

cellpose.io.load_images_labels(tdir, mask_filter='_masks', image_filter=None, look_one_level_down=False)[source]

Loads images and corresponding labels from a directory.

Parameters:

tdir (str) – The directory path.
mask_filter (str, optional) – The filter for mask files. Defaults to “_masks”.
image_filter (str, optional) – The filter for image files. Defaults to None.
look_one_level_down (bool, optional) – Whether to look for files one level down. Defaults to False.

Returns:

A tuple containing a list of images, a list of labels, and a list of image names.

Return type:

tuple

cellpose.io.load_train_test_data(train_dir, test_dir=None, image_filter=None, mask_filter='_masks', look_one_level_down=False)[source]

Loads training and testing data for a Cellpose model.

Parameters:

train_dir (str) – The directory path containing the training data.
test_dir (str, optional) – The directory path containing the testing data. Defaults to None.
image_filter (str, optional) – The filter for selecting image files. Defaults to None.
mask_filter (str, optional) – The filter for selecting mask files. Defaults to “_masks”.
look_one_level_down (bool, optional) – Whether to look for data in subdirectories of train_dir and test_dir. Defaults to False.

Returns:

images, labels, image_names, test_images, test_labels, test_image_names

cellpose.io.logger_setup(cp_path='.cellpose', logfile_name='run.log', stdout_file_replacement=None)[source]

Set up logging to a file and stdout (or a file replacement).

Creates the log directory if it doesn’t exist, removes any existing log file, and configures the root logger to write INFO-level and above messages to both a log file and stdout (or a replacement file).

Parameters:

cp_path (str, optional) – Directory name under the user’s home directory for log output. Default is “.cellpose”.
logfile_name (str, optional) – Name of the log file created inside cp_path. Default is “run.log”.
stdout_file_replacement (str or None, optional) – If provided, log output is written to this file path instead of stdout.

Returns:

logger – Configured logger for this module. Only INFO and above messages are emitted by default. To enable debug output, call logger.setLevel(logging.DEBUG) on the returned logger.

Return type:

logging.Logger

Notes

The log file is deleted and recreated on each call.

cellpose.io.masks_flows_to_seg(images, masks, flows, file_names, channels=None, imgs_restore=None, restore_type=None, ratio=1.0)[source]

Save output of model eval to be loaded in GUI.

Can be list output (run on multiple images) or single output (run on single image).

Saved to file_names[k]+”_seg.npy”.

Parameters:

images (list) – Images input into cellpose.
masks (list) – Masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flows (list) – Flows output from Cellpose.eval.
file_names (list, str) – Names of files of images.
diams (float array) – Diameters used to run Cellpose. Defaults to 30. TODO: remove this
channels (list, int, optional) – Channels used to run Cellpose. Defaults to None.

Returns:

None

cellpose.io.remove_model(filename, delete=False)[source]: remove model from .cellpose custom model list

cellpose.io.save_masks(images, masks, flows, file_names, png=True, tif=False, channels=[0, 0], suffix='_cp_masks', save_flows=False, save_outlines=False, dir_above=False, in_folders=False, savedir=None, save_txt=False, save_mpl=False)[source]

Save masks + nicely plotted segmentation image to png and/or tiff.

Can save masks, flows to different directories, if in_folders is True.

If png, masks[k] for images[k] are saved to file_names[k]+”_cp_masks.png”.

If tif, masks[k] for images[k] are saved to file_names[k]+”_cp_masks.tif”.

If png and matplotlib installed, full segmentation figure is saved to file_names[k]+”_cp.png”.

Only tif option works for 3D data, and only tif option works for empty masks.

Parameters:

images (list) – Images input into cellpose.
masks (list) – Masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flows (list) – Flows output from Cellpose.eval.
file_names (list, str) – Names of files of images.
png (bool, optional) – Save masks to PNG. Defaults to True.
tif (bool, optional) – Save masks to TIF. Defaults to False.
channels (list, int, optional) – Channels used to run Cellpose. Defaults to [0,0].
suffix (str, optional) – Add name to saved masks. Defaults to “_cp_masks”.
save_flows (bool, optional) – Save flows output from Cellpose.eval. Defaults to False.
save_outlines (bool, optional) – Save outlines of masks. Defaults to False.
dir_above (bool, optional) – Save masks/flows in directory above. Defaults to False.
in_folders (bool, optional) – Save masks/flows in separate folders. Defaults to False.
savedir (str, optional) – Absolute or relative path where images will be saved. If None, saves to image directory. Defaults to None.
save_txt (bool, optional) – Save masks as list of outlines for ImageJ. Defaults to False.
save_mpl (bool, optional) – If True, saves a matplotlib figure of the original image/segmentation/flows. Does not work for 3D. This takes a long time for large images. Defaults to False.

Returns:

None

cellpose.io.save_rois(masks, file_name, multiprocessing=None, prefix='', pad=False)[source]

save masks to .roi files in .zip archive for ImageJ/Fiji When opened in ImageJ, the ROIs will be named [prefix][0000]n where n is 1,2,… corresponding to the masks label

Parameters:

masks (np.ndarray) – masks output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels
file_name (str) – name to save the .zip file to
multiprocessing (bool, optional) – Flag to enable multiprocessing. Defaults to None (disabled).
prefix (str, optional) – prefix to add at the beginning of the ROI labels in ImageJ. Defaults to no prefix
pad (bool, optional) – Whether to pad the numerical part of the label with zeros so that all labels have the same length

Returns:

None

cellpose.io.save_to_png(images, masks, flows, file_names)[source]

deprecated (runs io.save_masks with png=True)

does not work for 3D images

Utils functions

class cellpose.utils.TqdmToLogger(logger, level=None)[source]

Output stream for TQDM which will output to logger module instead of the StdOut.

flush()[source]

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

write(buf)[source]

Write string to file.

Returns the number of characters written, which is always equal to the length of the string.

cellpose.utils.circleMask(d0)[source]

Creates an array with indices which are the radius of that x,y point.

Parameters:

d0 (tuple) – Patch of (-d0, d0+1) over which radius is computed.

Returns:

A tuple containing:

rs (ndarray): Array of radii with shape (2*d0[0]+1, 2*d0[1]+1).
dx (ndarray): Indices of the patch along the x-axis.
dy (ndarray): Indices of the patch along the y-axis.

Return type:

tuple

cellpose.utils.diameters(masks)[source]

Calculate the diameters of the objects in the given masks.

Parameters: masks (ndarray): masks (0=no cells, 1=first cell, 2=second cell,…)

Returns:: A tuple containing the median diameter and an array of diameters for each object.
Return type:: tuple

Examples: >>> masks = np.array([[0, 1, 1], [1, 0, 0], [1, 1, 0]]) >>> diameters(masks) (1.0, array([1.41421356, 1.0, 1.0]))

cellpose.utils.dilate_masks(masks, n_iter=5)[source]

Dilate masks by n_iter pixels.

Parameters:

masks (ndarray) – Array of masks.
n_iter (int, optional) – Number of pixels to dilate the masks. Defaults to 5.

Returns:

Dilated masks.

Return type:

ndarray

cellpose.utils.distance_to_boundary(masks)[source]

Get the distance to the boundary of mask pixels.

Parameters:: masks (int, 2D or 3D array) – The masks array. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.
Returns:: The distance to the boundary. Size [Ly x Lx] or [Lz x Ly x Lx].
Return type:: dist_to_bound (2D or 3D array)
Raises:: ValueError – If the masks array is not 2D or 3D.

cellpose.utils.download_url_to_file(url, dst, progress=True)[source]

Download object at the given URL to a local path.: Thanks to torch, slightly modified

Parameters:

url (string) – URL of the object to download
dst (string) – Full path where object will be saved, e.g. /tmp/temporary_file
progress (bool, optional) – whether or not to display a progress bar to stderr Default: True

cellpose.utils.fill_holes_and_remove_small_masks(masks, min_size=15)[source]

Fills holes in masks (2D/3D) and discards masks smaller than min_size.

This function fills holes in each mask using fill_voids.fill. It also removes masks that are smaller than the specified min_size.

Parameters: masks (ndarray): Int, 2D or 3D array of labelled masks.

0 represents no mask, while positive integers represent mask labels. The size can be [Ly x Lx] or [Lz x Ly x Lx].

min_size (int, optional): Minimum number of pixels per mask.: Masks smaller than min_size will be removed. Set to -1 to turn off this functionality. Default is 15.

Returns:

Int, 2D or 3D array of masks with holes filled and small masks removed.: 0 represents no mask, while positive integers represent mask labels. The size is [Ly x Lx] or [Lz x Ly x Lx].

Return type:

ndarray

cellpose.utils.get_mask_compactness(masks)[source]

Calculate the compactness of masks.

Parameters:: masks (ndarray) – Binary masks representing objects.
Returns:: Array of compactness values for each mask.
Return type:: ndarray

cellpose.utils.get_mask_perimeters(masks)[source]

Calculate the perimeters of the given masks.

Parameters:: masks (numpy.ndarray) – Binary masks representing objects.
Returns:: Array containing the perimeters of each mask.
Return type:: numpy.ndarray

cellpose.utils.get_mask_stats(masks_true)[source]

Calculate various statistics for the given binary masks.

Parameters:: masks_true (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
Returns:: Convexity values for each mask. solidity (ndarray): Solidity values for each mask. compactness (ndarray): Compactness values for each mask.
Return type:: convexity (ndarray)

cellpose.utils.get_masks_unet(output, cell_threshold=0, boundary_threshold=0)[source]

Create masks using cell probability and cell boundary.

Parameters:

output (ndarray) – The output array containing cell probability and cell boundary.
cell_threshold (float, optional) – The threshold value for cell probability. Defaults to 0.
boundary_threshold (float, optional) – The threshold value for cell boundary. Defaults to 0.

Returns:

The masks representing the segmented cells.

Return type:

ndarray

cellpose.utils.get_outline_multi(args)[source]

Get the outline of a specific mask in a multi-mask image.

Parameters:: args (tuple) – A tuple containing the masks and the mask number.
Returns:: The outline of the specified mask as an array of coordinates.
Return type:: numpy.ndarray

cellpose.utils.get_perimeter(points)[source]

Calculate the perimeter of a set of points.

Parameters:: points (ndarray) – An array of points with shape (npoints, ndim).
Returns:: The perimeter of the points.
Return type:: float

cellpose.utils.masks_to_edges(masks, threshold=1.0)[source]

Get edges of masks as a 0-1 array.

Parameters:

masks (int, 2D or 3D array) – Size [Ly x Lx] or [Lz x Ly x Lx], where 0=NO masks and 1,2,…=mask labels.
threshold (float, optional) – Threshold value for distance to boundary. Defaults to 1.0.

Returns:

Size [Ly x Lx] or [Lz x Ly x Lx], where True pixels are edge pixels.

Return type:

edges (2D or 3D array)

cellpose.utils.masks_to_outlines(masks)[source]

Get outlines of masks as a 0-1 array.

Parameters:: masks (int, 2D or 3D array) – Size [Ly x Lx] or [Lz x Ly x Lx], where 0=NO masks and 1,2,…=mask labels.
Returns:: Size [Ly x Lx] or [Lz x Ly x Lx], where True pixels are outlines.
Return type:: outlines (2D or 3D array)

cellpose.utils.outlines_list(masks, multiprocessing_threshold=1000, multiprocessing=None)[source]

Get outlines of masks as a list to loop over for plotting.

Parameters:

masks (ndarray) – Array of masks.
multiprocessing_threshold (int, optional) – Threshold for enabling multiprocessing. Defaults to 1000.
multiprocessing (bool, optional) – Flag to enable multiprocessing. Defaults to None.

Returns:

List of outlines.

Return type:

list

Raises:

None –

Notes

This function is a wrapper for outlines_list_single and outlines_list_multi.
Multiprocessing is disabled for Windows.

cellpose.utils.outlines_list_multi(masks, num_processes=None)[source]

Get outlines of masks as a list to loop over for plotting.

Parameters:: masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
Returns:: List of outlines as pixel coordinates.
Return type:: list

cellpose.utils.outlines_list_single(masks)[source]

Get outlines of masks as a list to loop over for plotting.

Parameters:: masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
Returns:: List of outlines as pixel coordinates.
Return type:: list

cellpose.utils.radius_distribution(masks, bins)[source]

Calculate the radius distribution of masks.

Parameters:

masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
bins (int) – Number of bins for the histogram.

Returns:

A tuple containing a normalized histogram of radii, median radius, array of radii.

cellpose.utils.remove_edge_masks(masks, change_index=True)[source]

Removes masks with pixels on the edge of the image.

Parameters:

masks (int, 2D or 3D array) – The masks to be processed. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.
change_index (bool, optional) – If True, after removing masks, changes the indexing so that there are no missing label numbers. Defaults to True.

Returns:

The processed masks. Size [Ly x Lx] or [Lz x Ly x Lx], where 0 represents no mask and 1, 2, … represent mask labels.

Return type:

outlines (2D or 3D array)

cellpose.utils.size_distribution(masks)[source]

Calculates the size distribution of masks.

Parameters:: masks (ndarray) – masks (0=no cells, 1=first cell, 2=second cell,…)
Returns:: The ratio of the 25th percentile of mask sizes to the 75th percentile of mask sizes.
Return type:: float

cellpose.utils.stitch3D(masks, stitch_threshold=0.25)[source]

Stitch 2D masks into a 3D volume using a stitch_threshold on IOU.

Parameters:

masks (list or ndarray) – List of 2D masks.
stitch_threshold (float, optional) – Threshold value for stitching. Defaults to 0.25.

Returns:

List of stitched 3D masks.

Return type:

list

Plot functions

cellpose.plot.disk(med, r, Ly, Lx)[source]

Returns the pixels of a disk with a given radius and center.

Parameters:

med (tuple) – The center coordinates of the disk.
r (float) – The radius of the disk.
Ly (int) – The height of the image.
Lx (int) – The width of the image.

Returns:

A tuple containing the y and x coordinates of the pixels within the disk.

Return type:

tuple

cellpose.plot.dx_to_circ(dP)[source]

Converts the optic flow representation to a circular color representation.

Parameters:: dP (ndarray) – Flow field components [dy, dx].
Returns:: The circular color representation of the optic flow.
Return type:: ndarray

cellpose.plot.image_to_rgb(img0, channels=[0, 0])[source]

Converts image from 2 x Ly x Lx or Ly x Lx x 2 to RGB Ly x Lx x 3.

Parameters:: img0 (ndarray) – Input image of shape 2 x Ly x Lx or Ly x Lx x 2.
Returns:: RGB image of shape Ly x Lx x 3.
Return type:: ndarray

cellpose.plot.interesting_patch(mask, bsize=130)[source]

Get patch of size bsize x bsize with most masks.

Parameters:

mask (ndarray) – Input mask.
bsize (int) – Size of the patch.

Returns:

Patch coordinates (y, x).

Return type:

tuple

cellpose.plot.mask_overlay(img, masks, colors=None)[source]

Overlay masks on image (set image to grayscale).

Parameters:

img (int or float, 2D or 3D array) – Image of size [Ly x Lx (x nchan)].
masks (int, 2D array) – Masks where 0=NO masks; 1,2,…=mask labels.
colors (int, 2D array, optional) – Size [nmasks x 3], each entry is a color in 0-255 range.

Returns:

Array of masks overlaid on grayscale image.

Return type:

RGB (uint8, 3D array)

cellpose.plot.mask_rgb(masks, colors=None)[source]

Masks in random RGB colors.

Parameters:

masks (int, 2D array) – Masks where 0=NO masks; 1,2,…=mask labels.
colors (int, 2D array, optional) – Size [nmasks x 3], each entry is a color in 0-255 range.

Returns:

Array of masks overlaid on grayscale image.

Return type:

RGB (uint8, 3D array)

cellpose.plot.outline_view(img0, maski, color=[1, 0, 0], mode='inner')[source]

Generates a red outline overlay onto the image.

Parameters:

img0 (numpy.ndarray) – The input image.
maski (numpy.ndarray) – The mask representing the region of interest.
color (list, optional) – The color of the outline overlay. Defaults to [1, 0, 0] (red).
mode (str, optional) – The mode for generating the outline. Defaults to “inner”.

Returns:

The image with the red outline overlay.

Return type:

numpy.ndarray

cellpose.plot.show_segmentation(fig, img, maski, flowi, channels=[0, 0], file_name=None)[source]

Plot segmentation results (like on website).

Can save each panel of figure with file_name option. Use channels option if img input is not an RGB image with 3 channels.

Parameters:

fig (matplotlib.pyplot.figure) – Figure in which to make plot.
img (ndarray) – 2D or 3D array. Image input into cellpose.
maski (int, ndarray) – For image k, masks[k] output from Cellpose.eval, where 0=NO masks; 1,2,…=mask labels.
flowi (int, ndarray) – For image k, flows[k][0] output from Cellpose.eval (RGB of flows).
channels (list of int, optional) – Channels used to run Cellpose, no need to use if image is RGB. Defaults to [0, 0].
file_name (str, optional) – File name of image. If file_name is not None, figure panels are saved. Defaults to None.
seg_norm (bool, optional) – Improve cell visibility under labels. Defaults to False.

Transformer class

class cellpose.vit_sam.Transformer(*args: Any, **kwargs: Any)[source]

property device

Get the device of the model.

Returns:: The device of the model.
Return type:: torch.device

property dtype

Get the data type of the model.

Returns:: The data type of the model.
Return type:: torch.dtype

save_model(filename)[source]

Save the model to a file.

Parameters:: filename (str) – The path to the file where the model will be saved.

Core functions

cellpose.core.assign_device(use_torch=True, gpu=False, device=0)[source]

Assigns the device (CPU or GPU or mps) to be used for computation.

Parameters:

use_torch (bool, optional) – Whether to use torch for GPU detection. Defaults to True.
gpu (bool, optional) – Whether to use GPU for computation. Defaults to False.
device (int or str, optional) – The device index or name to be used. Defaults to 0.

Returns:

torch.device, bool (True if GPU is used, False otherwise)

cellpose.core.run_3D(net, imgs, batch_size=8, augment=False, tile_overlap=0.1, bsize=224, net_ortho=None, progress=None)[source]

Run network on image z-stack.

(faster if augment is False)

Parameters:

imgs (np.ndarray) – The input image stack of size [Lz x Ly x Lx x nchan].
batch_size (int, optional) – Number of tiles to run in a batch. Defaults to 8.
rsz (float, optional) – Resize coefficient(s) for image. Defaults to 1.0.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
augment (bool, optional) – Tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile_overlap (float, optional) – Fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – Size of tiles to use in pixels [bsize x bsize]. Defaults to 224.
net_ortho (class, optional) – cellpose network for orthogonal ZY and ZX planes. Defaults to None.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.

Returns:

outputs of network y and style. If tiled y is averaged in tile overlaps. Size of [Ly x Lx x 3] or [Lz x Ly x Lx x 3].: y[…,0] is Z flow; y[…,1] is Y flow; y[…,2] is X flow; y[…,3] is cell probability. style is a 1D array of size 256 summarizing the style of the image, if tiled style is averaged over tiles.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

cellpose.core.run_net(net, imgi, batch_size=8, augment=False, tile_overlap=0.1, bsize=224, rsz=None)[source]

Run network on stack of images.

(faster if augment is False)

Parameters:

net (class) – cellpose network (model.net)
imgi (np.ndarray) – The input image or stack of images of size [Lz x Ly x Lx x nchan].
batch_size (int, optional) – Number of tiles to run in a batch. Defaults to 8.
rsz (float, optional) – Resize coefficient(s) for image. Defaults to 1.0.
augment (bool, optional) – Tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile_overlap (float, optional) – Fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – Size of tiles to use in pixels [bsize x bsize]. Defaults to 224.

Returns:

outputs of network y and style. If tiled y is averaged in tile overlaps. Size of [Ly x Lx x 3] or [Lz x Ly x Lx x 3].: y[…,0] is Y flow; y[…,1] is X flow; y[…,2] is cell probability. style is a 1D array of size 256 summarizing the style of the image, if tiled style is averaged over tiles.

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

cellpose.core.use_gpu(gpu_number=0, use_torch=True)[source]

Check if GPU is available for use.

Parameters:

gpu_number (int) – The index of the GPU to be used. Default is 0.
use_torch (bool) – Whether to use PyTorch for GPU check. Default is True.

Returns:

True if GPU is available, False otherwise.

Return type:

bool

Raises:

ValueError – If use_torch is False, as cellpose only runs with PyTorch now.

All models functions

class cellpose.models.CellposeModel(gpu=False, pretrained_model='cpsam', model_type=None, diam_mean=None, device=None, nchan=None, use_bfloat16=True)[source]

Class representing a Cellpose model.

diam_mean

Mean “diameter” value for the model.

Type:: float

builtin

Whether the model is a built-in model or not.

Type:: bool

device

Device used for model running / training.

Type:: torch device

nclasses

Number of classes in the model.

Type:: int

nbase

List of base values for the model.

Type:: list

net

Cellpose network.

Type:: CPnet

pretrained_model

Path to pretrained cellpose model.

Type:: str

pretrained_model_ortho

Path or model_name for pretrained cellpose model for ortho views in 3D.

Type:: str

backbone

Type of network (“default” is the standard res-unet, “transformer” for the segformer).

Type:: str

__init__(self, gpu=False, pretrained_model=False, model_type=None, diam_mean=30., device=None)[source]: Initialize the CellposeModel.

eval(self, x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, stitch_threshold=0.0, min_size=15, niter=None, augment=False, tile_overlap=0.1, bsize=256, interp=True, compute_masks=True, progress=None)[source]: Segment list of images x, or 4D array - Z x C x Y x X.

eval(x, batch_size=8, resample=True, channels=None, channel_axis=None, z_axis=None, normalize=True, invert=False, rescale=None, diameter=None, flow_threshold=0.4, cellprob_threshold=0.0, do_3D=False, anisotropy=None, flow3D_smooth=0, stitch_threshold=0.0, min_size=15, max_size_fraction=0.4, niter=None, augment=False, tile_overlap=0.1, bsize=256, compute_masks=True, progress=None)[source]

segment list of images x, or 4D array - Z x 3 x Y x X

Parameters:

x (list, np.ndarry) – can be list of 2D/3D/4D images, or array of 2D/3D/4D images. Images must have 3 channels.
batch_size (int, optional) – number of 256x256 patches to run simultaneously on the GPU (can make smaller or bigger depending on GPU memory usage). Defaults to 64.
resample (bool, optional) – run dynamics at original image size (will be slower but create more accurate boundaries).
channel_axis (int, optional) – channel axis in element of list x, or of np.ndarray x. if None, channels dimension is attempted to be automatically determined. Defaults to None.
z_axis (int, optional) – z axis in element of list x, or of np.ndarray x. if None, z dimension is attempted to be automatically determined. Defaults to None.
normalize (bool, optional) –
if True, normalize data so 0.0=1st percentile and 1.0=99th percentile of image intensities in each channel; can also pass dictionary of parameters (all keys are optional, default values shown):
- ”lowhigh”=None : pass in normalization values for 0.0 and 1.0 as list [low, high] (if not None, all following parameters ignored)
- ”sharpen”=0 ; sharpen image with high pass filter, recommended to be 1/4-1/8 diameter of cells in pixels
- ”normalize”=True ; run normalization (if False, all following parameters ignored)
- ”percentile”=None : pass in percentiles to use as list [perc_low, perc_high]
- ”tile_norm_blocksize”=0 ; compute normalization in tiles across image to brighten dark areas, to turn on set to window size in pixels (e.g. 100)
- ”norm3D”=True ; compute normalization across entire z-stack rather than plane-by-plane in stitching mode.
Defaults to True.
invert (bool, optional) – invert image pixel intensity before running network. Defaults to False.
rescale (float, optional) – resize factor for each image, if None, set to 1.0; (only used if diameter is None). Defaults to None.
diameter (float or list of float, optional) – diameters are used to rescale the image to 30 pix cell diameter.
flow_threshold (float, optional) – flow error threshold (all cells with errors below threshold are kept) (not used for 3D). Defaults to 0.4.
cellprob_threshold (float, optional) – all pixels with value above threshold kept for masks, decrease to find more and larger masks. Defaults to 0.0.
do_3D (bool, optional) – set to True to run 3D segmentation on 3D/4D image input. Defaults to False.
flow3D_smooth (int or float or list of (int or float), optional) – if do_3D and flow3D_smooth>0, smooth flows with gaussian filter of this stddev. If you are seeing increased fragmentation along the Z axis, or ring-artifacts, you can specify increased smoothing in the z-axis by providing a list, e.g. flow3D_smooth = [2, 1, 1]. List smooths the ZYX axes independently and must be length 3. Defaults to 0.
anisotropy (float, optional) – for 3D segmentation, optional rescaling factor (e.g. set to 2.0 if Z is sampled half as dense as X or Y). Defaults to None.
stitch_threshold (float, optional) – if stitch_threshold>0.0 and not do_3D, masks are stitched in 3D to return volume segmentation. Defaults to 0.0.
min_size (int, optional) – all ROIs below this size, in pixels, will be discarded. Defaults to 15.
max_size_fraction (float, optional) – max_size_fraction (float, optional): Masks larger than max_size_fraction of total image size are removed. Default is 0.4.
niter (int, optional) – number of iterations for dynamics computation. if None, it is set proportional to the diameter. Defaults to None.
augment (bool, optional) – tiles image with overlapping tiles and flips overlapped regions to augment. Defaults to False.
tile_overlap (float, optional) – fraction of overlap of tiles when computing flows. Defaults to 0.1.
bsize (int, optional) – block size for tiles, recommended to keep at 256, like in training. Defaults to 256.
interp (bool, optional) – interpolate during 2D dynamics (not available in 3D) . Defaults to True.
compute_masks (bool, optional) – Whether or not to compute dynamics and return masks. Returns empty array if False. Defaults to True.
progress (QProgressBar, optional) – pyqt progress bar. Defaults to None.

Returns:

masks (list of 2D arrays or single 3D array): Labelled image, where 0=no masks; 1,2,…=mask labels; flows (list of lists 2D arrays or list of 3D arrays):

flows[k][0] = XY flow in HSV 0-255; flows[k][1] = XY flows at each pixel; flows[k][2] = cell probability (if > cellprob_threshold, pixel used for dynamics); flows[k][3] = final pixel locations after Euler integration;

styles (list of 1D arrays of length 256 or single 1D array): Style vector containing only zeros. Retained for compaibility with CP3.

Return type:

A tuple containing (masks, flows, styles)