Class Point1S
java.lang.Object
org.apache.commons.geometry.spherical.oned.Point1S
This class represents a point on the 1-sphere, or in other words, an
azimuth angle on a circle. The value of the azimuth angle is not normalized
by default, meaning that instances can be constructed representing negative
values or values greater than
2pi
. However, instances separated by a
multiple of 2pi
are considered equivalent for most methods, with the
exceptions being equals(Object)
and hashCode()
, where the
azimuth values must match exactly in order for instances to be considered
equal.
Instances of this class are guaranteed to be immutable.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final double
Azimuthal angle in radians.static final Point1S
A point with all coordinates set to NaN.static final Comparator
<Point1S> Comparator that sorts points by normalized azimuth in ascending order.private final double
Normalized azimuth value in the range[0, 2pi)
.static final Point1S
A point with coordinates set topi
.static final Point1S
A point with coordinates set to0*pi
. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
Point1S
(double azimuth, double normalizedAzimuth) Build a point from its internal components. -
Method Summary
Modifier and TypeMethodDescriptionabove
(double base) Return an equivalent point with an azimuth value at or above the given base value in radians.Return an equivalent point with an azimuth value at or above the given base.Get the point exactly opposite this point on the circle,pi
distance away.double
Compute the distance between this point and another point.static double
Compute the shortest distance (angular separation) between two points.boolean
Return true if this instance is equivalent to the argument.boolean
Test for the exact equality of two points on the 1-sphere.static Point1S
from
(PolarCoordinates polar) Create a new point instance containing an azimuth value equal to that of the given set of polar coordinates.static Point1S
Create a new point instance from the given Euclidean 2D vector.double
Get the azimuth angle in radians.int
Returns the number of dimensions in the space that this element belongs to.double
Get the azimuth angle normalized to the range[0, 2pi)
.Get the normalized vector corresponding to this azimuth angle in 2D Euclidean space.int
hashCode()
Get a hashCode for the point.boolean
isFinite()
Returns true if all values in this element are finite, meaning they are not NaN or infinite.boolean
Returns true if any value in this element is infinite and none are NaN; otherwise, returns false.boolean
isNaN()
Returns true if any value in this element is NaN; otherwise returns false.static Point1S
of
(double azimuth) Create a new point instance from the given azimuth angle.static Point1S
of
(org.apache.commons.numbers.angle.Angle azimuth) Create a new point instance from the given azimuth angle.static Point1S
Parse the given string and returns a new point instance.double
signedDistance
(Point1S point) Return the signed distance (angular separation) between this instance and the given point in the range[-pi, pi)
.static double
signedDistance
(Point1S p1, Point1S p2) Compute the signed shortest distance (angular separation) between two points.toString()
-
Field Details
-
ZERO
A point with coordinates set to0*pi
. -
PI
A point with coordinates set topi
. -
NaN
A point with all coordinates set to NaN. -
NORMALIZED_AZIMUTH_ASCENDING_ORDER
Comparator that sorts points by normalized azimuth in ascending order. Points are only considered equal if their normalized azimuths match exactly. Null arguments are evaluated as being greater than non-null arguments.- See Also:
-
azimuth
private final double azimuthAzimuthal angle in radians. -
normalizedAzimuth
private final double normalizedAzimuthNormalized azimuth value in the range[0, 2pi)
.
-
-
Constructor Details
-
Point1S
private Point1S(double azimuth, double normalizedAzimuth) Build a point from its internal components.- Parameters:
azimuth
- azimuth anglenormalizedAzimuth
- azimuth angle normalized to the range[0, 2pi)
-
-
Method Details
-
getAzimuth
public double getAzimuth()Get the azimuth angle in radians. This value is not normalized and can be any floating point number.- Returns:
- azimuth angle
- See Also:
-
getNormalizedAzimuth
public double getNormalizedAzimuth()Get the azimuth angle normalized to the range[0, 2pi)
.- Returns:
- the azimuth angle normalized to the range
[0, 2pi)
.
-
getVector
Get the normalized vector corresponding to this azimuth angle in 2D Euclidean space.- Returns:
- normalized vector
-
getDimension
public int getDimension()Returns the number of dimensions in the space that this element belongs to.- Specified by:
getDimension
in interfaceSpatial
- Returns:
- the number of dimensions in the element's space
-
isNaN
public boolean isNaN()Returns true if any value in this element is NaN; otherwise returns false. -
isInfinite
public boolean isInfinite()Returns true if any value in this element is infinite and none are NaN; otherwise, returns false.- Specified by:
isInfinite
in interfaceSpatial
- Returns:
- true if any value in this element is infinite and none are NaN
-
isFinite
public boolean isFinite()Returns true if all values in this element are finite, meaning they are not NaN or infinite. -
distance
Compute the distance between this point and another point.The returned value is the shortest angular distance between the two points, in the range
[0, pi]
. -
signedDistance
Return the signed distance (angular separation) between this instance and the given point in the range[-pi, pi)
. Ifp1
is the current instance,p2
the given point, andd
the signed distance, thenp1.getAzimuth() + d
is an angle equivalent top2.getAzimuth()
.- Parameters:
point
- point to compute the signed distance to- Returns:
- the signed distance between this instance and the given point in the range
[-pi, pi)
-
above
Return an equivalent point with an azimuth value at or above the given base value in radians. The returned point has an azimuth value in the range[base, base + 2pi)
.- Parameters:
base
- base azimuth to place this instance's azimuth value above- Returns:
- a point equivalent to the current instance but with an azimuth
value in the range
[base, base + 2pi)
- Throws:
IllegalArgumentException
- if the azimuth value is NaN or infinite and cannot be normalized
-
above
Return an equivalent point with an azimuth value at or above the given base. The returned point has an azimuth value in the range[base, base + 2pi)
.- Parameters:
base
- point to place this instance's azimuth value above- Returns:
- a point equivalent to the current instance but with an azimuth
value in the range
[base, base + 2pi)
- Throws:
IllegalArgumentException
- if the azimuth value is NaN or infinite and cannot be normalized
-
antipodal
Get the point exactly opposite this point on the circle,pi
distance away. The azimuth of the antipodal point is in the range[0, 2pi)
.- Returns:
- the point exactly opposite this point on the circle
-
eq
public boolean eq(Point1S other, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision) Return true if this instance is equivalent to the argument. The points are considered equivalent if the shortest angular distance between them is equal to zero as evaluated by the given precision context. This means that points that differ in azimuth by multiples of2pi
are considered equivalent.- Parameters:
other
- point to compare withprecision
- precision context used for floating point comparisons- Returns:
- true if this instance is equivalent to the argument
-
hashCode
public int hashCode()Get a hashCode for the point. Points normally must have exactly the same azimuth angles in order to have the same hash code. Points will angles that differ by multiples of2pi
will not necessarily have the same hash code.All NaN values have the same hash code.
-
equals
Test for the exact equality of two points on the 1-sphere.If all coordinates of the given points are exactly the same, and none are
Double.NaN
, the points are considered to be equal. Points with azimuth values separated by multiples of2pi
are not considered equal.NaN
coordinates are considered to affect globally the vector and be equals to each other - i.e, if either (or all) coordinates of the point are equal toDouble.NaN
, the point is equal toNaN
. -
toString
-
of
Create a new point instance from the given azimuth angle.- Parameters:
azimuth
- azimuth angle in radians- Returns:
- point instance with the given azimuth angle
- See Also:
-
of
Create a new point instance from the given azimuth angle.- Parameters:
azimuth
- azimuth azimuth angle- Returns:
- point instance with the given azimuth angle
- See Also:
-
from
Create a new point instance from the given Euclidean 2D vector. The returned point will have an azimuth value equal to the angle between the positive x-axis and the given vector, measured in a counter-clockwise direction.- Parameters:
vector
- 3D vector to create the point from- Returns:
- a new point instance with an azimuth value equal to the angle between the given vector and the positive x-axis, measured in a counter-clockwise direction
-
from
Create a new point instance containing an azimuth value equal to that of the given set of polar coordinates.- Parameters:
polar
- polar coordinates to convert to a point- Returns:
- a new point instance containing an azimuth value equal to that of the given set of polar coordinates.
-
parse
Parse the given string and returns a new point instance. The expected string format is the same as that returned bytoString()
.- Parameters:
str
- the string to parse- Returns:
- point instance represented by the string
- Throws:
IllegalArgumentException
- if the given string has an invalid format
-
signedDistance
Compute the signed shortest distance (angular separation) between two points. The return value is in the range[-pi, pi)
and is such thatp1.getAzimuth() + d
(whered
is the signed distance) is an angle equivalent top2.getAzimuth()
.- Parameters:
p1
- first pointp2
- second point- Returns:
- the signed angular separation between p1 and p2, in the range
[-pi, pi)
.
-
distance
Compute the shortest distance (angular separation) between two points. The returned value is in the range[0, pi]
. This method is equal to the absolute value of thesigned distance
.- Parameters:
p1
- first pointp2
- second point- Returns:
- the angular separation between p1 and p2, in the range
[0, pi]
. - See Also:
-