Package qupath.lib.roi

Class GeometryTools

java.lang.Object
qupath.lib.roi.GeometryTools
public class GeometryTools extends Object
Convert between QuPath ROI objects and Java Topology Suite Geometry objects.
Author:
Pete Bankhead

  • Constructor Details

    • GeometryTools

      public GeometryTools()

  • Method Details

    • getDefaultFactory

      public static GeometryFactory getDefaultFactory()
      Get the default GeometryFactory to construct Geometries within QuPath.
      Returns:

    • parseTransformMatrix

      public static AffineTransformation parseTransformMatrix(String text) throws ParseException
      Parse the matrix (String) to create and return an AffineTransformation.

      The order of the matrix elements should be the following:

      1. m00 m01 m02

      2. m10 m11 m12

      Parameters:
      text -
      Returns:
      affineTransformation
      Throws:
      ParseException

    • convertTransform

      public static AffineTransform convertTransform(AffineTransformation transform)
      Convert an AffineTransformation to an AffineTransform.
      Parameters:
      transform -
      Returns:

    • convertTransform

      public static AffineTransformation convertTransform(AffineTransform transform)
      Convert an AffineTransform to an AffineTransformation.
      Parameters:
      transform -
      Returns:

    • shapeToGeometry

      public static Geometry shapeToGeometry(Shape shape)
      Convert a java.awt.Shape to a JTS Geometry.
      Parameters:
      shape -
      Returns:

    • envelopToRegion

      public static ImageRegion envelopToRegion(Envelope env, int z, int t)
      Convert an Envelope to an ImageRegion.
      Parameters:
      env - envelop
      z - z index for the region (default is 0)
      t - timepoint for the region (default is 0)
      Returns:
      the smallest ImageRegion that contains the specified envelop

    • attemptOperation

      public static Geometry attemptOperation(Geometry input, Function<Geometry,Geometry> fun)
      Attempt to apply a function to a geometry, returning the input unchanged if there was an exception.

      The purpose of this is to make it easier to apply non-essential functions that might fail (e.g. with a TopologyException and to recover easily.

      Parameters:
      input - the input geometry
      fun - the function to (attempt) to apply
      Returns:
      the new geometry if the function succeeded, otherwise the original geometry

    • roundCoordinates

      public static Geometry roundCoordinates(Geometry geometry)
      Round coordinates in a Geometry to integer values.
      Parameters:
      geometry - the updated Geometry
      Returns:

    • constrainToBounds

      public static Geometry constrainToBounds(Geometry geometry, double x, double y, double width, double height)
      Compute the intersection of a Geometry and a specified bounding box. The original Geometry may be returned unchanged if no changes are required to fit within the bounds.
      Parameters:
      geometry - the updated Geometry
      x -
      y -
      width -
      height -
      Returns:

    • createRectangle

      public static Geometry createRectangle(double x, double y, double width, double height)
      Create a rectangular Geometry for the specified bounding box.
      Parameters:
      x -
      y -
      width -
      height -
      Returns:

    • geometryToROI

      public static ROI geometryToROI(Geometry geometry, ImagePlane plane)
      Convert a JTS Geometry to a QuPath ROI.
      Parameters:
      geometry -
      plane -
      Returns:

    • roiToGeometry

      public static Geometry roiToGeometry(ROI roi)
      Convert to QuPath ROI to a JTS Geometry.
      Parameters:
      roi -
      Returns:

    • geometryToShape

      public static Shape geometryToShape(Geometry geometry)
      Convert a JTS Geometry to a java.awt.Shape.
      Parameters:
      geometry -
      Returns:

    • regionToGeometry

      public static Geometry regionToGeometry(ImageRegion region)
      Convert an ImageRegion to a rectangular Geometry. The z-position is retained, but timepoint is lost.
      Parameters:
      region -
      Returns:

    • union

      public static Geometry union(Collection<? extends Geometry> geometries)
      Calculate the union of multiple Geometry objects.
      Parameters:
      geometries -
      Returns:

    • ensurePolygonal

      public static Geometry ensurePolygonal(Geometry geometry)
      Strip non-polygonal parts from a GeometryCollection (non-recursive).
      Parameters:
      geometry -
      Returns:
      a Geometry containing only Polygons, which may be the same as the input Geometry or empty

    • homogenizeGeometryCollection

      public static Geometry homogenizeGeometryCollection(Geometry geometry)
      Ensure a GeometryCollection contains only Geometries of the same type (Polygonal, Lineal or Puntal). Other geometries (with lower dimension) are discarded.
      Parameters:
      geometry -
      Returns:

    • removeInteriorRings

      public static Geometry removeInteriorRings(Geometry geometry, double minRingArea)
      Fill all interior rings for the specified geometry that have an area < a specified threshold.

      Note that this assumes that the geometry is valid, and does not contain self-intersections or overlapping pieces. No checks are made to confirm this (for performance reasons).

      Parameters:
      geometry -
      minRingArea -
      Returns:

    • fillHoles

      public static Geometry fillHoles(Geometry geometry)
      Fill all interior rings for the specified geometry.
      Parameters:
      geometry -
      Returns:

    • removeFragments

      public static Geometry removeFragments(Geometry geometry, double minArea)
      Remove fragments smaller than the specified area from a Geometry, ignoring internal rings.
      Parameters:
      geometry - the geometry to refine
      minArea - the minimum area of a fragment to retain. If ≤ 0, the geometry is returned unchanged. Otherwise, polygons will be extracted from the geometry and all that have an external ring area smaller than minArea will be removed.
      Returns:
      the refined Geometry, or an empty polygon if all pieces of the geometry were removed.

    • tryToFixPolygon

      public static Geometry tryToFixPolygon(Polygon polygon)
      Test a polygon for validity, attempting to fix TopologyValidationErrors if possible. This attempts a range of tricks (starting with Geometry.buffer(0)), although none are guaranteed to work. The first that largely preserves the polygon's area is returned.

      The result is guaranteed to be valid, but not necessarily to be a close match to the original polygon; in particular, if everything failed the result will be empty.

      Code that calls this method can test if the output is equal to the input to determine if any changes were made.

      Parameters:
      polygon - input (possibly-invalid) polygon
      Returns:
      the input polygon (if valid), an adjusted polygon (if attempted fixes helped), or an empty polygon if the situation could not be resolved

    • refineAreas

      public static Geometry refineAreas(Geometry geometry, double minSizePixels, double minHoleSizePixels)
      Remove small fragments and fill small interior rings within a Geometry.

      Note that any modifications to the geometry will result in points and lines being stripped away, leaving only polygons.

      Parameters:
      geometry - input geometry to refine
      minSizePixels - minimum area of a fragment to keep (the area of interior rings for polygons will be ignored)
      minHoleSizePixels - minimum size of an interior hole to keep
      Returns:
      the refined geometry (possibly the original unchanged), or empty geometry if the changes resulted in the Geometry disappearing
      See Also:

    • splitGeometryByLineStrings

      public static List<Geometry> splitGeometryByLineStrings(Geometry polygon, Collection<? extends Geometry> splitLines) throws IllegalArgumentException
      Split an input polygonal geometry using a collection of split lines.

      The main input must be polygonal, but the split lines can be any geometry type; their linestrings will be extracted and used for splitting.

      Important! This will also split a MultiPolygon into its constituent Polygon objects as a side effect. This is to ensure consistency and avoid cases where linestrings may span multiple polygons within the same multipolygon. The output may be combined to form a new multipolygon later if required.

      Parameters:
      polygon - the polygonal geometry to split
      splitLines - a collection of geometries, whose union will be used to split the input geometry
      Returns:
      a list of polygons formed by the splitting. This may return the original geometry, or geometries within an original collection, if these do not need to be split.
      Throws:
      IllegalArgumentException - if the input geometry is not polygonal
      Since:
      v0.5.0