Package qupath.lib.analysis.images
Class ContourTracing
java.lang.Object
qupath.lib.analysis.images.ContourTracing
Class to convert labelled images to Geometry objects, ROIs and PathObjects.
- Author:
- Pete Bankhead
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classHelper class defining global thresholds to apply to a single image channel. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionstatic List<PathObject>createAnnotations(SimpleImage image, RegionRequest region, int minLabel, int maxLabel) Create annotation objects from a labelled image.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.static List<PathObject>createCells(SimpleImage imageNuclei, SimpleImage imageCells, RegionRequest region, int minLabel, int maxLabel) Create cell objects from a pair of labelled images.static List<PathObject>createDetections(SimpleImage image, RegionRequest region, int minLabel, int maxLabel) Create detection objects from a labelled image.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.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.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.static List<PathObject>createObjects(SimpleImage image, RegionRequest region, int minLabel, int maxLabel, BiFunction<ROI, Number, PathObject> creator) Create objects from a labelled image.createROIs(Raster raster, int band, RegionRequest region, int minLabel, int maxLabel) Create ROIs from one band of a raster containing integer label values.createROIs(SimpleImage image, RegionRequest region, int minLabel, int maxLabel) Create ROIs from a labelled image containing integer labels.static GeometrycreateTracedGeometry(Raster raster, double minThresholdInclusive, double maxThresholdInclusive, int band, RegionRequest request) Create a traced geometry from a raster.static GeometrycreateTracedGeometry(SimpleImage image, double minThresholdInclusive, double maxThresholdInclusive, RegionRequest request) Create a traced geometry from aSimpleImage.static ROIcreateTracedROI(Raster raster, double minThresholdInclusive, double maxThresholdInclusive, int band, RegionRequest request) Create a traced ROI from a raster.static ROIcreateTracedROI(SimpleImage image, double minThresholdInclusive, double maxThresholdInclusive, RegionRequest request) Create a traced ROI from aSimpleImage.static SimpleImageextractBand(Raster raster, int band) Extract a band from a a raster as aSimpleImage.static List<PathObject>labelsToAnnotations(Path path, RegionRequest request) Convert a labeled image to annotation objects.static List<PathObject>labelsToAnnotations(Collection<Path> paths, boolean mergeByLabel) Convert labeled images to annotation objects, determining the region from the filename if possible.static List<PathObject>labelsToCells(Path path, RegionRequest request) Convert a 2-channel labeled image to cell objects.static List<PathObject>labelsToCells(Collection<Path> paths, boolean mergeByLabel) Convert 2-channel labeled images to cell objects, determining the region from the filename if possible.static List<PathObject>labelsToDetections(Path path, RegionRequest request) Convert a labeled image to detection objects.static List<PathObject>labelsToDetections(Collection<Path> paths, boolean mergeByLabel) Convert labeled images to detection objects, determining the region from the filename if possible.static List<PathObject>labelsToObjects(Path path, RegionRequest request, BiFunction<ROI, Number, PathObject> creator) Convert a labeled image to objects.static booleanmaybeCellLabels(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.static booleanmaybeCellLabels(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.static RegionRequestparseRegion(String name, int width, int height) Attempt to parse aRegionRequestcorresponding to an image region from the file name.traceGeometries(ImageServer<BufferedImage> server, RegionRequest regionRequest, Geometry clipArea, ContourTracing.ChannelThreshold... thresholds) Trace one or more geometries in an image.static GeometrytraceGeometry(ImageServer<BufferedImage> server, RegionRequest regionRequest, Geometry clipArea, int channel, double minThreshold, double maxThreshold) Trace a geometry from a single channel of a single image.
-
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- aRegionRequestrepresenting 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
Convert a 2-channel labeled image to cell objects.- Parameters:
path- path to labeled image file (e.g. PNGs)request- aRegionRequestrepresenting 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- aRegionRequestrepresenting 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, throws IOExceptionPathObject> creator) Convert a labeled image to objects.- Parameters:
path- path to labeled image file (e.g. PNGs)request- aRegionRequestrepresenting 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
Attempt to parse aRegionRequestcorresponding 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 namewidth- labeled image width, used to calculate the downsample if required; use -1 to ignore thisheight- labeled image height, used to calculate the downsample if required; use -1 to ignore this- Returns:
- a
RegionRequestthat 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 valuesband- 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 createdmaxLabel- maximum label; if less than minLabel, the maximum label will be found in the image and usedcreator- function to convert the traced ROI and associated numeric label into aPathObject- 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 imageregion- 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 createdmaxLabel- maximum label; if less than minLabel, the maximum label will be found in the image and usedcreator- function to convert the traced ROI and associated numeric label into aPathObject- 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 imageregion- 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 createdmaxLabel- 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 imageregion- 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 createdmaxLabel- 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, createNumberedObjectFunctionPathObject> (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, createObjectFunctionPathObject> (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 ROInumberer- 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 pixelsbandNuclei- the band containing the labelled nucleus pixelsbandCells- the band containing the labelled cell pixelsregion- 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 createdmaxLabel- 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 nucleiimageCells- the labelled image containing full cell regions; labels must match with imageNucleiregion- 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 createdmaxLabel- 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
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 imagesbandNuclei- band corresponding to the potential labeled image for nucleibandCells- band corresponding to the potential labeled image for cellsminLabel- the minimum positive label (usually 1). All pixels inimageNucleiwith a value ≥ minLabel must have the same value inimageCells.- Returns:
- true if the images could provide nuclei and cell regions, false otherwise
-
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 nucleiimageCells- potential labeled image for cellsminLabel- the minimum positive label (usually 1). All pixels inimageNucleiwith a value ≥ minLabel must have the same value inimageCells.- Returns:
- true if the images could provide nuclei and cell regions, false otherwise
-
extractBand
Extract a band from a a raster as aSimpleImage.- Parameters:
raster- the rasterband- the band (0-based index)- Returns:
- a
SimpleImagecontaining 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 valuesband- 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 createdmaxLabel- 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 imageregion- 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 createdmaxLabel- 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 rasterminThresholdInclusive- minimum threshold valuemaxThresholdInclusive- maximum threshold valueband- band (channel) to thresholdrequest- 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 aSimpleImage.- Parameters:
image- input imageminThresholdInclusive- minimum threshold valuemaxThresholdInclusive- maximum threshold valuerequest- 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 aSimpleImage.- Parameters:
image- input imageminThresholdInclusive- minimum threshold valuemaxThresholdInclusive- maximum threshold valuerequest- 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 rasterminThresholdInclusive- minimum threshold valuemaxThresholdInclusive- maximum threshold valueband- band (channel) to thresholdrequest- 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 tracedclipArea- 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
-