Class AngularInterval
- java.lang.Object
-
- org.apache.commons.geometry.spherical.oned.AngularInterval
-
- All Implemented Interfaces:
HyperplaneBoundedRegion<Point1S>
,Splittable<Point1S,HyperplaneBoundedRegion<Point1S>>
,Region<Point1S>
,Sized
- Direct Known Subclasses:
AngularInterval.Convex
public class AngularInterval extends java.lang.Object implements HyperplaneBoundedRegion<Point1S>
Class representing an angular interval of size greater than zero to2pi
. The interval is defined by two azimuth angles: a min and a max. The interval starts at the min azimuth angle and contains all points in the direction of increasing azimuth angles up to max.Instances of this class are guaranteed to be immutable.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
AngularInterval.Convex
Class representing an angular interval with the additional property that the region is convex.
-
Field Summary
Fields Modifier and Type Field Description private CutAngle
maxBoundary
The maximum boundary of the interval.private Point1S
midpoint
Point halfway between the min and max boundaries.private CutAngle
minBoundary
The minimum boundary of the interval.
-
Constructor Summary
Constructors Modifier Constructor Description private
AngularInterval(CutAngle minBoundary, CutAngle maxBoundary)
Construct a new instance representing the angular region between the given min and max azimuth boundaries.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description RegionLocation
classify(Point1S pt)
Classify the given point with respect to the region.private static <T extends AngularInterval>
TcreateInterval(CutAngle a, CutAngle b, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory, T fullSpace)
Internal method to create a new interval instance from the given cut angles.private static <T extends AngularInterval>
TcreateInterval(Point1S min, Point1S max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory, T fullSpace)
Internal method to create an interval between the given min and max points.static AngularInterval.Convex
full()
Return an instance representing the full space.double
getBoundarySize()
Get the size of the boundary of the region.Point1S
getCentroid()
Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique.double
getMax()
Get the maximum azimuth angle for the interval, or2pi
if the interval represents the full space.CutAngle
getMaxBoundary()
Get the maximum point for the interval.Point1S
getMidPoint()
Get the midpoint of the interval or null if the interval represents the full space.double
getMin()
Get the minimum azimuth angle for the interval, or0
if the interval is full.CutAngle
getMinBoundary()
Get the minimum boundary for the interval, or null if the interval represents the full space.double
getSize()
Get the size of the instance.private static boolean
isConvex(CutAngle min, CutAngle max)
Return true if the given cut angles define a convex region.boolean
isEmpty()
Return true if the region is completely empty, ie all points in the space are classified asoutside
.boolean
isFull()
Return true if the region spans the entire space.static AngularInterval
of(double min, double max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Return an instance representing the angular interval between the given min and max azimuth values.static AngularInterval
of(CutAngle a, CutAngle b)
Return an instance representing the angular interval between the given oriented points.static AngularInterval
of(Point1S min, Point1S max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Return an instance representing the angular interval between the given min and max azimuth points.Point1S
project(Point1S pt)
Project a point onto the boundary of the region.Split<RegionBSPTree1S>
split(Hyperplane<Point1S> splitter)
Split this instance with the given hyperplane.java.util.List<AngularInterval.Convex>
toConvex()
Return a list of convex intervals comprising this region.java.lang.String
toString()
RegionBSPTree1S
toTree()
Return aRegionBSPTree1S
instance representing the same region as this instance.AngularInterval
transform(Transform<Point1S> transform)
Return a new instance transformed by the argument.private static <T extends AngularInterval>
Ttransform(T interval, Transform<Point1S> transform, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory)
Internal transform method that transforms the given instance, using the factory method to create a new instance if needed.private static void
validateIntervalValues(Point1S a, Point1S b)
Validate that the given points can be used to specify an angular interval.boolean
wrapsZero()
Return true if the interval wraps around the zero/2pi
point.-
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.core.Sized
isFinite, isInfinite
-
-
-
-
Constructor Detail
-
AngularInterval
private AngularInterval(CutAngle minBoundary, CutAngle maxBoundary)
Construct a new instance representing the angular region between the given min and max azimuth boundaries. The arguments must be either all finite or all null (to indicate the full space). If the boundaries are finite, then the min boundary azimuth value must be numerically less than the max boundary. Callers are responsible for enforcing these constraints. No validation is performed.- Parameters:
minBoundary
- minimum boundary for the intervalmaxBoundary
- maximum boundary for the interval
-
-
Method Detail
-
getMin
public double getMin()
Get the minimum azimuth angle for the interval, or0
if the interval is full.- Returns:
- the minimum azimuth angle for the interval or
0
if the interval represents the full space.
-
getMinBoundary
public CutAngle getMinBoundary()
Get the minimum boundary for the interval, or null if the interval represents the full space.- Returns:
- the minimum point for the interval or null if the interval represents the full space
-
getMax
public double getMax()
Get the maximum azimuth angle for the interval, or2pi
if the interval represents the full space.- Returns:
- the maximum azimuth angle for the interval or
2pi
if the interval represents the full space.
-
getMaxBoundary
public CutAngle getMaxBoundary()
Get the maximum point for the interval. This will be null if the interval represents the full space.- Returns:
- the maximum point for the interval or null if the interval represents the full space
-
getMidPoint
public Point1S getMidPoint()
Get the midpoint of the interval or null if the interval represents the full space.- Returns:
- the midpoint of the interval or null if the interval represents the full space
- See Also:
getCentroid()
-
isFull
public boolean isFull()
Return true if the region spans the entire space. In other words, a region is full if no points in the space are classified asoutside
.
-
isEmpty
public boolean isEmpty()
Return true if the region is completely empty, ie all points in the space are classified asoutside
.This method always returns false.
-
getSize
public double getSize()
Get the size of the instance.
-
getBoundarySize
public double getBoundarySize()
Get the size of the boundary of the region. The size is a value in thed-1
dimension space. For example, in Euclidean space, this will be a length in 2D and an area in 3D.This method simply returns 0 because boundaries in one dimension do not have any size.
- Specified by:
getBoundarySize
in interfaceRegion<Point1S>
- Returns:
- the size of the boundary of the region
-
getCentroid
public Point1S 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.
This method is an alias for
getMidPoint()
.- Specified by:
getCentroid
in interfaceRegion<Point1S>
- Returns:
- the centroid of the region or null if no unique centroid exists
- See Also:
getMidPoint()
-
classify
public RegionLocation classify(Point1S pt)
Classify the given point with respect to the region.
-
wrapsZero
public boolean wrapsZero()
Return true if the interval wraps around the zero/2pi
point. In this case, the max boundary azimuth is less than that of the min boundary when both values are normalized to the range[0, 2pi)
.- Returns:
- true if the interval wraps around the zero/
2pi
point
-
transform
public AngularInterval transform(Transform<Point1S> transform)
Return a new instance transformed by the argument. If the transformed size of the interval is greater than or equal to 2pi, then an interval representing the full space is returned.- Parameters:
transform
- transform to apply- Returns:
- a new instance transformed by the argument
-
split
public Split<RegionBSPTree1S> split(Hyperplane<Point1S> splitter)
Split this instance with the given hyperplane.This method returns instances of
RegionBSPTree1S
instead ofAngularInterval
since it is possible for a convex angular interval to be split into disjoint regions by a single hyperplane. These disjoint regions cannot be represented by this class and require the use of a BSP tree.- Specified by:
split
in interfaceSplittable<Point1S,HyperplaneBoundedRegion<Point1S>>
- Parameters:
splitter
- the hyperplane to split this object with.- Returns:
- result of the split operation
- See Also:
RegionBSPTree1S.split(Hyperplane)
-
toTree
public RegionBSPTree1S toTree()
Return aRegionBSPTree1S
instance representing the same region as this instance.- Returns:
- a BSP tree representing the same region as this instance
-
toConvex
public java.util.List<AngularInterval.Convex> toConvex()
Return a list of convex intervals comprising this region.- Returns:
- a list of convex intervals comprising this region
- See Also:
AngularInterval.Convex
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
full
public static AngularInterval.Convex full()
Return an instance representing the full space. The returned instance contains all possible azimuth angles.- Returns:
- an interval representing the full space
-
of
public static AngularInterval of(double min, double max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Return an instance representing the angular interval between the given min and max azimuth values. The max value is adjusted to be numerically above the min value, even if the resulting azimuth value is greater than or equal to2pi
. An instance representing the full space is returned if either point is infinite or min and max are equivalent as evaluated by the given precision context.- Parameters:
min
- min azimuth valuemax
- max azimuth valueprecision
- precision precision context used to compare floating point values- Returns:
- a new instance resulting the angular region between the given min and max azimuths
- Throws:
java.lang.IllegalArgumentException
- if either azimuth is infinite or NaN
-
of
public static AngularInterval of(Point1S min, Point1S max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Return an instance representing the angular interval between the given min and max azimuth points. The max point is adjusted to be numerically above the min point, even if the resulting azimuth value is greater than or equal to2pi
. An instance representing the full space is returned if either point is infinite or min and max are equivalent as evaluated by the given precision context.- Parameters:
min
- min azimuth valuemax
- max azimuth valueprecision
- precision precision context used to compare floating point values- Returns:
- a new instance resulting the angular region between the given min and max points
- Throws:
java.lang.IllegalArgumentException
- if either azimuth is infinite or NaN
-
of
public static AngularInterval of(CutAngle a, CutAngle b)
Return an instance representing the angular interval between the given oriented points. The negative-facing point is used as the minimum boundary and the positive-facing point is adjusted to be above the minimum. The arguments can be given in any order. The full space is returned if the points are equivalent or are oriented in the same direction.- Parameters:
a
- first oriented pointb
- second oriented point- Returns:
- an instance representing the angular interval between the given oriented points
- Throws:
java.lang.IllegalArgumentException
- if either argument is infinite or NaN
-
createInterval
private static <T extends AngularInterval> T createInterval(Point1S min, Point1S max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory, T fullSpace)
Internal method to create an interval between the given min and max points. The max point is adjusted to be numerically above the min point, even if the resulting azimuth value is greater than or equal to2pi
. The full instance argument is returned if either point is infinite or min and max are equivalent as evaluated by the given precision context.- Type Parameters:
T
- Angular interval implementation type- Parameters:
min
- min azimuth valuemax
- max azimuth valueprecision
- precision precision context used to compare floating point valuesfactory
- factory object used to create new instances; this object is passed the validated min (negative-facing) cut and the max (positive-facing) cut, in that orderfullSpace
- instance returned if the interval should represent the full space- Returns:
- a new instance resulting the angular region between the given min and max points
- Throws:
java.lang.IllegalArgumentException
- if either azimuth is infinite or NaN
-
createInterval
private static <T extends AngularInterval> T createInterval(CutAngle a, CutAngle b, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory, T fullSpace)
Internal method to create a new interval instance from the given cut angles. The negative-facing point is used as the minimum boundary and the positive-facing point is adjusted to be above the minimum. The arguments can be given in any order. The full space argument is returned if the points are equivalent or are oriented in the same direction.- Type Parameters:
T
- Angular interval implementation type- Parameters:
a
- first cut pointb
- second cut pointfactory
- factory object used to create new instances; this object is passed the validated min (negative-facing) cut and the max (positive-facing) cut, in that orderfullSpace
- instance returned if the interval should represent the full space- Returns:
- a new interval instance created from the given cut angles
- Throws:
java.lang.IllegalArgumentException
- if either argument is infinite or NaN
-
validateIntervalValues
private static void validateIntervalValues(Point1S a, Point1S b)
Validate that the given points can be used to specify an angular interval.- Parameters:
a
- first pointb
- second point- Throws:
java.lang.IllegalArgumentException
- if either point is infinite NaN
-
isConvex
private static boolean isConvex(CutAngle min, CutAngle max)
Return true if the given cut angles define a convex region. By convention, the precision context from the min cut is used for the floating point comparison.- Parameters:
min
- min (negative-facing) cut anglemax
- max (positive-facing) cut angle- Returns:
- true if the given cut angles define a convex region
-
transform
private static <T extends AngularInterval> T transform(T interval, Transform<Point1S> transform, java.util.function.BiFunction<? super CutAngle,? super CutAngle,T> factory)
Internal transform method that transforms the given instance, using the factory method to create a new instance if needed.- Type Parameters:
T
- Angular interval implementation type- Parameters:
interval
- interval to transformtransform
- transform to applyfactory
- object used to create new instances- Returns:
- a transformed instance
-
-