Package qupath.ext.biop.cellpose

Class CellposeBuilder

java.lang.Object
qupath.ext.biop.cellpose.CellposeBuilder
public class CellposeBuilder extends 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 ...

Very much inspired by stardist-imagej at ... 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 Details

    • CellposeBuilder

      protected CellposeBuilder(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(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 Details

    • extendChannelOp

      public CellposeBuilder extendChannelOp(qupath.opencv.ops.ImageOp extendChannelOp)

    • useGPU

      public CellposeBuilder useGPU(boolean useGPU)
      overwrite use GPU
      Parameters:
      useGPU - add or remove the option
      Returns:
      this builder

    • groundTruthDirectory

      public CellposeBuilder groundTruthDirectory(File groundTruthDirectory)
      Specify the training directory

    • tempDirectory

      public CellposeBuilder tempDirectory(File trainingDirectory)
      Specify the temporary directory

    • nThreads

      public CellposeBuilder nThreads(int nThreads)
      Specify the number of threads to use for processing. If you encounter problems, setting this to 1 may help to resolve them by preventing multithreading.
      Parameters:
      nThreads - the number of threads to use
      Returns:
      this builder

    • readResultsAsynchronously

      public CellposeBuilder readResultsAsynchronously()
      Use an asynchronous method to read the results from the cellpose as it writes files Can result in faster processing. !!EXPERIMENTAL!!

    • 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 - a series of ImageOps to apply to the input image
      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(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 - the channels to use
      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 - expansion distance in microns
      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 - the classification to give to all detected PathObjects
      Returns:
      this builder

    • classify

      public CellposeBuilder classify(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 - the classification to give to all detected PathObjects as a String
      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(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 - the width and height of each tile for exporting images
      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 - the width of each tile for exporting images
      tileHeight - the height of each tile for exporting images
      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

      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

      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:

    • 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:

    • addParameter

      public CellposeBuilder addParameter(String flagName, 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:

    • addParameter

      public CellposeBuilder addParameter(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:

    • 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(Integer channel1, Integer channel2)
      Explicitly set the cellpose channels manually. This corresponds to --chan and --chan2
      Parameters:
      channel1 - --chan value passed to cellpose/omnipose
      channel2 - --chan2 value passed to cellpose/omnipose
      Returns:
      this builder

    • maskThreshold

      @Deprecated public CellposeBuilder maskThreshold(Double threshold)
      Deprecated.
      use cellprobThreshold(Double)
      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(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(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(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(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(Integer nEpochs)
      Defines the number of epochs for training
      Parameters:
      nEpochs - number of epochs for training
      Returns:
      this Builder

    • learningRate

      public CellposeBuilder learningRate(Double learningRate)
      Defines the learning rate
      Parameters:
      learningRate - learning rate per epoch
      Returns:
      this Builder

    • batchSize

      public CellposeBuilder batchSize(Integer batchSize)
      Defines the batch size for training
      Parameters:
      batchSize - batch size for training
      Returns:
      this Builder

    • minTrainMasks

      public CellposeBuilder minTrainMasks(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(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:
      this builder

    • setOutputModelName

      public CellposeBuilder setOutputModelName(String outputName)
      Set the final model name. Setting this to "My Model" would lead to the final cellpose file being called "My Model_yyyy-MM-dd_HH_mm.cpm" with the current timestamp and .cpm meaning Cellpose Model
      Parameters:
      outputName - the prefix os the cellpose model name
      Returns:
      this builder

    • build

      public Cellpose2D build()
      Create a Cellpose2D, all ready for detection.
      Returns:
      a new Cellpose2D instance