Class ConvexArea
- java.lang.Object
-
- org.apache.commons.geometry.core.partitioning.AbstractConvexHyperplaneBoundedRegion<Vector2D,LineConvexSubset>
-
- org.apache.commons.geometry.euclidean.twod.ConvexArea
-
- All Implemented Interfaces:
BoundarySource<LineConvexSubset>
,HyperplaneBoundedRegion<Vector2D>
,Splittable<Vector2D,HyperplaneBoundedRegion<Vector2D>>
,Region<Vector2D>
,Sized
,BoundarySource2D
,Linecastable2D
- Direct Known Subclasses:
Parallelogram
public class ConvexArea extends AbstractConvexHyperplaneBoundedRegion<Vector2D,LineConvexSubset> implements BoundarySource2D
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.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from class org.apache.commons.geometry.core.partitioning.AbstractConvexHyperplaneBoundedRegion
AbstractConvexHyperplaneBoundedRegion.ConvexRegionBoundaryBuilder<P extends Point<P>,S extends HyperplaneConvexSubset<P>>
-
-
Field Summary
Fields Modifier and Type Field Description private static ConvexArea
FULL
Instance representing the full 2D plane.private static java.lang.String
NON_CONVEX_PATH_ERROR
Error message used when attempting to construct a convex polygon from a non-convex line path.
-
Constructor Summary
Constructors Modifier Constructor Description protected
ConvexArea(java.util.List<LineConvexSubset> boundaries)
Simple constructor.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.stream.Stream<LineConvexSubset>
boundaryStream()
Return a stream containing the boundaries for this instance.static ConvexArea
convexPolygonFromPath(LinePath path)
Construct a convex polygon from a line path.static ConvexArea
convexPolygonFromVertices(java.util.Collection<Vector2D> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex polygon from the given vertices.static ConvexArea
fromBounds(java.lang.Iterable<Line> bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding lines.static ConvexArea
fromBounds(Line... bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding lines.static ConvexArea
full()
Return an instance representing the full 2D area.java.util.List<LinePath>
getBoundaryPaths()
Get the connected line subset paths comprising the boundary of the area.Vector2D
getCentroid()
Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique.double
getSize()
Get the size of the instance.java.util.List<Vector2D>
getVertices()
Get the vertices for the area in a counter-clockwise order.Split<ConvexArea>
split(Hyperplane<Vector2D> splitter)
Split this instance with the given hyperplane.RegionBSPTree2D
toTree()
Return a BSP tree representing the same region as this instance.ConvexArea
transform(Transform<Vector2D> transform)
Return a new instance transformed by the argument.LineConvexSubset
trim(HyperplaneConvexSubset<Vector2D> convexSubset)
Trim the given hyperplane subset to the portion contained inside this instance.-
Methods inherited from class org.apache.commons.geometry.core.partitioning.AbstractConvexHyperplaneBoundedRegion
classify, getBoundaries, getBoundarySize, isEmpty, isFull, project, splitInternal, swapsInsideOutside, toString, transformInternal
-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
Methods inherited from interface org.apache.commons.geometry.euclidean.twod.BoundarySource2D
getBounds, linecast, linecastFirst, toList
-
Methods inherited from interface org.apache.commons.geometry.euclidean.twod.Linecastable2D
linecast, linecastFirst
-
Methods inherited from interface org.apache.commons.geometry.core.Sized
isFinite, isInfinite
-
-
-
-
Field Detail
-
NON_CONVEX_PATH_ERROR
private static final java.lang.String NON_CONVEX_PATH_ERROR
Error message used when attempting to construct a convex polygon from a non-convex line path.- See Also:
- Constant Field Values
-
FULL
private static final ConvexArea FULL
Instance representing the full 2D plane.
-
-
Constructor Detail
-
ConvexArea
protected ConvexArea(java.util.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 Detail
-
boundaryStream
public java.util.stream.Stream<LineConvexSubset> boundaryStream()
Return a stream containing the boundaries for this instance.- Specified by:
boundaryStream
in interfaceBoundarySource<LineConvexSubset>
- Returns:
- a stream containing the boundaries for this instance
-
getBoundaryPaths
public java.util.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 java.util.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 classAbstractConvexHyperplaneBoundedRegion<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.
-
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 interfaceRegion<Vector2D>
- Returns:
- the centroid of the region or null if no unique centroid exists
- See Also:
- Centroid
-
split
public Split<ConvexArea> split(Hyperplane<Vector2D> splitter)
Split this instance with the given hyperplane.- Specified by:
split
in interfaceSplittable<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 interfaceBoundarySource2D
- Returns:
- a BSP tree constructed from the boundaries in this instance
- See Also:
RegionBSPTree2D.partitionedRegionBuilder()
-
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(java.util.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 polygonprecision
- precision context used for floating point comparisons- Returns:
- a convex polygon constructed using the given vertices
- Throws:
java.lang.IllegalStateException
- ifvertices
contains only a single unique vertexjava.lang.IllegalArgumentException
- if the constructed path does not define a closed, convex polygon- See Also:
LinePath.fromVertexLoop(Collection, Precision.DoubleEquivalence)
-
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:
java.lang.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:
java.lang.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(java.lang.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:
java.lang.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.
-
-