org.apache.commons.geometry.euclidean.twod

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>>

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ConvexArea(List<LineConvexSubset> boundaries) Simple constructor.

Method Summary

Modifier and Type	Method and Description
Stream<LineConvexSubset>	boundaryStream()
static ConvexArea	convexPolygonFromPath(LinePath path) Construct a convex polygon from a line path.
static ConvexArea	convexPolygonFromVertices(Collection<Vector2D> vertices, Precision.DoubleEquivalence precision) Construct a convex polygon from the given vertices.
static ConvexArea	fromBounds(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.
List<LinePath>	getBoundaryPaths() Get the connected line subset paths comprising the boundary of the area.
Vector2D	getCentroid()
double	getSize()
List<Vector2D>	getVertices() Get the vertices for the area in a counter-clockwise order.
Split<ConvexArea>	split(Hyperplane<Vector2D> splitter)
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)

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, of, of, toList

Methods inherited from interface org.apache.commons.geometry.euclidean.twod.Linecastable2D

linecast, linecastFirst

Methods inherited from interface org.apache.commons.geometry.core.Region

contains

Methods inherited from interface org.apache.commons.geometry.core.Sized

isFinite, isInfinite

Constructor Detail

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 Detail

boundaryStream

public Stream<LineConvexSubset> boundaryStream()

Specified by:

boundaryStream in interface BoundarySource<LineConvexSubset>

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)

Overrides:

trim in class AbstractConvexHyperplaneBoundedRegion<Vector2D,LineConvexSubset>

getSize

public double getSize()

Specified by:

getSize in interface Sized

getCentroid

public Vector2D getCentroid()

Specified by:

getCentroid in interface Region<Vector2D>

split

public Split<ConvexArea> split(Hyperplane<Vector2D> splitter)

Specified by:

split in interface Splittable<Vector2D,HyperplaneBoundedRegion<Vector2D>>

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:

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(Collection<Vector2D> vertices,
                                                   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:

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:

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.