Class CellposeBuilder
- java.lang.Object
-
- qupath.ext.biop.cellpose.CellposeBuilder
-
public class CellposeBuilder extends java.lang.Object
Cell detection based on the following method:Uwe Schmidt, Martin Weigert, Coleman Broaddus, and Gene Myers. "Cell Detection with Star-convex Polygons." International Conference on Medical Image Computing and Computer-Assisted Intervention (MICCAI), Granada, Spain, September 2018.
See the main repo at https://github.com/mpicbg-csbd/stardistVery much inspired by stardist-imagej at https://github.com/mpicbg-csbd/stardist-imagej but re-written from scratch to use OpenCV and adapt the method of converting predictions to contours (very slightly) to be more QuPath-friendly.
Models are expected in the same format as required by the Fiji plugin, or converted to a frozen .pb file for use with OpenCV.
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
CellposeBuilder(java.io.File builderFile)
can create a cellpose builder from a serialized JSON version of this builder.protected
CellposeBuilder(java.lang.String modelPath)
Build a cellpose model by providing a string which can be the name of a pretrained model or a path to a custom model
-
Method Summary
All Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description CellposeBuilder
addParameter(java.lang.String flagName)
Generic means of adding a cellpose parameterCellposeBuilder
addParameter(java.lang.String flagName, java.lang.String flagValue)
Generic means of adding a cellpose parameterCellposeBuilder
batchSize(java.lang.Integer batchSize)
Defines the batch size for trainingCellpose2D
build()
Create aCellpose2D
, all ready for detection.CellposeBuilder
cellConstrainScale(double scale)
Constrain any cell expansion defined usingcellExpansion(double)
based upon the nucleus size.CellposeBuilder
cellExpansion(double distance)
Amount by which to expand detected nuclei to approximate the cell area.CellposeBuilder
cellposeChannels(java.lang.Integer channel1, java.lang.Integer channel2)
CellposeBuilder
cellprobThreshold(java.lang.Double threshold)
/** cellprob threshold, default is 0, decrease to find more and larger masksCellposeBuilder
channels(int... channels)
Specify channels.CellposeBuilder
channels(java.lang.String... channels)
Specify channels by name.CellposeBuilder
channels(qupath.lib.images.servers.ColorTransforms.ColorTransform... channels)
Define the channels (or color transformers) to apply to the input image.CellposeBuilder
classify(java.lang.String pathClassName)
Request that a classification is applied to all created objects.CellposeBuilder
classify(qupath.lib.objects.classes.PathClass pathClass)
Request that a classification is applied to all created objects.CellposeBuilder
compartments(qupath.lib.analysis.features.ObjectMeasurements.Compartments... compartments)
Specify the compartments within which intensity measurements are made.CellposeBuilder
constrainToParent(boolean constrainToParent)
If true, constrain nuclei and cells to any parent annotation (default is true).CellposeBuilder
createAnnotations()
Create annotations rather than detections (the default).CellposeBuilder
diameter(java.lang.Double diameter)
The estimated diameter of the objects to detect.CellposeBuilder
epochs(java.lang.Integer nEpochs)
Defines the number of epochs for trainingCellposeBuilder
excludeEdges()
Exclude on edges.CellposeBuilder
flowThreshold(java.lang.Double threshold)
Flow error threshold, 0 turns off this optional QC step.CellposeBuilder
ignoreCellOverlaps(boolean ignore)
If true, ignore overlaps when computing cell expansion.CellposeBuilder
inputAdd(double... values)
Add an offset as a preprocessing step.CellposeBuilder
inputScale(double... values)
Multiply by a scale factor as a preprocessing step.CellposeBuilder
inputSubtract(double... values)
Subtract an offset as a preprocessing step.CellposeBuilder
learningRate(java.lang.Double learningRate)
Defines the learning rateCellposeBuilder
maskThreshold(java.lang.Double threshold)
Deprecated.CellposeBuilder
measureIntensity()
Request default intensity measurements are made for all available cell compartments.CellposeBuilder
measureIntensity(java.util.Collection<qupath.lib.analysis.features.ObjectMeasurements.Measurements> measurements)
Request specified intensity measurements are made for all available cell compartments.CellposeBuilder
measureShape()
Request shape measurements are made for the detected cell or nucleus.CellposeBuilder
minTrainMasks(java.lang.Integer n)
Excludes training data with less than n training masks (n labels)CellposeBuilder
modelDirectory(java.io.File modelDir)
Define the directory where the newly trained model should be savedCellposeBuilder
noCellposeNormalization()
convenience method? to deactivate cellpose normalization.CellposeBuilder
normalizePercentiles(double min, double max)
Apply percentile normalization separately to the input image channels.CellposeBuilder
normalizePercentiles(double min, double max, boolean perChannel, double eps)
Apply percentile normalization to the input image channels, or across all channels jointly.CellposeBuilder
normalizePercentilesGlobal(double percentileMin, double percentileMax, double normDownsample)
Convenience method to call global normalization for the datasetCellposeBuilder
pixelSize(double pixelSize)
Resolution at which the cell detection should be run.CellposeBuilder
preprocess(OpCreators.TileOpCreator global)
Add anOpCreators.TileOpCreator
to generate preprocessing operations based upon the entire image, rather than per tile.CellposeBuilder
preprocess(qupath.opencv.ops.ImageOp... ops)
Add preprocessing operations, if required.CellposeBuilder
saveBuilder(java.lang.String name)
Save this builder as a JSON file in order to be able to reuse it in placeCellposeBuilder
setOverlap(int overlap)
Set the overlap (in pixels) between tiles.CellposeBuilder
simplify(double distance)
Customize the extent to which contours are simplified.CellposeBuilder
tileSize(int tileSize)
Size in pixels of a tile used for detection.CellposeBuilder
tileSize(int tileWidth, int tileHeight)
Size in pixels of a tile used for detection.CellposeBuilder
useOmnipose()
Use Omnipose implementation: Adds --omni flag to command
-
-
-
Constructor Detail
-
CellposeBuilder
protected CellposeBuilder(java.io.File builderFile)
can create a cellpose builder from a serialized JSON version of this builder.- Parameters:
builderFile
- the path to a serialized JSON builder made withsaveBuilder(String)
-
CellposeBuilder
protected CellposeBuilder(java.lang.String modelPath)
Build a cellpose model by providing a string which can be the name of a pretrained model or a path to a custom model- Parameters:
modelPath
- the model name or path
-
-
Method Detail
-
pixelSize
public CellposeBuilder pixelSize(double pixelSize)
Resolution at which the cell detection should be run. The units depend upon thePixelCalibration
of the input image.The default is to use the full resolution of the input image.
For an image calibrated in microns, the recommended default is approximately 0.5.
- Parameters:
pixelSize
- Pixel size in microns for the analysis- Returns:
- this builder
-
preprocess
public CellposeBuilder preprocess(qupath.opencv.ops.ImageOp... ops)
Add preprocessing operations, if required.- Parameters:
ops
-- Returns:
- this builder
-
preprocess
public CellposeBuilder preprocess(OpCreators.TileOpCreator global)
Add anOpCreators.TileOpCreator
to generate preprocessing operations based upon the entire image, rather than per tile.Note that only a single such operation is permitted, which is applied after channel extraction but before any other preprocessing.
The intended use is with
OpCreators.imageNormalizationBuilder()
to perform normalization based upon percentiles computed across the image, rather than per tile.- Parameters:
global
- preprocessing operation- Returns:
- this builder
-
simplify
public CellposeBuilder simplify(double distance)
Customize the extent to which contours are simplified. Simplification reduces the number of vertices, which in turn can reduce memory requirements and improve performance.Implementation note: this currently uses the Visvalingam-Whyatt algorithm.
- Parameters:
distance
- simplify distance threshold; set ≤ 0 to turn off additional simplification- Returns:
- this builder
-
channels
public CellposeBuilder channels(int... channels)
Specify channels. Useful for detecting nuclei for one channel within a multi-channel image, or potentially for trained models that support multi-channel input.- Parameters:
channels
- 0-based indices of the channels to use- Returns:
- this builder
-
channels
public CellposeBuilder channels(java.lang.String... channels)
Specify channels by name. Useful for detecting nuclei for one channel within a multi-channel image, or potentially for trained models that support multi-channel input.- Parameters:
channels
- 0-based indices of the channels to use- Returns:
- this builder
-
channels
public CellposeBuilder channels(qupath.lib.images.servers.ColorTransforms.ColorTransform... channels)
Define the channels (or color transformers) to apply to the input image.This makes it possible to supply color deconvolved channels, for example.
- Parameters:
channels
-- Returns:
- this builder
-
cellExpansion
public CellposeBuilder cellExpansion(double distance)
Amount by which to expand detected nuclei to approximate the cell area. Units are the same as for thePixelCalibration
of the input image.Warning! This is rather experimental, relying heavily on JTS and a convoluted method of resolving overlaps using a Voronoi tessellation.
In short, be wary.
- Parameters:
distance
-- Returns:
- this builder
-
cellConstrainScale
public CellposeBuilder cellConstrainScale(double scale)
Constrain any cell expansion defined usingcellExpansion(double)
based upon the nucleus size. Only meaningful for values > 1; the nucleus is expanded according to the scale factor, and used to define the maximum permitted cell expansion.- Parameters:
scale
-- Returns:
- this builder
-
createAnnotations
public CellposeBuilder createAnnotations()
Create annotations rather than detections (the default). If cell expansion is not zero, the nucleus will be included as a child object.- Returns:
- this builder
-
classify
public CellposeBuilder classify(qupath.lib.objects.classes.PathClass pathClass)
Request that a classification is applied to all created objects.- Parameters:
pathClass
-- Returns:
- this builder
-
classify
public CellposeBuilder classify(java.lang.String pathClassName)
Request that a classification is applied to all created objects. This is a convenience method that get aPathClass
from a String representation.- Parameters:
pathClassName
-- Returns:
- this builder
-
ignoreCellOverlaps
public CellposeBuilder ignoreCellOverlaps(boolean ignore)
If true, ignore overlaps when computing cell expansion.- Parameters:
ignore
-- Returns:
- this builder
-
constrainToParent
public CellposeBuilder constrainToParent(boolean constrainToParent)
If true, constrain nuclei and cells to any parent annotation (default is true).- Parameters:
constrainToParent
-- Returns:
- this builder
-
measureIntensity
public CellposeBuilder measureIntensity()
Request default intensity measurements are made for all available cell compartments.- Returns:
- this builder
-
measureIntensity
public CellposeBuilder measureIntensity(java.util.Collection<qupath.lib.analysis.features.ObjectMeasurements.Measurements> measurements)
Request specified intensity measurements are made for all available cell compartments.- Parameters:
measurements
- the measurements to make- Returns:
- this builder
-
measureShape
public CellposeBuilder measureShape()
Request shape measurements are made for the detected cell or nucleus.- Returns:
- this builder
-
compartments
public CellposeBuilder compartments(qupath.lib.analysis.features.ObjectMeasurements.Compartments... compartments)
Specify the compartments within which intensity measurements are made. Only effective ifmeasureIntensity()
andcellExpansion(double)
have been selected.- Parameters:
compartments
- cell compartments for intensity measurements- Returns:
- this builder
-
tileSize
public CellposeBuilder tileSize(int tileSize)
Size in pixels of a tile used for detection. Note that tiles are independently normalized, and therefore tiling can impact the results. Default is 1024.- Parameters:
tileSize
-- Returns:
- this builder
-
tileSize
public CellposeBuilder tileSize(int tileWidth, int tileHeight)
Size in pixels of a tile used for detection. Note that tiles are independently normalized, and therefore tiling can impact the results. Default is 1024.- Parameters:
tileWidth
-tileHeight
-- Returns:
- this builder
-
normalizePercentiles
public CellposeBuilder normalizePercentiles(double min, double max)
Apply percentile normalization separately to the input image channels.Note that this can be used in combination with
preprocess(ImageOp...)
, in which case the order in which the operations are applied depends upon the order in which the methods of the builder are called.Warning! This is applied on a per-tile basis. This can result in artifacts and false detections without background/constant regions. Consider using
inputAdd(double...)
andinputScale(double...)
as alternative normalization strategies, if appropriate constants can be determined to apply globally.- Parameters:
min
- minimum percentilemax
- maximum percentile- Returns:
- this builder
- See Also:
normalizePercentiles(double, double, boolean, double)
-
normalizePercentiles
public CellposeBuilder normalizePercentiles(double min, double max, boolean perChannel, double eps)
Apply percentile normalization to the input image channels, or across all channels jointly.Note that this can be used in combination with
preprocess(ImageOp...)
, in which case the order in which the operations are applied depends upon the order in which the methods of the builder are called.Warning! This is applied on a per-tile basis. This can result in artifacts and false detections without background/constant regions. Consider using
inputAdd(double...)
andinputScale(double...)
as alternative normalization strategies, if appropriate constants can be determined to apply globally.- Parameters:
min
- minimum percentilemax
- maximum percentileperChannel
- if true, normalize each channel separately; if false, normalize channels jointlyeps
- small constant to apply- Returns:
- this builder
- Since:
- v0.4.0
-
inputAdd
public CellposeBuilder inputAdd(double... values)
Add an offset as a preprocessing step. Usually the value will be negative. Along withinputScale(double...)
this can be used as an alternative (global) normalization.Note that this can be used in combination with
preprocess(ImageOp...)
, in which case the order in which the operations are applied depends upon the order in which the methods of the builder are called.- Parameters:
values
- either a single value to add to all channels, or an array of values equal to the number of channels- Returns:
- this builder
- See Also:
inputSubtract(double...)
,inputScale(double...)
-
inputSubtract
public CellposeBuilder inputSubtract(double... values)
Subtract an offset as a preprocessing step.Note that this can be used in combination with
preprocess(ImageOp...)
, in which case the order in which the operations are applied depends upon the order in which the methods of the builder are called.- Parameters:
values
- either a single value to subtract from all channels, or an array of values equal to the number of channels- Returns:
- this builder
- Since:
- v0.4.0
- See Also:
inputAdd(double...)
,inputScale(double...)
-
inputScale
public CellposeBuilder inputScale(double... values)
Multiply by a scale factor as a preprocessing step. Along withinputAdd(double...)
this can be used as an alternative (global) normalization.Note that this can be used in combination with
preprocess(ImageOp...)
, in which case the order in which the operations are applied depends upon the order in which the methods of the builder are called.- Parameters:
values
- either a single value to add to all channels, or an array of values equal to the number of channels- Returns:
- this builder
- See Also:
inputAdd(double...)
,inputSubtract(double...)
-
addParameter
public CellposeBuilder addParameter(java.lang.String flagName, java.lang.String flagValue)
Generic means of adding a cellpose parameter- Parameters:
flagName
- the name of the flag, eg. "save_every"flagValue
- the value that is linked to the flag, eg. "20". Can be an empty string or null if it is not needed- Returns:
- this builder
- See Also:
- the cellpose documentation for a list of available flags
-
addParameter
public CellposeBuilder addParameter(java.lang.String flagName)
Generic means of adding a cellpose parameter- Parameters:
flagName
- the name of the flag, eg. "save_every" * @param flagName the name of the flag, eg. "save_every"- Returns:
- See Also:
- the cellpose documentation for a list of available flags
-
useOmnipose
public CellposeBuilder useOmnipose()
Use Omnipose implementation: Adds --omni flag to command- Returns:
- this builder
-
excludeEdges
public CellposeBuilder excludeEdges()
Exclude on edges. Adds --exclude_on_edges flag to cellpose command- Returns:
- this builder
-
cellposeChannels
public CellposeBuilder cellposeChannels(java.lang.Integer channel1, java.lang.Integer channel2)
-
maskThreshold
public CellposeBuilder maskThreshold(java.lang.Double threshold)
Deprecated.cellprob threshold, default is 0, decrease to find more and larger masks- Parameters:
threshold
- cell/nuclei masks threshold, between -6 and +6- Returns:
- this builder
-
cellprobThreshold
public CellposeBuilder cellprobThreshold(java.lang.Double threshold)
/** cellprob threshold, default is 0, decrease to find more and larger masks- Parameters:
threshold
- cell/nuclei masks threshold, between -6 and +6- Returns:
- this builder
-
flowThreshold
public CellposeBuilder flowThreshold(java.lang.Double threshold)
Flow error threshold, 0 turns off this optional QC step. Default: 0.- Parameters:
threshold
- flow threshold (default 0.0)- Returns:
- this builder
-
diameter
public CellposeBuilder diameter(java.lang.Double diameter)
The estimated diameter of the objects to detect. Cellpose will further downsample (or upsample) the images in order to match the diamteter corresponding to the model being used- Parameters:
diameter
- in pixels- Returns:
- this builder
-
modelDirectory
public CellposeBuilder modelDirectory(java.io.File modelDir)
Define the directory where the newly trained model should be saved- Parameters:
modelDir
- a directory (does not need to exist yet) where to save the cellpose model- Returns:
- this Builder
-
epochs
public CellposeBuilder epochs(java.lang.Integer nEpochs)
Defines the number of epochs for training- Parameters:
nEpochs
- number of epochs for training- Returns:
- this Builder
-
learningRate
public CellposeBuilder learningRate(java.lang.Double learningRate)
Defines the learning rate- Parameters:
learningRate
- learning rate per epoch- Returns:
- this Builder
-
batchSize
public CellposeBuilder batchSize(java.lang.Integer batchSize)
Defines the batch size for training- Parameters:
batchSize
- batch size for training- Returns:
- this Builder
-
minTrainMasks
public CellposeBuilder minTrainMasks(java.lang.Integer n)
Excludes training data with less than n training masks (n labels)- Parameters:
n
- minimum number of labels per training image- Returns:
- this builder
-
saveBuilder
public CellposeBuilder saveBuilder(java.lang.String name)
Save this builder as a JSON file in order to be able to reuse it in place- Parameters:
name
- // A name to append to the JSON file. Keep it meaningful for your needs- Returns:
- this builder
-
setOverlap
public CellposeBuilder setOverlap(int overlap)
Set the overlap (in pixels) between tiles. This overlap should be larger than 2x the largest object you are trying to segment- Parameters:
overlap
- the overlap, in pixels- Returns:
- this builder
-
normalizePercentilesGlobal
public CellposeBuilder normalizePercentilesGlobal(double percentileMin, double percentileMax, double normDownsample)
Convenience method to call global normalization for the dataset- Parameters:
percentileMin
- the min percentile 0-100percentileMax
- the max percentile 0-100normDownsample
- a large downsample for the computation to be efficient over the whole image- Returns:
- this builder
-
noCellposeNormalization
public CellposeBuilder noCellposeNormalization()
convenience method? to deactivate cellpose normalization.- Returns:
-
build
public Cellpose2D build()
Create aCellpose2D
, all ready for detection.- Returns:
-
-