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 Object implements HyperplaneBoundedRegion<Point1S>
Class representing an angular interval of size greater than zero to 2pi. 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.

  • Field Details

    • minBoundary

      private final CutAngle minBoundary
      The minimum boundary of the interval.
    • maxBoundary

      private final CutAngle maxBoundary
      The maximum boundary of the interval.
    • midpoint

      private final Point1S midpoint
      Point halfway between the min and max boundaries.
  • Constructor Details

    • 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 interval
      maxBoundary - maximum boundary for the interval
  • Method Details

    • getMin

      public double getMin()
      Get the minimum azimuth angle for the interval, or 0 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, or 2pi 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:
    • 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 as outside.
      Specified by:
      isFull in interface Region<Point1S>
      Returns:
      true if the region spans the entire space
    • isEmpty

      public boolean isEmpty()
      Return true if the region is completely empty, ie all points in the space are classified as outside.

      This method always returns false.

      Specified by:
      isEmpty in interface Region<Point1S>
      Returns:
      true if the region is empty
    • getSize

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

      public double getBoundarySize()
      Get the size of the boundary of the region. The size is a value in the d-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 interface Region<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 interface Region<Point1S>
      Returns:
      the centroid of the region or null if no unique centroid exists
      See Also:
    • classify

      public RegionLocation classify(Point1S pt)
      Classify the given point with respect to the region.
      Specified by:
      classify in interface Region<Point1S>
      Parameters:
      pt - the point to classify
      Returns:
      the location of the point with respect to the region
    • project

      public Point1S project(Point1S pt)
      Project a point onto the boundary of the region. Null is returned if the region contains no boundaries (ie, is either full or empty).
      Specified by:
      project in interface Region<Point1S>
      Parameters:
      pt - pt to project
      Returns:
      projection of the point on the boundary of the region or null if the region does not contain any boundaries
    • 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 of AngularInterval 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 interface Splittable<Point1S,HyperplaneBoundedRegion<Point1S>>
      Parameters:
      splitter - the hyperplane to split this object with.
      Returns:
      result of the split operation
      See Also:
    • toTree

      public RegionBSPTree1S toTree()
      Return a RegionBSPTree1S instance representing the same region as this instance.
      Returns:
      a BSP tree representing the same region as this instance
    • toConvex

      public List<AngularInterval.Convex> toConvex()
      Return a list of convex intervals comprising this region.
      Returns:
      a list of convex intervals comprising this region
      See Also:
    • toString

      public String toString()
      Overrides:
      toString in class 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 to 2pi. 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 value
      max - max azimuth value
      precision - 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:
      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 to 2pi. 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 value
      max - max azimuth value
      precision - 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:
      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 point
      b - second oriented point
      Returns:
      an instance representing the angular interval between the given oriented points
      Throws:
      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, 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 to 2pi. 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 value
      max - max azimuth value
      precision - precision precision context used to compare floating point values
      factory - 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 order
      fullSpace - 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:
      IllegalArgumentException - if either azimuth is infinite or NaN
    • createInterval

      private static <T extends AngularInterval> T createInterval(CutAngle a, CutAngle b, 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 point
      b - second cut point
      factory - 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 order
      fullSpace - instance returned if the interval should represent the full space
      Returns:
      a new interval instance created from the given cut angles
      Throws:
      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 point
      b - second point
      Throws:
      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 angle
      max - 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, 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 transform
      transform - transform to apply
      factory - object used to create new instances
      Returns:
      a transformed instance