Package qupath.lib.roi

Class RoiTools

java.lang.Object
qupath.lib.roi.RoiTools
public class RoiTools extends Object
A collection of static methods for working with ROIs.
Author:
Pete Bankhead

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static enum 
    RoiTools.CombineOp
    Methods of combining two ROIs.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RoiTools()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static boolean
    areaContains(ROI pathROI, double x, double y)
    Returns true if pathROI is an area that contains x & y somewhere within it.
    static ROI
    buffer(ROI roi, double distance)
    Buffer the specified ROI, dilating (or eroding) by the specified distance.
    static List<ROI>
    clipToROI(ROI parent, Collection<? extends ROI> rois)
    Intersect a collection of ROIs with a single parent ROI, returning all results that are valid.
    static ROI
    combineROIs(ROI shape1, ROI shape2, RoiTools.CombineOp op)
    Combine two shape ROIs together.
    static Collection<? extends ROI>
    computeTiledROIs(ROI parentROI, ImmutableDimension sizePreferred, ImmutableDimension sizeMax, boolean fixedSize, int overlap)
    Create a collection of tiled ROIs corresponding to a specified parentROI if it is larger than sizeMax, with optional overlaps.
    static ROI
    createRandomRectangle(ImageRegion mask, double width, double height)
    Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask region.
    static ROI
    createRandomRectangle(ImageRegion mask, double width, double height, Random random)
    Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask region.
    static ROI
    createRandomRectangle(ROI mask, double width, double height)
    Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask ROI.
    static ROI
    createRandomRectangle(ROI mask, double width, double height, int maxAttempts, boolean permitErosion, Random random)
    Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask ROI, using a specified maximum number of attempts.
    static ROI
    difference(ROI roi1, ROI roi2)
    Compute the difference between two ROIs.
    static ROI
    fillHoles(ROI roi)
    Fill the holes of an Area ROI, or return the ROI unchanged if it contains no holes.
    static Area
    getArea(ROI roi)
    Get an Area object representing a ROI.
    static double
    getBoundaryDistance(ROI roi1, ROI roi2)
    Get the Euclidean distance between the boundaries of two ROIs.
    static double
    getBoundaryDistance(ROI roi1, ROI roi2, double pixelWidth, double pixelHeight)
    Get the calibrated Euclidean distance between the boundaries of two ROIs using specified pixel sizes.
    static double
    getCentroidDistance(ROI roi1, ROI roi2)
    Get the Euclidean distance between the centroids of two ROIs.
    static double
    getCentroidDistance(ROI roi1, ROI roi2, double pixelWidth, double pixelHeight)
    Get the calibrated Euclidean distance between the centroids of two ROIs using specified pixel sizes.
    static double
    getCircularity(ROI roi)
    Get circularity measurement for Area ROIs, calculated as 4 * PI * (area / perimeter^2).
    static double
    getCircularity(ROI roi, double pixelWidth, double pixelHeight)
    Get circularity measurement for area ROIs, with optional pixel calibration, calculated as 4 * PI * (area / perimeter^2).
    static Shape
    getShape(ROI roi)
    Get a Shape object representing a ROI.
    static ROI
    getShapeROI(Area area, ImagePlane plane)
    Create a ROI from an Shape.
    static ROI
    getShapeROI(Shape shape, ImagePlane plane, double flatness)
    Create a ROI from an Shape with a specified 'flatness'.
    static ROI
    intersection(Collection<? extends ROI> rois)
    Create intersection of multiple ROIs from a collection.
    static ROI
    intersection(ROI... rois)
    Create intersection of multiple ROIs.
    static boolean
    intersectsRegion(ROI roi, ImageRegion region)
    Test whether a ROI and an ImageRegion intersect.
    static boolean
    isShapeROI(ROI roi)
    Returns true if the ROI is not null and is not a point ROI.
    static List<ROI>
    makeTiles(ROI roi, int tileWidth, int tileHeight, boolean trimToROI)
    Make fixed-size rectangular tile ROIs for a specified area.
    static ROI
    removeSmallPieces(ROI roi, double minAreaPixels, double minHoleAreaPixels)
    Remove small fragments and fill small holes of an area ROI.
    static PolygonROI[][]
    splitAreaToPolygons(Area area, int c, int z, int t)
    Split Area into PolygonROIs for the exterior and the holes.
    static List<ROI>
    splitROI(ROI roi)
    Split a multi-part ROI into separate pieces.
    static ROI
    subtract(ROI roiMain, Collection<? extends ROI> roisToSubtract)
    Subtract a collection of ROIs from another ROI.
    static ROI
    subtract(ROI roiMain, ROI... roisToSubtract)
    Subtract one or more ROIs from another ROI.
    static ROI
    symDifference(ROI roi1, ROI roi2)
    Compute the symmetric difference between two ROIs (XOR).
    static ROI
    transformROI(ROI roi, AffineTransform transform)
    Apply an affine transform to a ROI, returning the result.
    static ROI
    union(Collection<? extends ROI> rois)
    Create union of multiple ROIs from a collection.
    static ROI
    union(ROI... rois)
    Create union of multiple ROIs.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • RoiTools

      public RoiTools()

  • Method Details

    • combineROIs

      public static ROI combineROIs(ROI shape1, ROI shape2, RoiTools.CombineOp op)
      Combine two shape ROIs together.
      Parameters:
      shape1 -
      shape2 -
      op -
      Returns:

    • union

      public static ROI union(Collection<? extends ROI> rois)
      Create union of multiple ROIs from a collection. This assumes that ROIs fall on the same plane, if not an IllegalArgumentException will be thrown. Similarly, ROIs must be of a similar type (e.g. area, point) or an exception will be thrown by Java Topology Suite.
      Parameters:
      rois -
      Returns:

    • union

      public static ROI union(ROI... rois)
      Create union of multiple ROIs. ROIs must be of a similar type (e.g. area, point) or an exception will be thrown by Java Topology Suite.
      Parameters:
      rois -
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • intersection

      public static ROI intersection(Collection<? extends ROI> rois)
      Create intersection of multiple ROIs from a collection. ROIs must be of a similar type (e.g. area, point) or an exception will be thrown by Java Topology Suite.
      Parameters:
      rois -
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • intersection

      public static ROI intersection(ROI... rois)
      Create intersection of multiple ROIs. This assumes that ROIs fall on the same plane, if not an IllegalArgumentException will be thrown. Similarly, ROIs must be of a similar type (e.g. area, point) or an exception will be thrown by Java Topology Suite.
      Parameters:
      rois -
      Returns:

    • difference

      public static ROI difference(ROI roi1, ROI roi2)
      Compute the difference between two ROIs. This is equivalent to calling subtract(ROI, ROI...) to subtract roi2 from roi1.
      Parameters:
      roi1 - the main ROI
      roi2 - the ROI to subtract
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • symDifference

      public static ROI symDifference(ROI roi1, ROI roi2)
      Compute the symmetric difference between two ROIs (XOR).
      Parameters:
      roi1 - the first ROI
      roi2 - the second ROI
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • subtract

      public static ROI subtract(ROI roiMain, ROI... roisToSubtract)
      Subtract one or more ROIs from another ROI.
      Parameters:
      roiMain - the main ROI, defining the positive area
      roisToSubtract - the ROIs to remove from roiMain
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • subtract

      public static ROI subtract(ROI roiMain, Collection<? extends ROI> roisToSubtract)
      Subtract a collection of ROIs from another ROI.
      Parameters:
      roiMain - the main ROI, defining the positive area
      roisToSubtract - the ROIs to remove from roiMain
      Returns:
      Throws:
      IllegalArgumentException - if the ROIs do not fall in the same plane

    • intersectsRegion

      public static boolean intersectsRegion(ROI roi, ImageRegion region)
      Test whether a ROI and an ImageRegion intersect.

      This returns false quickly if the ROI and region do not share the same z-slice or timepoint, or the ROI's bounding box does not intersect the region. Otherwise, a more expensive geometry test is performed to check for intersection.

      Parameters:
      roi -
      region -
      Returns:
      true if the ROI and the region intersect, false otherwise

    • transformROI

      public static ROI transformROI(ROI roi, AffineTransform transform)
      Apply an affine transform to a ROI, returning the result.
      Parameters:
      roi - the ROI to transform
      transform - the affine transform to apply; if null or the identity transform, the original ROI is returned unchanged
      Returns:
      the transformed ROI, or the original if no (non-identity) transform is specified

    • clipToROI

      public static List<ROI> clipToROI(ROI parent, Collection<? extends ROI> rois)
      Intersect a collection of ROIs with a single parent ROI, returning all results that are valid. Where possible, ROIs are returned unchanged.
      Parameters:
      parent - the parent ROI, used to define the clip boundary
      rois - a collection of ROIs that should be intersected with parent
      Returns:
      list of intersected ROIs; this may be shorter than rois if some lie completely outside parent

    • fillHoles

      public static ROI fillHoles(ROI roi)
      Fill the holes of an Area ROI, or return the ROI unchanged if it contains no holes.
      Parameters:
      roi -
      Returns:

    • removeSmallPieces

      public static ROI removeSmallPieces(ROI roi, double minAreaPixels, double minHoleAreaPixels)
      Remove small fragments and fill small holes of an area ROI.
      Parameters:
      roi - the ROI to refine
      minAreaPixels - the minimum size of a fragment to retain
      minHoleAreaPixels - the minimum size of a hole to retain, or -1 if all holes should be retained
      Returns:
      an updated ROI - which may be empty if the modifications caused the ROI to disappear
      See Also:

    • getCircularity

      public static double getCircularity(ROI roi)
      Get circularity measurement for Area ROIs, calculated as 4 * PI * (area / perimeter^2). Non-area ROIs return Double.NaN.

      This ranges between 0 (for a line) and 1 (for a circle). Note that the pixel (i.e. not scaled) areas and perimeters are used.

      Parameters:
      roi - the ROI to measure
      Returns:
      a circularity value, between 0 (a line) and 1 (a perfect circle)

    • getCircularity

      public static double getCircularity(ROI roi, double pixelWidth, double pixelHeight)
      Get circularity measurement for area ROIs, with optional pixel calibration, calculated as 4 * PI * (area / perimeter^2). Non-area ROIs return Double.NaN.

      This ranges between 0 (for a line) and 1 (for a circle). This version optionally allows non-square pixels to be used.

      Parameters:
      roi - the ROI to measure
      pixelWidth - the calibrated pixel width (use 1.0 for uncalibrated pixels)
      pixelHeight - the calibrated pixel height (use 1.0 for uncalibrated pixels)
      Returns:
      a circularity value, between 0 (a line) and 1 (a perfect circle)

    • getShapeROI

      public static ROI getShapeROI(Shape shape, ImagePlane plane, double flatness)
      Create a ROI from an Shape with a specified 'flatness'. This will try to return a RectangleROI or PolygonROI if possible, or AreaROI if neither of the other classes can adequately represent the area. In the input shape is an Ellipse2D then an EllipseROI will be returned.
      Parameters:
      shape -
      plane -
      flatness - - can be used to prefer polygons, see Shape.getPathIterator(AffineTransform, double)
      Returns:

    • getCentroidDistance

      public static double getCentroidDistance(ROI roi1, ROI roi2)
      Get the Euclidean distance between the centroids of two ROIs.
      Parameters:
      roi1 - first ROI
      roi2 - second ROI
      Returns:
      the distance between centroids

    • getCentroidDistance

      public static double getCentroidDistance(ROI roi1, ROI roi2, double pixelWidth, double pixelHeight)
      Get the calibrated Euclidean distance between the centroids of two ROIs using specified pixel sizes.
      Parameters:
      roi1 - first ROI
      roi2 - second ROI
      pixelWidth - horizontal scale factor for pixels
      pixelHeight - vertical scale factor for pixels
      Returns:
      the distance between centroids

    • getBoundaryDistance

      public static double getBoundaryDistance(ROI roi1, ROI roi2)
      Get the Euclidean distance between the boundaries of two ROIs.
      Parameters:
      roi1 - first ROI
      roi2 - second ROI
      Returns:
      the distance between boundaries

    • getBoundaryDistance

      public static double getBoundaryDistance(ROI roi1, ROI roi2, double pixelWidth, double pixelHeight)
      Get the calibrated Euclidean distance between the boundaries of two ROIs using specified pixel sizes.
      Parameters:
      roi1 - first ROI
      roi2 - second ROI
      pixelWidth - horizontal scale factor for pixels
      pixelHeight - vertical scale factor for pixels
      Returns:
      the distance between boundaries

    • getShapeROI

      public static ROI getShapeROI(Area area, ImagePlane plane)
      Create a ROI from an Shape. This will try to return a RectangleROI or PolygonROI if possible, or AreaROI if neither of the other classes can adequately represent the area. In the input shape is an Ellipse2D then an EllipseROI will be returned.
      Parameters:
      area -
      plane -
      Returns:

    • getShape

      public static Shape getShape(ROI roi) throws IllegalArgumentException
      Get a Shape object representing a ROI. Previously this did more work; now it only calls ROI.getShape()
      Parameters:
      roi -
      Returns:
      Throws:
      IllegalArgumentException - if the ROI is a Point ROI, which cannot be converted to a java.awtshape.

    • getArea

      public static Area getArea(ROI roi)
      Get an Area object representing a ROI.
      Parameters:
      roi -
      Returns:

    • makeTiles

      public static List<ROI> makeTiles(ROI roi, int tileWidth, int tileHeight, boolean trimToROI)
      Make fixed-size rectangular tile ROIs for a specified area.
      Parameters:
      roi - area to be tiled
      tileWidth - requested tile width, in pixels
      tileHeight - requested tile height, in pixels
      trimToROI - if true, trim tiles at the ROI boundary according to the ROI shape, otherwise retain full tiles that may only partially overlap
      Returns:

    • computeTiledROIs

      public static Collection<? extends ROI> computeTiledROIs(ROI parentROI, ImmutableDimension sizePreferred, ImmutableDimension sizeMax, boolean fixedSize, int overlap)
      Create a collection of tiled ROIs corresponding to a specified parentROI if it is larger than sizeMax, with optional overlaps.

      The purpose of this is to create useful tiles whenever the exact tile size may not be essential, and overlaps may be required. Tiles at the parentROI boundary will be trimmed to fit inside. If the parentROI is smaller, it is returned as is.

      Parameters:
      parentROI - main ROI to be tiled
      sizePreferred - the preferred size; in general tiles should have this size
      sizeMax - the maximum allowed size; occasionally it is more efficient to have a tile larger than the preferred size towards a ROI boundary to avoid creating very small tiles unnecessarily
      fixedSize - if true, the tile size is enforced so that complete tiles have the same size
      overlap - optional requested overlap between tiles
      Returns:
      See Also:

    • buffer

      public static ROI buffer(ROI roi, double distance)
      Buffer the specified ROI, dilating (or eroding) by the specified distance.
      Parameters:
      roi - the ROI to buffer
      distance - the distance to buffer, in pixels. If negative an erosion will be performed.
      Returns:
      the modified ROI (which may be empty)

    • splitROI

      public static List<ROI> splitROI(ROI roi)
      Split a multi-part ROI into separate pieces.

      If the ROI is already a distinct, single region or line it is returned as a singleton list.

      Parameters:
      roi -
      Returns:

    • splitAreaToPolygons

      public static PolygonROI[][] splitAreaToPolygons(Area area, int c, int z, int t)
      Split Area into PolygonROIs for the exterior and the holes.

      The first array returned gives the holes and the second the positive regions (admittedly, it might have been more logical the other way around). 

       
 var polygons = splitAreaToPolygons(area, -1, 0, 0);
 var holes = polygons[0];
 var regions = polygons[1];
      Parameters:
      area -
      c -
      z -
      t -
      Returns:

    • createRandomRectangle

      public static ROI createRandomRectangle(ImageRegion mask, double width, double height) throws IllegalArgumentException
      Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask region.
      Parameters:
      mask - region defining the area in which the rectangle can be located, including the image plane information
      width - width of the rectangle to create
      height - height of the rectangle to create
      Returns:
      a rectangle with the specified width and height, covered by the mask
      Throws:
      IllegalArgumentException - if either the mask width or height is too small for the requested width and height

    • createRandomRectangle

      public static ROI createRandomRectangle(ImageRegion mask, double width, double height, Random random) throws IllegalArgumentException
      Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask region.
      Parameters:
      mask - region defining the area in which the rectangle can be located, including the image plane information
      width - width of the rectangle to create
      height - height of the rectangle to create
      random - random number generator to use (may be null to use a default)
      Returns:
      a rectangle with the specified width and height, covered by the mask
      Throws:
      IllegalArgumentException - if either the mask width or height is too small for the requested width and height

    • createRandomRectangle

      public static ROI createRandomRectangle(ROI mask, double width, double height) throws IllegalArgumentException
      Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask ROI.

      For greater control, see createRandomRectangle(ROI, double, double, int, boolean, Random).

      Parameters:
      mask - region defining the area in which the rectangle can be located, including the image plane information
      width - width of the rectangle to create
      height - height of the rectangle to create
      Returns:
      a rectangle with the specified width and height and covered by the mask, or null if it was not possible to find a rectangle that meets this criterion
      Throws:
      IllegalArgumentException - if either the mask width or height is too small for the requested width and height
      See Also:

    • createRandomRectangle

      public static ROI createRandomRectangle(ROI mask, double width, double height, int maxAttempts, boolean permitErosion, Random random) throws IllegalArgumentException
      Create a randomly-located rectangle ROI with the specified width and height, constrained to fall within the provided mask ROI, using a specified maximum number of attempts.
      Parameters:
      mask - region defining the area in which the rectangle can be located, including the image plane information
      width - width of the rectangle to create
      height - height of the rectangle to create
      maxAttempts - the maximum number of attempts to make when attempting to fit the rectangle within the ROI
      permitErosion - optionally make an additional attempt to locate a rectangle by eroding the mask and using the remaining region. For a non-square rectangle, this uses the length of the longest side for erosion - and therefore may exclude some possible rectangles from consideration.
      random - random number generator to use for the initial attempts (may be null to use a default)
      Returns:
      a rectangle with the specified width and height and covered by the mask, or null if it was not possible to find a rectangle that meets this criterion
      Throws:
      IllegalArgumentException - if either the mask width or height is too small for the requested width and height
      See Also:

    • areaContains

      public static boolean areaContains(ROI pathROI, double x, double y)
      Returns true if pathROI is an area that contains x & y somewhere within it.
      Parameters:
      pathROI -
      x -
      y -
      Returns:

    • isShapeROI

      public static boolean isShapeROI(ROI roi)
      Returns true if the ROI is not null and is not a point ROI.
      Parameters:
      roi -
      Returns: