Class ConvexArea2S
- java.lang.Object
-
- org.apache.commons.geometry.core.partitioning.AbstractConvexHyperplaneBoundedRegion<Point2S,GreatArc>
-
- org.apache.commons.geometry.spherical.twod.ConvexArea2S
-
- All Implemented Interfaces:
BoundarySource<GreatArc>
,HyperplaneBoundedRegion<Point2S>
,Splittable<Point2S,HyperplaneBoundedRegion<Point2S>>
,Region<Point2S>
,Sized
,BoundarySource2S
public final class ConvexArea2S extends AbstractConvexHyperplaneBoundedRegion<Point2S,GreatArc> implements BoundarySource2S
Class representing a convex area in 2D spherical space. The boundaries of this area, if any, are composed of convex great circle arcs.
-
-
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 ConvexArea2S
FULL
Instance representing the full spherical area.private static double
FULL_SIZE
Constant containing the area of the full spherical space.private static double
HALF_SIZE
Constant containing the area of half of the spherical space.private static double
TRIANGLE_FAN_CENTROID_COMPUTE_THRESHOLD
Empirically determined threshold for computing the weighted centroid vector using the triangle fan approach.
-
Constructor Summary
Constructors Modifier Constructor Description private
ConvexArea2S(java.util.List<GreatArc> boundaries)
Construct an instance from its boundaries.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.util.stream.Stream<GreatArc>
boundaryStream()
Return a stream containing the boundaries for this instance.private static double
computeArcCentroidContribution(Vector3D.Unit a, Vector3D.Unit b, Vector3D.Unit triangleCentroid)
Compute the contribution made by a single arc to a weighted centroid vector.private static Vector3D
computeArcPoleWeightedCentroidVector(java.util.List<GreatArc> arcs)
Compute the weighted centroid vector for the triangle or polygon formed by the given arcs by adding together the arc pole vectors multiplied by their respective arc lengths.private static Vector3D
computeHemisphereWeightedCentroidVector(GreatArc arc)
Compute the weighted centroid vector for the hemisphere formed by the given arc.private static Vector3D
computeLuneWeightedCentroidVector(GreatArc a, GreatArc b)
Compute the weighted centroid vector for the lune formed by the given arcs.private static Vector3D
computeTriangleFanWeightedCentroidVector(java.util.List<GreatArc> arcs)
Compute the weighted centroid vector for the triangle or polygon formed by the given arcs using a triangle fan approach.static ConvexArea2S
fromBounds(java.lang.Iterable<GreatCircle> bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles.static ConvexArea2S
fromBounds(GreatCircle... bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles.static ConvexArea2S
fromPath(GreatArcPath path)
Construct a convex area from an arc path.static ConvexArea2S
fromVertexLoop(java.util.Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area by creating great circles between adjacent vertices.static ConvexArea2S
fromVertices(java.util.Collection<Point2S> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area from great circles between adjacent vertices.static ConvexArea2S
fromVertices(java.util.Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area by creating great circles between adjacent vertices.static ConvexArea2S
full()
Return an instance representing the full spherical 2D space.GreatArcPath
getBoundaryPath()
Get a path instance representing the boundary of the area.Point2S
getCentroid()
Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique.double[]
getInteriorAngles()
Get an array of interior angles for the area.double
getSize()
Get the size of the instance.(package private) Vector3D
getWeightedCentroidVector()
Return the weighted centroid vector of the area.Split<ConvexArea2S>
split(Hyperplane<Point2S> splitter)
Split this instance with the given hyperplane.RegionBSPTree2S
toTree()
Return a BSP tree representing the same region as this instance.ConvexArea2S
transform(Transform<Point2S> transform)
Return a new instance transformed by the argument.GreatArc
trim(HyperplaneConvexSubset<Point2S> sub)
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.spherical.twod.BoundarySource2S
toList
-
Methods inherited from interface org.apache.commons.geometry.core.Sized
isFinite, isInfinite
-
-
-
-
Field Detail
-
FULL
private static final ConvexArea2S FULL
Instance representing the full spherical area.
-
FULL_SIZE
private static final double FULL_SIZE
Constant containing the area of the full spherical space.- See Also:
- Constant Field Values
-
HALF_SIZE
private static final double HALF_SIZE
Constant containing the area of half of the spherical space.- See Also:
- Constant Field Values
-
TRIANGLE_FAN_CENTROID_COMPUTE_THRESHOLD
private static final double TRIANGLE_FAN_CENTROID_COMPUTE_THRESHOLD
Empirically determined threshold for computing the weighted centroid vector using the triangle fan approach. Areas with boundary sizes under this value use the triangle fan method to increase centroid accuracy.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
ConvexArea2S
private ConvexArea2S(java.util.List<GreatArc> boundaries)
Construct an instance from its boundaries. 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<GreatArc> boundaryStream()
Return a stream containing the boundaries for this instance.- Specified by:
boundaryStream
in interfaceBoundarySource<GreatArc>
- Returns:
- a stream containing the boundaries for this instance
-
getBoundaryPath
public GreatArcPath getBoundaryPath()
Get a path instance representing the boundary of the area. The path is oriented so that the minus sides of the arcs lie on the inside of the area.- Returns:
- the boundary path of the area
-
getInteriorAngles
public double[] getInteriorAngles()
Get an array of interior angles for the area. An empty array is returned if there are no boundary intersections (ie, it has only one boundary or no boundaries at all).The order of the angles corresponds with the order of the boundaries returned by
AbstractConvexHyperplaneBoundedRegion.getBoundaries()
: ifi
is an index into the boundaries list, thenangles[i]
is the angle between boundariesi
and(i+1) % boundariesSize
.- Returns:
- an array of interior angles for the area
-
getSize
public double getSize()
Get the size of the instance.
-
getCentroid
public Point2S 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<Point2S>
- Returns:
- the centroid of the region or null if no unique centroid exists
- See Also:
- Centroid
-
getWeightedCentroidVector
Vector3D getWeightedCentroidVector()
Return the weighted centroid vector of the area. The returned vector points in the direction of the centroid point on the surface of the unit sphere with the length of the vector proportional to the effective mass of the area at the centroid. By adding the weighted centroid vectors of multiple convex areas, a single centroid can be computed for the combined area.- Returns:
- weighted centroid vector.
- See Also:
- The Centroid and Inertia Tensor for a Spherical Triangle - John E. Brock
-
split
public Split<ConvexArea2S> split(Hyperplane<Point2S> splitter)
Split this instance with the given hyperplane.- Specified by:
split
in interfaceSplittable<Point2S,HyperplaneBoundedRegion<Point2S>>
- Parameters:
splitter
- the hyperplane to split this object with.- Returns:
- result of the split operation
-
toTree
public RegionBSPTree2S toTree()
Return a BSP tree representing the same region as this instance.- Specified by:
toTree
in interfaceBoundarySource2S
- Returns:
- a BSP tree constructed from the boundaries in this instance
-
transform
public ConvexArea2S transform(Transform<Point2S> transform)
Return a new instance transformed by the argument.- Parameters:
transform
- transform to apply- Returns:
- a new instance transformed by the argument
-
trim
public GreatArc trim(HyperplaneConvexSubset<Point2S> sub)
Trim the given hyperplane subset to the portion contained inside this instance.- Overrides:
trim
in classAbstractConvexHyperplaneBoundedRegion<Point2S,GreatArc>
- Parameters:
sub
- 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.
-
full
public static ConvexArea2S full()
Return an instance representing the full spherical 2D space.- Returns:
- an instance representing the full spherical 2D space.
-
fromVertices
public static ConvexArea2S fromVertices(java.util.Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area by creating great circles between adjacent vertices. The vertices must be given in a counter-clockwise around order the interior of the shape. If the area is intended to be closed, the beginning point must be repeated at the end of the path.- Parameters:
vertices
- vertices to use to construct the areaprecision
- precision context used to create new great circle instances- Returns:
- a convex area constructed using great circles between adjacent vertices
- See Also:
fromVertexLoop(Collection, Precision.DoubleEquivalence)
-
fromVertexLoop
public static ConvexArea2S fromVertexLoop(java.util.Collection<Point2S> vertices, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area by creating great circles between adjacent vertices. An implicit great circle is created between the last vertex given and the first one, if needed. The vertices must be given in a counter-clockwise around order the interior of the shape.- Parameters:
vertices
- vertices to use to construct the areaprecision
- precision context used to create new great circles instances- Returns:
- a convex area constructed using great circles between adjacent vertices
- See Also:
fromVertices(Collection, Precision.DoubleEquivalence)
-
fromVertices
public static ConvexArea2S fromVertices(java.util.Collection<Point2S> vertices, boolean close, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Construct a convex area from great circles between adjacent vertices.- Parameters:
vertices
- vertices to use to construct the areaclose
- if true, an additional great circle will be created between the last and first vertexprecision
- precision context used to create new great circle instances- Returns:
- a convex area constructed using great circles between adjacent vertices
-
fromPath
public static ConvexArea2S fromPath(GreatArcPath path)
Construct a convex area from an arc path. The area represents the intersection of all of the negative half-spaces of the great circles in the path. The boundaries of the returned area may therefore not match the arcs in the path.- Parameters:
path
- path to construct the area from- Returns:
- a convex area constructed from the great circles in the given path
-
fromBounds
public static ConvexArea2S fromBounds(GreatCircle... bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles. The returned instance represents the area that is on the minus side of all of the given circles. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)- Parameters:
bounds
- great circles used to define the convex area- Returns:
- a new convex area instance representing the area on the minus side of all of the bounding great circles or an instance representing the full area if no circles are given
- Throws:
java.lang.IllegalArgumentException
- if the given set of bounding great circles do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding circles.
-
fromBounds
public static ConvexArea2S fromBounds(java.lang.Iterable<GreatCircle> bounds)
Create a convex area formed by the intersection of the negative half-spaces of the given bounding great circles. The returned instance represents the area that is on the minus side of all of the given circles. Note that this method does not support areas of zero size (ie, infinitely thin areas or points.)- Parameters:
bounds
- great circles used to define the convex area- Returns:
- a new convex area instance representing the area on the minus side of all of the bounding great circles or an instance representing the full area if no circles are given
- Throws:
java.lang.IllegalArgumentException
- if the given set of bounding great circles do not form a convex area, meaning that there is no region that is on the minus side of all of the bounding circles.
-
computeHemisphereWeightedCentroidVector
private static Vector3D computeHemisphereWeightedCentroidVector(GreatArc arc)
Compute the weighted centroid vector for the hemisphere formed by the given arc.- Parameters:
arc
- arc defining the hemisphere- Returns:
- the weighted centroid vector for the hemisphere
- See Also:
getWeightedCentroidVector()
-
computeLuneWeightedCentroidVector
private static Vector3D computeLuneWeightedCentroidVector(GreatArc a, GreatArc b)
Compute the weighted centroid vector for the lune formed by the given arcs.- Parameters:
a
- first arc for the luneb
- second arc for the lune- Returns:
- the weighted centroid vector for the lune
- See Also:
getWeightedCentroidVector()
-
computeArcPoleWeightedCentroidVector
private static Vector3D computeArcPoleWeightedCentroidVector(java.util.List<GreatArc> arcs)
Compute the weighted centroid vector for the triangle or polygon formed by the given arcs by adding together the arc pole vectors multiplied by their respective arc lengths. This algorithm is described in the paper The Centroid and Inertia Tensor for a Spherical Triangle by John E Brock.Note: This algorithm works well in general but is susceptible to floating point errors on very small areas. In these cases, the computed centroid may not be in the expected location and may even be outside of the area. The
computeTriangleFanWeightedCentroidVector(List)
method can produce more accurate results in these cases.- Parameters:
arcs
- boundary arcs for the area- Returns:
- the weighted centroid vector for the area
- See Also:
computeTriangleFanWeightedCentroidVector(List)
-
computeTriangleFanWeightedCentroidVector
private static Vector3D computeTriangleFanWeightedCentroidVector(java.util.List<GreatArc> arcs)
Compute the weighted centroid vector for the triangle or polygon formed by the given arcs using a triangle fan approach. This method is specifically designed for use with areas of very small size, where use of the standard algorithm fromcomputeArcPoleWeightedCentroidVector(List)
can produce inaccurate results. The algorithm proceeds as follows:- The polygon is divided into spherical triangles using a triangle fan.
- For each triangle, the vectors of the 3 spherical points are added together to approximate the direction of the spherical centroid. This ensures that the computed centroid lies within the area.
- The length of the weighted centroid vector is determined by computing the sum of the contributions that
each arc in the triangle would make to the centroid using the algorithm from
computeArcPoleWeightedCentroidVector(List)
. This essentially performs part of that algorithm in reverse: given a centroid direction, compute the contribution that each arc makes. - The sum of the weighted centroid vectors for each triangle is computed and returned.
- Parameters:
arcs
- boundary arcs for the area; must contain at least 3 arcs- Returns:
- the weighted centroid vector for the area
- See Also:
computeArcPoleWeightedCentroidVector(List)
-
computeArcCentroidContribution
private static double computeArcCentroidContribution(Vector3D.Unit a, Vector3D.Unit b, Vector3D.Unit triangleCentroid)
Compute the contribution made by a single arc to a weighted centroid vector.- Parameters:
a
- first point in the arcb
- second point in the arctriangleCentroid
- the centroid vector for the area- Returns:
- the contribution made by the arc
ab
to the length of the weighted centroid vector
-
-