Package micycle.pgs

Class PGS_ShapePredicates

java.lang.Object
micycle.pgs.PGS_ShapePredicates
public final class PGS_ShapePredicates extends Object
Various shape metrics, predicates and descriptors.
Author:
Michael Carleton

  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    area(processing.core.PShape shape)
    Computes the area of the given shape.
    static processing.core.PVector
    boundsCenter(processing.core.PShape shape)
    Computes the center of the bounding box of a shape.
    static processing.core.PVector
    centroid(processing.core.PShape shape)
    Computes the centroid of a shape.
    static double
    circularity(processing.core.PShape shape)
    Calculates the Miller circularity index for a shape.
    static boolean
    contains(processing.core.PShape outer, processing.core.PShape inner)
    Determines whether the outer shape fully contains the inner shape.
    static boolean
    containsAllPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
    Determines whether a shape contains every point from a list of points.
    static boolean
    containsPoint(processing.core.PShape shape, processing.core.PVector point)
    Determines whether a shape contains a point.
    static List<Boolean>
    containsPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
    Measures for each point in the input whether it is contained in the given shape.
    static double
    convexity(processing.core.PShape shape)
    Computes the convexity of a shape using a simple area-based measure of convexity.
    static double
    density(processing.core.PShape shape)
    Computes the ratio (density) of the shape's area compared to the area of it's envelope.
    static double
    diameter(processing.core.PShape shape)
    Returns the diameter of a shape.
    static double
    distance(processing.core.PShape a, processing.core.PShape b)
    Computes the minimum distance between two shapes.
    static double
    efdSimilarity(processing.core.PShape a, processing.core.PShape b)
    Quantifies the similarity between two shapes, by using the pairwise euclidean distance between each shape's Elliptic Fourier Descriptors (EFD).
    static double
    elongation(processing.core.PShape shape)
    Measures the elongation of a shape; the ratio of a shape's bounding box length to its width.
    static boolean
    equalsExact(processing.core.PShape a, processing.core.PShape b)
    Tests two shapes for structural equality.
    static boolean
    equalsNorm(processing.core.PShape a, processing.core.PShape b)
    Tests two shapes for normalised structural equality.
    static boolean
    equalsTopo(processing.core.PShape a, processing.core.PShape b)
    Tests two shapes for topological equality.
    static List<processing.core.PVector>
    findContainedPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
    Tests for each point in the input whether it is contained in/inside the given shape; if it is, then the point is included in the output list.
    static processing.core.PShape
    findContainingShape(processing.core.PShape groupShape, processing.core.PVector point)
    Finds the single child shape/cell (if any) that contains the query point from a GROUP shape input (a shape that has non-overlapping children).
    static double
    height(processing.core.PShape shape)
    Computes the vertical height of a shape (the height of its bounding-box).
    static int
    holes(processing.core.PShape shape)
    Counts the number of holes in a shape.
    static boolean
    intersect(processing.core.PShape a, processing.core.PShape b)
    Determines whether the shapes intersect/overlap (meaning that have at least one point in common).
    static boolean
    isClockwise(processing.core.PShape shape)
    Determines if the vertices of the specified shape form a clockwise loop on the screen in Processing.
    static boolean
    isConformingMesh(processing.core.PShape mesh)
    Determines whether a GROUP shape forms a conforming mesh / valid polygon coverage.
    static boolean
    isConvex(processing.core.PShape shape)
    Determines whether a shape is convex.
    static boolean
    isSimple(processing.core.PShape shape)
    Checks whether a shape is simple.
    static boolean
    isValid(processing.core.PShape shape)
    Checks if a PShape is valid, and reports the validation error if it is invalid.
    static double
    length(processing.core.PShape shape)
    Returns the length of a shape.
    static double
    maximumInteriorAngle(processing.core.PShape shape)
    Computes the maximum/largest interior angle of a polygon.
    static processing.core.PVector
    median(processing.core.PShape shape)
    Computes the geometric median location of a shape's vertices.
    static double
    overlap(processing.core.PShape a, processing.core.PShape b)
    Measures the degree of mutual overlap between two shapes.
    static double
    similarity(processing.core.PShape a, processing.core.PShape b)
    Measures the degree of similarity between two shapes using the Hausdorff distance metric.
    static double
    sphericity(processing.core.PShape shape)
    Measures the sphericity of a shape; the ratio of the maximum inscribed circle to the minimum bounding circle.
    static boolean
    touch(processing.core.PShape a, processing.core.PShape b)
    Determines whether the have at least one point in common, but where their interiors do not intersect.
    static double
    width(processing.core.PShape shape)
    Computes the horizontal width of a shape (the width of its bounding-box).

    Methods inherited from class java.lang.Object

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

  • Method Details

    • contains

      public static boolean contains(processing.core.PShape outer, processing.core.PShape inner)
      Determines whether the outer shape fully contains the inner shape. A shape is considered to contain itself. Points of the inner shape that lie on the boundary of the outer shape are considered to be contained.
      Parameters:
      outer -
      inner -
      Returns:

    • containsPoint

      public static boolean containsPoint(processing.core.PShape shape, processing.core.PVector point)
      Determines whether a shape contains a point. Points that lie on the boundary of the shape are considered to be contained.
      Parameters:
      shape -
      point -
      Returns:
      See Also:

    • containsAllPoints

      public static boolean containsAllPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
      Determines whether a shape contains every point from a list of points. It is faster to use method rather than than calling containsPoint() repeatedly. Any points that lie on the boundary of the shape are considered to be contained.
      Parameters:
      shape -
      points - list of points to check
      Returns:
      true if every point is contained within the shape

    • containsPoints

      public static List<Boolean> containsPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
      Measures for each point in the input whether it is contained in the given shape. This method checks every point individually, returning a boolean for each point. Using this method is faster than calling containsPoint() repeatedly. Points that lie on the boundary of the shape are considered to be contained.
      Parameters:
      shape -
      points - list of points to check
      Returns:
      a list of booleans corresponding to whether the shape contains the point at same index

    • findContainedPoints

      public static List<processing.core.PVector> findContainedPoints(processing.core.PShape shape, Collection<processing.core.PVector> points)
      Tests for each point in the input whether it is contained in/inside the given shape; if it is, then the point is included in the output list. This method does not mutate the input; it returns a filtered copy. Points that lie on the boundary of the shape are considered to be contained.

      Using this method is faster than calling containsPoint() repeatedly.

      Parameters:
      shape -
      points - list of points to check
      Returns:
      a filtered view of the input points

    • findContainingShape

      public static processing.core.PShape findContainingShape(processing.core.PShape groupShape, processing.core.PVector point)
      Finds the single child shape/cell (if any) that contains the query point from a GROUP shape input (a shape that has non-overlapping children).

      This method locates the containing shape in log(n) time (after some pre-processing overhead).

      Parameters:
      groupShape - a GROUP shape
      point - the query point
      Returns:
      the child shape that contains the query point, or null if no child shape contains the point
      Since:
      1.3.0

    • intersect

      public static boolean intersect(processing.core.PShape a, processing.core.PShape b)
      Determines whether the shapes intersect/overlap (meaning that have at least one point in common).

      Note that the input shapes may be lineal (open path) or polygonal (closed path), and this affects the meaning of the method. The following intersection tests are performed based on the type combinations of the shapes:

      • Polygon-line intersection: the polygon area and line share at least one point in common. This means a path contained entirely inside a polygon will return true as it needn't intersect with the polygon's perimeter.
      • Line-line intersection: the two lines intersect at least once.
      • Polygon-polygon intersection: the two polygons share at least one point in common (from their area or perimeter).
      Parameters:
      a -
      b -
      Returns:

    • touch

      public static boolean touch(processing.core.PShape a, processing.core.PShape b)
      Determines whether the have at least one point in common, but where their interiors do not intersect.
      Parameters:
      a -
      b -
      Returns:

    • distance

      public static double distance(processing.core.PShape a, processing.core.PShape b)
      Computes the minimum distance between two shapes.
      Parameters:
      a - shape A
      b - shape B
      Returns:

    • area

      public static double area(processing.core.PShape shape)
      Computes the area of the given shape.
      Parameters:
      shape -
      Returns:

    • density

      public static double density(processing.core.PShape shape)
      Computes the ratio (density) of the shape's area compared to the area of it's envelope.
      Parameters:
      shape -
      Returns:
      Density value. A rectangular shape will have a value of 1.

    • centroid

      public static processing.core.PVector centroid(processing.core.PShape shape)
      Computes the centroid of a shape. A centroid is the center of mass of the shape.

      If the input is a polygon, the centroid will always lie inside it. For other shapes, this may not be the case.

      Parameters:
      shape - the PShape object representing the shape for which the centroid is to be computed
      Returns:
      a PVector representing the centroid of the shape, or null if the shape's geometry is empty

    • boundsCenter

      public static processing.core.PVector boundsCenter(processing.core.PShape shape)
      Computes the center of the bounding box of a shape. The bounding box is the smallest rectangle that completely contains the shape.
      Parameters:
      shape - the PShape object representing the shape for which the bounding box center is to be computed
      Returns:
      a PVector representing the center of the shape's bounding box, or null if the shape's geometry is empty
      Since:
      2.0

    • median

      public static processing.core.PVector median(processing.core.PShape shape)
      Computes the geometric median location of a shape's vertices.

      The median point is the point that minimises the sum of distances to the shape vertices. If the input is a concave polygon, the median may not lie inside it.

      Parameters:
      shape -
      Returns:
      median point
      Since:
      1.4.0

    • width

      public static double width(processing.core.PShape shape)
      Computes the horizontal width of a shape (the width of its bounding-box).

    • height

      public static double height(processing.core.PShape shape)
      Computes the vertical height of a shape (the height of its bounding-box).

    • length

      public static double length(processing.core.PShape shape)
      Returns the length of a shape. Linear shapes return their length; areal shapes (polygons) return their perimeter.

    • diameter

      public static double diameter(processing.core.PShape shape)
      Returns the diameter of a shape. Diameter is the maximum distance between any 2 coordinates on the shape perimeter; this is equal to the diameter of the circumscribed circle.
      Parameters:
      shape -
      Returns:
      Since:
      1.1.3

    • circularity

      public static double circularity(processing.core.PShape shape)
      Calculates the Miller circularity index for a shape. This index, between 0 and 1, is equal to 1 if the polygon is perfectly circular and tends towards 0 for a segment.
      Parameters:
      shape -
      Returns:

    • similarity

      public static double similarity(processing.core.PShape a, processing.core.PShape b)
      Measures the degree of similarity between two shapes using the Hausdorff distance metric. The measure is normalized to lie in the range [0, 1]. Higher measures indicate a great degree of similarity.
      Parameters:
      a - first shape
      b - second shape
      Returns:
      the value of the similarity measure, in [0.0, 1.0]

    • overlap

      public static double overlap(processing.core.PShape a, processing.core.PShape b)
      Measures the degree of mutual overlap between two shapes.

      This metric aggregates how much each shape is overlapped (fractional), weighted by its respective area.

      Parameters:
      a - first shape
      b - second shape
      Returns:
      overlap metric, in [0.0, 1.0]
      Since:
      1.3.0

    • sphericity

      public static double sphericity(processing.core.PShape shape)
      Measures the sphericity of a shape; the ratio of the maximum inscribed circle to the minimum bounding circle.
      Parameters:
      shape -
      Returns:
      a value in [0, 1]

    • elongation

      public static double elongation(processing.core.PShape shape)
      Measures the elongation of a shape; the ratio of a shape's bounding box length to its width.
      Parameters:
      shape -
      Returns:
      a value in [0, 1]

    • convexity

      public static double convexity(processing.core.PShape shape)
      Computes the convexity of a shape using a simple area-based measure of convexity.
      Parameters:
      shape -
      Returns:
      a value in [0, 1]
      Since:
      1.4.0

    • holes

      public static int holes(processing.core.PShape shape)
      Counts the number of holes in a shape.

      If the shape forms a polygon coverage (a mesh), then this method will count holes from gaps within the mesh.

      Parameters:
      shape - a polygonal shape (can be a GROUP shape having multiple polygons)
      Returns:
      total number of holes in the shape

    • maximumInteriorAngle

      public static double maximumInteriorAngle(processing.core.PShape shape)
      Computes the maximum/largest interior angle of a polygon.
      Parameters:
      shape - simple polygonal shape
      Returns:
      an angle in the range [0, 2PI]
      Since:
      1.3.0

    • efdSimilarity

      public static double efdSimilarity(processing.core.PShape a, processing.core.PShape b)
      Quantifies the similarity between two shapes, by using the pairwise euclidean distance between each shape's Elliptic Fourier Descriptors (EFD).

      Smaller values indicate greater similarity or equivalence, and the measure is translation and rotation invariant.

      This method can be useful in shape recognition tasks where it is necessary to quantify the difference or similarity between two shapes.

      Parameters:
      a - polygonal shape
      b - polygonal shape
      Returns:
      The EFD distance between the two provided PShapes. Smaller values indicate greater similarity or equivalence between the shapes.
      Since:
      1.4.0

    • equalsExact

      public static boolean equalsExact(processing.core.PShape a, processing.core.PShape b)
      Tests two shapes for structural equality. In simple terms, this means that they must have the same number of vertices, in the same locations, and in the same order.

      Note: If two Polygons have matching vertices, but one is arranged clockwise while the other is counter-clockwise, then then this method will return false.

      Parameters:
      a - shape a
      b - shape b
      Returns:
      true if both shapes have identical structure and point values.
      Since:
      1.3.0
      See Also:

    • equalsNorm

      public static boolean equalsNorm(processing.core.PShape a, processing.core.PShape b)
      Tests two shapes for normalised structural equality. In simple terms, this means that they must have the same number of vertices in the same locations. Unlike equalsExact(PShape, PShape), vertices do not need to be in the same order for the shapes to be considered equal.
      Parameters:
      a - shape a
      b - shape b
      Returns:
      true the shapes are exactly equal in their normalized form
      Since:
      1.3.0
      See Also:

    • equalsTopo

      public static boolean equalsTopo(processing.core.PShape a, processing.core.PShape b)
      Tests two shapes for topological equality. In simple terms, this is equivalent to drawing the two shapes and seeing if all of their component edges overlap. It is the most robust kind of comparison but also the most computationally expensive.
      Parameters:
      a - shape a
      b - shape b
      Returns:
      true if the two shapes are topologically equal
      Since:
      1.3.0
      See Also:

    • isClockwise

      public static boolean isClockwise(processing.core.PShape shape)
      Determines if the vertices of the specified shape form a clockwise loop on the screen in Processing.
      Parameters:
      shape - a polygonal shape that may contain holes (but these aren't considered).
      Returns:
      true if clockwise; false otherwise (counter-clockwise).
      Since:
      2.0

    • isSimple

      public static boolean isSimple(processing.core.PShape shape)
      Checks whether a shape is simple. A shape is simple if it has no points of self-tangency, self-intersection or other anomalous points.

    • isConvex

      public static boolean isConvex(processing.core.PShape shape)
      Determines whether a shape is convex. A shape is convex if its interior angles are all less than or equal to 180°.

    • isConformingMesh

      public static boolean isConformingMesh(processing.core.PShape mesh)
      Determines whether a GROUP shape forms a conforming mesh / valid polygon coverage.

      Conforming meshes comprise faces that do not intersect; any adjacent faces not only share edges, but every pair of shared edges are identical (having the same coordinates) (such as a triangulation).

      Parameters:
      mesh - shape to test
      Returns:
      true if the shape is a conforming mesh
      Since:
      1.4.0

    • isValid

      public static boolean isValid(processing.core.PShape shape)
      Checks if a PShape is valid, and reports the validation error if it is invalid.

      An invalid shape is one that violates the rules of geometric validity. Some common reasons for a shape to be considered invalid include:

      • Self-intersection: The shape intersects itself at one or more points or segments, creating overlapping or self-crossing areas.
      • Invalid topology: The shape's topology is incorrect, such as having dangling edges, disconnected components, or invalid ring configurations in polygons.
      • Degenerate geometry: The shape has collapsed or degenerate components, such as zero-length lines, zero-area polygons, or overlapping vertices.
      Parameters:
      shape - The PShape to validate.
      Returns:
      true if the shape is valid, false otherwise.
      Since:
      1.4.0