Class ConvexArea

All Implemented Interfaces:
BoundarySource<LineConvexSubset>, HyperplaneBoundedRegion<Vector2D>, Splittable<Vector2D,HyperplaneBoundedRegion<Vector2D>>, Region<Vector2D>, Sized, BoundarySource2D, Linecastable2D
Direct Known Subclasses:
Parallelogram

Class representing a finite or infinite convex area in Euclidean 2D space. The boundaries of this area, if any, are composed of convex line subsets.
  • Field Details

    • NON_CONVEX_PATH_ERROR

      private static final String NON_CONVEX_PATH_ERROR
      Error message used when attempting to construct a convex polygon from a non-convex line path.
      See Also:
    • FULL

      private static final ConvexArea FULL
      Instance representing the full 2D plane.
  • Constructor Details

    • ConvexArea

      protected ConvexArea(List<LineConvexSubset> boundaries)
      Simple constructor. Callers are responsible for ensuring that the given path represents the boundary of a convex area. No validation is performed.
      Parameters:
      boundaries - the boundaries of the convex area
  • Method Details

    • boundaryStream

      public Stream<LineConvexSubset> boundaryStream()
      Return a stream containing the boundaries for this instance.
      Specified by:
      boundaryStream in interface BoundarySource<LineConvexSubset>
      Returns:
      a stream containing the boundaries for this instance
    • getBoundaryPaths

      public List<LinePath> getBoundaryPaths()
      Get the connected line subset paths comprising the boundary of the area. The line subsets are oriented so that their minus sides point toward the interior of the region. The size of the returned list is
      • 0 if the convex area is full,
      • 1 if at least one boundary is present and a single path can connect all line subsets (this will be the case for most instances), and
      • 2 if only two boundaries exist and they are parallel to each other (in which case they cannot be connected as a single path).
      Returns:
      the line subset paths comprising the boundary of the area.
    • getVertices

      public List<Vector2D> getVertices()
      Get the vertices for the area in a counter-clockwise order. Each vertex in the returned list is unique. If the boundary of the area is closed, the start vertex is not repeated at the end of the list.

      It is important to note that, in general, the list of vertices returned by this method is not sufficient to completely characterize the area. For example, a simple triangle has 3 vertices, but an infinite area constructed from two parallel lines and two lines that intersect between them will also have 3 vertices. It is also possible for non-empty areas to contain no vertices at all. For example, an area with no boundaries (representing the full space), an area with a single boundary, or an area with two parallel boundaries will not contain any vertices.

      Returns:
      the list of vertices for the area in a counter-clockwise order
    • transform

      public ConvexArea transform(Transform<Vector2D> transform)
      Return a new instance transformed by the argument.
      Parameters:
      transform - transform to apply
      Returns:
      a new instance transformed by the argument
    • trim

      public LineConvexSubset trim(HyperplaneConvexSubset<Vector2D> convexSubset)
      Trim the given hyperplane subset to the portion contained inside this instance.
      Overrides:
      trim in class AbstractConvexHyperplaneBoundedRegion<Vector2D,LineConvexSubset>
      Parameters:
      convexSubset - hyperplane subset to trim. Null is returned if the subset does not intersect the instance.
      Returns:
      portion of the argument that lies entirely inside the region represented by this instance, or null if it does not intersect.
    • getSize

      public double getSize()
      Get the size of the instance.
      Specified by:
      getSize in interface Sized
      Returns:
      the size of the instance
    • getCentroid

      public Vector2D getCentroid()
      Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique. A centroid will not exist for empty or infinite regions.

      The centroid of a geometric object is defined as the mean position of all points in the object, including interior points, vertices, and other points lying on the boundary. If a physical object has a uniform density, then its center of mass is the same as its geometric centroid.

      Specified by:
      getCentroid in interface Region<Vector2D>
      Returns:
      the centroid of the region or null if no unique centroid exists
      See Also:
    • split

      public Split<ConvexArea> split(Hyperplane<Vector2D> splitter)
      Split this instance with the given hyperplane.
      Specified by:
      split in interface Splittable<Vector2D,HyperplaneBoundedRegion<Vector2D>>
      Parameters:
      splitter - the hyperplane to split this object with.
      Returns:
      result of the split operation
    • toTree

      public RegionBSPTree2D toTree()
      Return a BSP tree representing the same region as this instance.
      Specified by:
      toTree in interface BoundarySource2D
      Returns:
      a BSP tree constructed from the boundaries in this instance
      See Also:
    • full

      public static ConvexArea full()
      Return an instance representing the full 2D area.
      Returns:
      an instance representing the full 2D area.
    • convexPolygonFromVertices

      public static ConvexArea convexPolygonFromVertices(Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Construct a convex polygon from the given vertices.
      Parameters:
      vertices - vertices to use to construct the polygon
      precision - precision context used for floating point comparisons
      Returns:
      a convex polygon constructed using the given vertices
      Throws:
      IllegalStateException - if vertices contains only a single unique vertex
      IllegalArgumentException - if the constructed path does not define a closed, convex polygon
      See Also:
    • convexPolygonFromPath

      public static ConvexArea convexPolygonFromPath(LinePath path)
      Construct a convex polygon from a line path.
      Parameters:
      path - path to construct the polygon from
      Returns:
      a convex polygon constructed from the given line path
      Throws:
      IllegalArgumentException - if the path does not define a closed, convex polygon
    • fromBounds

      public static ConvexArea fromBounds(Line... bounds)
      Create a convex area formed by the intersection of the negative half-spaces of the given bounding lines. The returned instance represents the area that is on the minus side of all of the given lines. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)
      Parameters:
      bounds - lines used to define the convex area
      Returns:
      a new convex area instance representing the area on the minus side of all of the bounding lines or an instance representing the full area if no lines are given
      Throws:
      IllegalArgumentException - if the given set of bounding lines do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding lines.
    • fromBounds

      public static ConvexArea fromBounds(Iterable<Line> bounds)
      Create a convex area formed by the intersection of the negative half-spaces of the given bounding lines. The returned instance represents the area that is on the minus side of all of the given lines. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)
      Parameters:
      bounds - lines used to define the convex area
      Returns:
      a new convex area instance representing the area on the minus side of all of the bounding lines or an instance representing the full area if the collection is empty
      Throws:
      IllegalArgumentException - if the given set of bounding lines do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding lines.