Class Point1S
- java.lang.Object
-
- org.apache.commons.geometry.spherical.oned.Point1S
-
public final class Point1S extends java.lang.Object implements Point<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 than2pi
. However, instances separated by a multiple of2pi
are considered equivalent for most methods, with the exceptions beingequals(Object)
andhashCode()
, 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
Fields Modifier and Type Field Description private double
azimuth
Azimuthal angle in radians.static Point1S
NaN
A point with all coordinates set to NaN.static java.util.Comparator<Point1S>
NORMALIZED_AZIMUTH_ASCENDING_ORDER
Comparator that sorts points by normalized azimuth in ascending order.private double
normalizedAzimuth
Normalized azimuth value in the range[0, 2pi)
.static Point1S
PI
A point with coordinates set topi
.static Point1S
ZERO
A point with coordinates set to0*pi
.
-
Constructor Summary
Constructors Modifier Constructor Description private
Point1S(double azimuth, double normalizedAzimuth)
Build a point from its internal components.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Point1S
above(double base)
Return an equivalent point with an azimuth value at or above the given base value in radians.Point1S
above(Point1S base)
Return an equivalent point with an azimuth value at or above the given base.Point1S
antipodal()
Get the point exactly opposite this point on the circle,pi
distance away.double
distance(Point1S point)
Compute the distance between this point and another point.static double
distance(Point1S p1, Point1S p2)
Compute the shortest distance (angular separation) between two points.boolean
eq(Point1S other, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
Return true if this instance is equivalent to the argument.boolean
equals(java.lang.Object other)
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
from(Vector2D vector)
Create a new point instance from the given Euclidean 2D vector.double
getAzimuth()
Get the azimuth angle in radians.int
getDimension()
Returns the number of dimensions in the space that this element belongs to.double
getNormalizedAzimuth()
Get the azimuth angle normalized to the range[0, 2pi)
.Vector2D
getVector()
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
isInfinite()
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(java.lang.String str)
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.java.lang.String
toString()
-
-
-
Field Detail
-
ZERO
public static final Point1S ZERO
A point with coordinates set to0*pi
.
-
PI
public static final Point1S PI
A point with coordinates set topi
.
-
NaN
public static final Point1S NaN
A point with all coordinates set to NaN.
-
NORMALIZED_AZIMUTH_ASCENDING_ORDER
public static final java.util.Comparator<Point1S> 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:
getNormalizedAzimuth()
-
azimuth
private final double azimuth
Azimuthal angle in radians.
-
normalizedAzimuth
private final double normalizedAzimuth
Normalized azimuth value in the range[0, 2pi)
.
-
-
Method Detail
-
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:
of(double)
-
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
public Vector2D 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
public double distance(Point1S point)
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
public double signedDistance(Point1S point)
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
public Point1S above(double base)
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:
java.lang.IllegalArgumentException
- if the azimuth value is NaN or infinite and cannot be normalized
-
above
public Point1S above(Point1S base)
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:
java.lang.IllegalArgumentException
- if the azimuth value is NaN or infinite and cannot be normalized
-
antipodal
public Point1S 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.
- Overrides:
hashCode
in classjava.lang.Object
- Returns:
- a hash code value for this object
-
equals
public boolean equals(java.lang.Object other)
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
.- Overrides:
equals
in classjava.lang.Object
- Parameters:
other
- Object to test for equality to this- Returns:
- true if two points on the 1-sphere objects are exactly equal, false if object is null, not an instance of Point1S, or not equal to this Point1S instance
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
of
public static Point1S of(double azimuth)
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:
getAzimuth()
-
of
public static Point1S of(org.apache.commons.numbers.angle.Angle azimuth)
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:
getAzimuth()
-
from
public static Point1S from(Vector2D vector)
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
public static Point1S from(PolarCoordinates polar)
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
public static Point1S parse(java.lang.String str)
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:
java.lang.IllegalArgumentException
- if the given string has an invalid format
-
signedDistance
public static double signedDistance(Point1S p1, Point1S p2)
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
public static double distance(Point1S p1, Point1S p2)
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:
signedDistance(Point1S, Point1S)
-
-