Class 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/stardist

    Very 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 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 with saveBuilder(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 the PixelCalibration 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 an OpCreators.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 the PixelCalibration 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 using cellExpansion(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 a PathClass 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 if measureIntensity() and cellExpansion(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...) and inputScale(double...) as alternative normalization strategies, if appropriate constants can be determined to apply globally.

        Parameters:
        min - minimum percentile
        max - 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...) and inputScale(double...) as alternative normalization strategies, if appropriate constants can be determined to apply globally.

        Parameters:
        min - minimum percentile
        max - maximum percentile
        perChannel - if true, normalize each channel separately; if false, normalize channels jointly
        eps - 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 with inputScale(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 with inputAdd(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-100
        percentileMax - the max percentile 0-100
        normDownsample - 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: