Package org.apache.commons.geometry.euclidean.oned

Class Interval

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 java.lang.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 Interval	FULL	Interval instance representing the entire real number line.
private OrientedPoint	maxBoundary	OrientedPoint instance representing the max boundary of the interval, or null if no max boundary exists.
private OrientedPoint	minBoundary	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
RegionLocation	classify(double location)	Classify a point with respect to the interval.
RegionLocation	classify(Vector1D pt)	Classify the given point with respect to the region.
private RegionLocation	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	full()	Return an interval representing the entire real number line.
double	getBoundarySize()	Get the size of the boundary of the region.
Vector1D	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 value for the interval or Double.POSITIVE_INFINITY if no maximum value exists.
OrientedPoint	getMaxBoundary()	Get the OrientedPoint forming the maximum bounding hyperplane of the interval, or null if none exists.
double	getMin()	Get the minimum value for the interval or Double.NEGATIVE_INFINITY if no minimum value exists.
OrientedPoint	getMinBoundary()	Get the OrientedPoint forming the minimum bounding hyperplane of the interval, or null if none exists.
double	getSize()	Get the size of the instance.
boolean	hasMaxBoundary()	Return true if the interval has a maximum (upper) boundary.
boolean	hasMinBoundary()	Return true if the interval has a minimum (lower) boundary.
boolean	isEmpty()	Return true if the region is completely empty, ie all points in the space are classified as outside.
boolean	isFinite()	True if the region is finite, meaning that both the minimum and maximum boundaries exist and the region size is finite.
boolean	isFull()	Return true if the region spans the entire space.
boolean	isInfinite()	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	of(OrientedPoint a, OrientedPoint b)	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.
Vector1D	project(Vector1D pt)	Project a point onto the boundary of the region.
Split<Interval>	split(Hyperplane<Vector1D> splitter)	Split this instance with the given hyperplane.
java.lang.String	toString()
RegionBSPTree1D	toTree()	Return a RegionBSPTree1D representing the same region as this instance.
Interval	transform(Transform<Vector1D> transform)	Return a new instance transformed by the argument.
private static void	validateBoundaryRelationship(OrientedPoint a, OrientedPoint b)	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 Detail

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 Detail

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 Detail

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:

classify(Vector1D)

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:

Region.contains(org.apache.commons.geometry.core.Point)

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:

Centroid

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:

RegionBSPTree1D.from(Interval, Interval...)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.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:

java.lang.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:

java.lang.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:

java.lang.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:

isFull()

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:

java.lang.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:

java.lang.IllegalArgumentException - if either value is NaN or if both values are infinite and have the same sign