Package qupath.lib.analysis.images

Class ContourTracing

java.lang.Object
qupath.lib.analysis.images.ContourTracing
public class ContourTracing extends Object
Class to convert labelled images to Geometry objects, ROIs and PathObjects.

  • Constructor Details

    • ContourTracing

      public ContourTracing()

  • Method Details

    • labelsToDetections

      public static List<PathObject> labelsToDetections(Collection<Path> paths, boolean mergeByLabel) throws IOException
      Convert labeled images to detection objects, determining the region from the filename if possible.
      Parameters:
      paths - paths to image files (e.g. PNGs)
      mergeByLabel - if true, merge objects with the same ROI label
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToCells

      public static List<PathObject> labelsToCells(Collection<Path> paths, boolean mergeByLabel) throws IOException
      Convert 2-channel labeled images to cell objects, determining the region from the filename if possible.
      Parameters:
      paths - paths to image files (e.g. PNGs)
      mergeByLabel - if true, merge objects with the same ROI label
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToDetections

      public static List<PathObject> labelsToDetections(Path path, RegionRequest request) throws IOException
      Convert a labeled image to detection objects.
      Parameters:
      path - path to labeled image file (e.g. PNGs)
      request - a RegionRequest representing the region or the full image, used to reposition and rescale ROIs. If not provided, this will be extracted from the filename, if possible.
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToCells

      public static List<PathObject> labelsToCells(Path path, RegionRequest request) throws IOException
      Convert a 2-channel labeled image to cell objects.
      Parameters:
      path - path to labeled image file (e.g. PNGs)
      request - a RegionRequest representing the region or the full image, used to reposition and rescale ROIs. If not provided, this will be extracted from the filename, if possible.
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToAnnotations

      public static List<PathObject> labelsToAnnotations(Collection<Path> paths, boolean mergeByLabel) throws IOException
      Convert labeled images to annotation objects, determining the region from the filename if possible.
      Parameters:
      paths - paths to image files (e.g. PNGs)
      mergeByLabel - if true, merge objects with the same ROI label
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToAnnotations

      public static List<PathObject> labelsToAnnotations(Path path, RegionRequest request) throws IOException
      Convert a labeled image to annotation objects.
      Parameters:
      path - path to labeled image file (e.g. PNGs)
      request - a RegionRequest representing the region or the full image, used to reposition and rescale ROIs. If not provided, this will be extracted from the filename, if possible.
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • labelsToObjects

      public static List<PathObject> labelsToObjects(Path path, RegionRequest request, BiFunction<ROI,Number,PathObject> creator) throws IOException
      Convert a labeled image to objects.
      Parameters:
      path - path to labeled image file (e.g. PNGs)
      request - a RegionRequest representing the region or the full image, used to reposition and rescale ROIs. If not provided, this will be extracted from the filename, if possible.
      creator - function used to convert a ROI and numeric label to an object
      Returns:
      a list of objects generated from the labels
      Throws:
      IOException - if there is an error reading the images

    • parseRegion

      public static RegionRequest parseRegion(String name, int width, int height)
      Attempt to parse a RegionRequest corresponding to an image region from the file name.

      This is used whenever a tile has been extracted from a larger image for further processing, and then there is a need to get the information back to the full-resolution image later.

      Parameters:
      name - file name
      width - labeled image width, used to calculate the downsample if required; use -1 to ignore this
      height - labeled image height, used to calculate the downsample if required; use -1 to ignore this
      Returns:
      a RegionRequest that may be used to transform ROIs

    • createObjects

      public static List<PathObject> createObjects(Raster raster, int band, RegionRequest region, int minLabel, int maxLabel, BiFunction<ROI,Number,PathObject> creator)
      Create objects from one band of a raster containing integer labels.
      Parameters:
      raster - the raster containing integer label values
      band - the band of interest (usually 0)
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      creator - function to convert the traced ROI and associated numeric label into a PathObject
      Returns:
      a list of all created objects

    • createObjects

      public static List<PathObject> createObjects(SimpleImage image, RegionRequest region, int minLabel, int maxLabel, BiFunction<ROI,Number,PathObject> creator)
      Create objects from a labelled image.
      Parameters:
      image - the labelled image
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      creator - function to convert the traced ROI and associated numeric label into a PathObject
      Returns:
      a list of all created objects

    • createDetections

      public static List<PathObject> createDetections(SimpleImage image, RegionRequest region, int minLabel, int maxLabel)
      Create detection objects from a labelled image.
      Parameters:
      image - the labelled image
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      a list of all created objects

    • createAnnotations

      public static List<PathObject> createAnnotations(SimpleImage image, RegionRequest region, int minLabel, int maxLabel)
      Create annotation objects from a labelled image.
      Parameters:
      image - the labelled image
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      a list of all created objects

    • createNumberedObjectFunction

      public static BiFunction<ROI,Number,PathObject> createNumberedObjectFunction(Function<ROI,PathObject> creator)
      Create a (bi)function to generate an object from a ROI and a number, setting the name of the object to match the number.
      Parameters:
      creator -
      Returns:
      a function compatible with createObjects(SimpleImage, RegionRequest, int, int, BiFunction)
      See Also:

    • createObjectFunction

      public static BiFunction<ROI,Number,PathObject> createObjectFunction(Function<ROI,PathObject> creator, BiConsumer<PathObject,Number> numberer)
      Create a (bi)function to generate an object from a ROI and a number.
      Parameters:
      creator - the function to create the object from the ROI
      numberer - the function to manipulate the object based on the number (e.g. to set the name, classification or measurements)
      Returns:
      a function compatible with createObjects(SimpleImage, RegionRequest, int, int, BiFunction)
      See Also:

    • createCells

      public static List<PathObject> createCells(Raster raster, int bandNuclei, int bandCells, RegionRequest region, int minLabel, int maxLabel)
      Create cell objects from two bands of a raster representing a labelled image.
      Parameters:
      raster - the raster containing the labelled pixels
      bandNuclei - the band containing the labelled nucleus pixels
      bandCells - the band containing the labelled cell pixels
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      a list of all created cells

    • createCells

      public static List<PathObject> createCells(SimpleImage imageNuclei, SimpleImage imageCells, RegionRequest region, int minLabel, int maxLabel)
      Create cell objects from a pair of labelled images.
      Parameters:
      imageNuclei - the labelled image containing cell nuclei
      imageCells - the labelled image containing full cell regions; labels must match with imageNuclei
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      a list of all created cells

    • maybeCellLabels

      public static boolean maybeCellLabels(Raster raster, int bandNuclei, int bandCells, int minLabel)
      Check whether a raster could be used to generate cell objects, by providing a nucleus and corresponding cell labels.
      Parameters:
      raster - the image raster containing labelled images
      bandNuclei - band corresponding to the potential labeled image for nuclei
      bandCells - band corresponding to the potential labeled image for cells
      minLabel - the minimum positive label (usually 1). All pixels in imageNuclei with a value ≥ minLabel must have the same value in imageCells.
      Returns:
      true if the images could provide nuclei and cell regions, false otherwise
      Implementation Requirements
      this returns true if bandNuclei == bandCells, since this could potentially provide cell objects (with no cytoplasm).

    • maybeCellLabels

      public static boolean maybeCellLabels(SimpleImage imageNuclei, SimpleImage imageCells, int minLabel)
      Check whether two images could be used to generate cell objects, by providing a nucleus and corresponding cell labels.
      Parameters:
      imageNuclei - potential labeled image for nuclei
      imageCells - potential labeled image for cells
      minLabel - the minimum positive label (usually 1). All pixels in imageNuclei with a value ≥ minLabel must have the same value in imageCells.
      Returns:
      true if the images could provide nuclei and cell regions, false otherwise

    • extractBand

      public static SimpleImage extractBand(Raster raster, int band)
      Extract a band from a a raster as a SimpleImage.
      Parameters:
      raster - the raster
      band - the band (0-based index)
      Returns:
      a SimpleImage containing a duplicate copy of the pixels in raster

    • createROIs

      public static Map<Number,ROI> createROIs(Raster raster, int band, RegionRequest region, int minLabel, int maxLabel)
      Create ROIs from one band of a raster containing integer label values.
      Parameters:
      raster - the raster containing integer label values
      band - the band of interest (usually 0)
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      an ordered map containing all the ROIs that could be found; corresponding labels are keys in the map

    • createGeometries

      public static Map<Number,Geometry> createGeometries(SimpleImage image, RegionRequest region, int minLabel, int maxLabel)
      Create Geometries from a labelled image containing integer labels.
      Parameters:
      image - the labelled image
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      an ordered map containing all the ROIs that could be found; corresponding labels are keys in the map

    • createROIs

      public static Map<Number,ROI> createROIs(SimpleImage image, RegionRequest region, int minLabel, int maxLabel)
      Create ROIs from a labelled image containing integer labels.
      Parameters:
      image - the labelled image
      region - region used to convert coordinates into the full image space (optional)
      minLabel - minimum label; usually 1, but may be 0 if a background ROI should be created
      maxLabel - maximum label; if less than minLabel, the maximum label will be found in the image and used
      Returns:
      an ordered map containing all the ROIs that could be found; corresponding labels are keys in the map

    • createTracedROI

      public static ROI createTracedROI(Raster raster, double minThresholdInclusive, double maxThresholdInclusive, int band, RegionRequest request)
      Create a traced ROI from a raster.
      Parameters:
      raster - input raster
      minThresholdInclusive - minimum threshold value
      maxThresholdInclusive - maximum threshold value
      band - band (channel) to threshold
      request - region request used to translate and rescale to the image space, and determine the image plane
      Returns:
      a ROI created by tracing pixel values ≥ minThresholdInclusive and ≤ maxThresholdInclusive
      See Also:

    • createTracedROI

      public static ROI createTracedROI(SimpleImage image, double minThresholdInclusive, double maxThresholdInclusive, RegionRequest request)
      Create a traced ROI from a SimpleImage.
      Parameters:
      image - input image
      minThresholdInclusive - minimum threshold value
      maxThresholdInclusive - maximum threshold value
      request - region request used to translate and rescale to the image space, and determine the image plane
      Returns:
      a ROI created by tracing pixel values ≥ minThresholdInclusive and ≤ maxThresholdInclusive
      See Also:

    • createTracedGeometry

      public static Geometry createTracedGeometry(SimpleImage image, double minThresholdInclusive, double maxThresholdInclusive, RegionRequest request)
      Create a traced geometry from a SimpleImage.
      Parameters:
      image - input image
      minThresholdInclusive - minimum threshold value
      maxThresholdInclusive - maximum threshold value
      request - optional region request; if provided, the geometry will be translated and rescaled to the image space
      Returns:
      a polygonal geometry created by tracing pixel values ≥ minThresholdInclusive and ≤ maxThresholdInclusive

    • createTracedGeometry

      public static Geometry createTracedGeometry(Raster raster, double minThresholdInclusive, double maxThresholdInclusive, int band, RegionRequest request)
      Create a traced geometry from a raster.
      Parameters:
      raster - input raster
      minThresholdInclusive - minimum threshold value
      maxThresholdInclusive - maximum threshold value
      band - band (channel) to threshold
      request - optional region request; if provided, the geometry will be translated and rescaled to the image space
      Returns:
      a polygonal geometry created by tracing pixel values ≥ minThresholdInclusive and ≤ maxThresholdInclusive

    • traceGeometry

      public static Geometry traceGeometry(ImageServer<BufferedImage> server, RegionRequest regionRequest, Geometry clipArea, int channel, double minThreshold, double maxThreshold) throws IOException
      Trace a geometry from a single channel of a single image.
      Parameters:
      server -
      regionRequest -
      clipArea -
      channel -
      minThreshold -
      maxThreshold -
      Returns:
      Throws:
      IOException

    • traceGeometries

      public static Map<Integer,Geometry> traceGeometries(ImageServer<BufferedImage> server, RegionRequest regionRequest, Geometry clipArea, ContourTracing.ChannelThreshold... thresholds) throws IOException
      Trace one or more geometries in an image.
      Parameters:
      server -
      regionRequest - optional region defining the area within which geometries should be traced
      clipArea - optional clip region, intersected with the created geometries (may be null)
      thresholds - min/max thresholds (inclusive) to apply to each channel to generate objects
      Returns:
      Throws:
      IOException