java.lang.Object
org.apache.commons.geometry.euclidean.oned.Interval
All Implemented Interfaces:
HyperplaneBoundedRegion<Vector1D>, Splittable<Vector1D,HyperplaneBoundedRegion<Vector1D>>, Region<Vector1D>, Sized

public final class Interval extends Object implements HyperplaneBoundedRegion<Vector1D>
Class representing an interval in one dimension. The interval is defined by minimum and maximum values. One or both of these values may be infinite although not with the same sign.

Instances of this class are guaranteed to be immutable.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final Interval
    Interval instance representing the entire real number line.
    private final OrientedPoint
    OrientedPoint instance representing the max boundary of the interval, or null if no max boundary exists.
    private final OrientedPoint
    OrientedPoint instance representing the min boundary of the interval, or null if no min boundary exists.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Interval(OrientedPoint minBoundary, OrientedPoint maxBoundary)
    Create an instance from min and max bounding hyperplanes.
  • Method Summary

    Modifier and Type
    Method
    Description
    classify(double location)
    Classify a point with respect to the interval.
    Classify the given point with respect to the region.
    classifyWithBoundary(double location, OrientedPoint boundary)
    Classify the location using the given interval boundary, which may be null.
    boolean
    contains(double x)
    Return true if the given point location is on the inside or boundary of the region.
    static Interval
    Return an interval representing the entire real number line.
    double
    Get the size of the boundary of the region.
    Get the centroid, or geometric center, of the region or null if no centroid exists or one exists but is not unique.
    double
    Get the maximum value for the interval or Double.POSITIVE_INFINITY if no maximum value exists.
    Get the OrientedPoint forming the maximum bounding hyperplane of the interval, or null if none exists.
    double
    Get the minimum value for the interval or Double.NEGATIVE_INFINITY if no minimum value exists.
    Get the OrientedPoint forming the minimum bounding hyperplane of the interval, or null if none exists.
    double
    Get the size of the instance.
    boolean
    Return true if the interval has a maximum (upper) boundary.
    boolean
    Return true if the interval has a minimum (lower) boundary.
    boolean
    Return true if the region is completely empty, ie all points in the space are classified as outside.
    boolean
    True if the region is finite, meaning that both the minimum and maximum boundaries exist and the region size is finite.
    boolean
    Return true if the region spans the entire space.
    boolean
    True if the region is infinite, meaning that at least one of the boundaries does not exist.
    static Interval
    max(double max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Return an interval with the given max value and no min.
    static Interval
    min(double min, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Return an interval with the given min value and no max.
    static Interval
    of(double a, double b, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Create a new interval from the given point locations.
    static Interval
    Create a new interval from the given hyperplanes.
    static Interval
    of(Vector1D a, Vector1D b, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Create a new interval from the given points.
    static Interval
    point(double location, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
    Return an interval representing a single point at the given location.
    Project a point onto the boundary of the region.
    Split this instance with the given hyperplane.
    Return a RegionBSPTree1D representing the same region as this instance.
    Return a new instance transformed by the argument.
    private static void
    Validate that the orientations and positions of the arguments may be used to create an interval.
    private static void
    validateIntervalValues(double a, double b)
    Validate that the given value can be used to construct an interval.

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

    contains
  • Field Details

    • FULL

      private static final Interval FULL
      Interval instance representing the entire real number line.
    • minBoundary

      private final OrientedPoint minBoundary
      OrientedPoint instance representing the min boundary of the interval, or null if no min boundary exists. If present, this instance will be negative-facing. Infinite values are allowed but not NaN.
    • maxBoundary

      private final OrientedPoint maxBoundary
      OrientedPoint instance representing the max boundary of the interval, or null if no max boundary exists. If present, this instance will be negative-facing. Infinite values are allowed but not NaN.
  • Constructor Details

    • Interval

      private Interval(OrientedPoint minBoundary, OrientedPoint maxBoundary)
      Create an instance from min and max bounding hyperplanes. No validation is performed. Callers are responsible for ensuring that the given hyperplanes represent a valid interval.
      Parameters:
      minBoundary - the min (negative-facing) hyperplane
      maxBoundary - the max (positive-facing) hyperplane
  • Method Details

    • getMin

      public double getMin()
      Get the minimum value for the interval or Double.NEGATIVE_INFINITY if no minimum value exists.
      Returns:
      the minimum value for the interval or Double.NEGATIVE_INFINITY if no minimum value exists.
    • getMax

      public double getMax()
      Get the maximum value for the interval or Double.POSITIVE_INFINITY if no maximum value exists.
      Returns:
      the maximum value for the interval or Double.POSITIVE_INFINITY if no maximum value exists.
    • getMinBoundary

      public OrientedPoint getMinBoundary()
      Get the OrientedPoint forming the minimum bounding hyperplane of the interval, or null if none exists. If present, This hyperplane is oriented to point in the negative direction.
      Returns:
      the hyperplane forming the minimum boundary of the interval or null if no minimum boundary exists
    • getMaxBoundary

      public OrientedPoint getMaxBoundary()
      Get the OrientedPoint forming the maximum bounding hyperplane of the interval, or null if none exists. If present, this hyperplane is oriented to point in the positive direction.
      Returns:
      the hyperplane forming the maximum boundary of the interval or null if no maximum boundary exists
    • hasMinBoundary

      public boolean hasMinBoundary()
      Return true if the interval has a minimum (lower) boundary.
      Returns:
      true if the interval has minimum (lower) boundary
    • hasMaxBoundary

      public boolean hasMaxBoundary()
      Return true if the interval has a maximum (upper) boundary.
      Returns:
      true if the interval has maximum (upper) boundary
    • isInfinite

      public boolean isInfinite()
      True if the region is infinite, meaning that at least one of the boundaries does not exist.
      Specified by:
      isInfinite in interface Sized
      Returns:
      true if the region is infinite
    • isFinite

      public boolean isFinite()
      True if the region is finite, meaning that both the minimum and maximum boundaries exist and the region size is finite.
      Specified by:
      isFinite in interface Sized
      Returns:
      true if the region is finite
    • classify

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

      public RegionLocation classify(double location)
      Classify a point with respect to the interval.
      Parameters:
      location - the location to classify
      Returns:
      the classification of the point with respect to the interval
      See Also:
    • classifyWithBoundary

      private RegionLocation classifyWithBoundary(double location, OrientedPoint boundary)
      Classify the location using the given interval boundary, which may be null.
      Parameters:
      location - the location to classify
      boundary - interval boundary to classify against
      Returns:
      the location of the point relative to the boundary
    • contains

      public boolean contains(double x)
      Return true if the given point location is on the inside or boundary of the region.
      Parameters:
      x - the location to test
      Returns:
      true if the location is on the inside or boundary of the region
      See Also:
    • project

      public Vector1D project(Vector1D 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).

      The point is projected onto the nearest interval boundary. When a point is on the inside of the interval and is equidistant from both boundaries, then the minimum boundary is selected. when a point is on the outside of the interval and is equidistant from both boundaries (as is the case for intervals representing a single point), then the boundary facing the point is returned, ensuring that the returned offset is positive.

      Specified by:
      project in interface Region<Vector1D>
      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
    • transform

      public Interval transform(Transform<Vector1D> transform)
      Return a new instance transformed by the argument.
      Parameters:
      transform - transform to apply
      Returns:
      a new instance transformed by the argument
    • 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 since there is always at least one point that can be classified as not being on the outside of the region.

      Specified by:
      isEmpty in interface Region<Vector1D>
      Returns:
      true if the region is empty
    • 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<Vector1D>
      Returns:
      true if the region spans the entire space
    • 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<Vector1D>
      Returns:
      the size of the boundary of the region
    • getCentroid

      public Vector1D 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 interface Region<Vector1D>
      Returns:
      the centroid of the region or null if no unique centroid exists
      See Also:
    • split

      public Split<Interval> split(Hyperplane<Vector1D> splitter)
      Split this instance with the given hyperplane.
      Specified by:
      split in interface Splittable<Vector1D,HyperplaneBoundedRegion<Vector1D>>
      Parameters:
      splitter - the hyperplane to split this object with.
      Returns:
      result of the split operation
    • toTree

      public RegionBSPTree1D toTree()
      Return a RegionBSPTree1D representing the same region as this instance.
      Returns:
      a BSP tree representing the same region
      See Also:
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • of

      public static Interval of(double a, double b, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Create a new interval from the given point locations. The returned interval represents the region between the points, regardless of the order they are given as arguments.
      Parameters:
      a - first point location
      b - second point location
      precision - precision context used to compare floating point numbers
      Returns:
      a new interval representing the region between the given point locations
      Throws:
      IllegalArgumentException - if either number is NaN or the numbers are both infinite and have the same sign
    • of

      public static Interval of(Vector1D a, Vector1D b, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Create a new interval from the given points. The returned interval represents the region between the points, regardless of the order they are given as arguments.
      Parameters:
      a - first point
      b - second point
      precision - precision context used to compare floating point numbers
      Returns:
      a new interval representing the region between the given points
      Throws:
      IllegalArgumentException - if either point is NaN or the points are both infinite and have the same sign
    • of

      public static Interval of(OrientedPoint a, OrientedPoint b)
      Create a new interval from the given hyperplanes. The hyperplanes may be given in any order but one must be positive-facing and the other negative-facing, with the positive-facing hyperplane located above the negative-facing hyperplane. Either or both argument may be null, in which case the returned interval will extend to infinity in the appropriate direction. If both arguments are null, an interval representing the full space is returned.
      Parameters:
      a - first hyperplane; may be null
      b - second hyperplane; may be null
      Returns:
      a new interval representing the region between the given hyperplanes
      Throws:
      IllegalArgumentException - if the hyperplanes have the same orientation or do not form an interval (for example, if the positive-facing hyperplane is below the negative-facing hyperplane)
    • min

      public static Interval min(double min, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return an interval with the given min value and no max.
      Parameters:
      min - min value for the interval
      precision - precision context used to compare floating point numbers
      Returns:
      an interval with the given min value and no max.
    • max

      public static Interval max(double max, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return an interval with the given max value and no min.
      Parameters:
      max - max value for the interval
      precision - precision context used to compare floating point numbers
      Returns:
      an interval with the given max value and no min.
    • point

      public static Interval point(double location, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return an interval representing a single point at the given location.
      Parameters:
      location - the location of the interval
      precision - precision context used to compare floating point numbers
      Returns:
      an interval representing a single point
    • full

      public static Interval full()
      Return an interval representing the entire real number line. The isFull() method of the instance will return true.
      Returns:
      an interval representing the entire real number line
      See Also:
    • validateBoundaryRelationship

      private static void validateBoundaryRelationship(OrientedPoint a, OrientedPoint b)
      Validate that the orientations and positions of the arguments may be used to create an interval. The arguments may be given in any order. Does nothing if one or both arguments are null.
      Parameters:
      a - first boundary; may be null
      b - second boundary may be null
      Throws:
      IllegalArgumentException - is a and b have the same orientation or one does not lie on the plus side of the other.
    • validateIntervalValues

      private static void validateIntervalValues(double a, double b)
      Validate that the given value can be used to construct an interval. The values must not be NaN and if infinite, must have opposite signs.
      Parameters:
      a - first value
      b - second value
      Throws:
      IllegalArgumentException - if either value is NaN or if both values are infinite and have the same sign