Point1S (Apache Commons Geometry Spherical 1.0 API)

java.lang.Object
- org.apache.commons.geometry.spherical.oned.Point1S

All Implemented Interfaces:

Point<Point1S>, Spatial
```
public final class Point1S
extends 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 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

Fields
Modifier and Type	Field and Description
`static Point1S`	`NaN` A point with all coordinates set to NaN.
`static Comparator<Point1S>`	`NORMALIZED_AZIMUTH_ASCENDING_ORDER` Comparator that sorts points by normalized azimuth in ascending order.
`static Point1S`	`PI` A point with coordinates set to `pi`.
`static Point1S`	`ZERO` A point with coordinates set to `0*pi`.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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)`
`static double`	`distance(Point1S p1, Point1S p2)` Compute the shortest distance (angular separation) between two points.
`boolean`	`eq(Point1S other, Precision.DoubleEquivalence precision)` Return true if this instance is equivalent to the argument.
`boolean`	`equals(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()`
`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()`
`boolean`	`isInfinite()`
`boolean`	`isNaN()`
`static Point1S`	`of(org.apache.commons.numbers.angle.Angle azimuth)` Create a new point instance from the given azimuth angle.
`static Point1S`	`of(double azimuth)` Create a new point instance from the given azimuth angle.
`static Point1S`	`parse(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.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - ZERO
```
public static final Point1S ZERO
```
    A point with coordinates set to 0*pi.
  - PI
```
public static final Point1S PI
```
    A point with coordinates set to pi.
  - NaN
```
public static final Point1S NaN
```
    A point with all coordinates set to NaN.
  - NORMALIZED_AZIMUTH_ASCENDING_ORDER
```
public static final 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()
- 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()
```
    Specified by:
    
    getDimension in interface Spatial
  - isNaN
```
public boolean isNaN()
```
    Specified by:
    
    isNaN in interface Spatial
  - isInfinite
```
public boolean isInfinite()
```
    Specified by:
    
    isInfinite in interface Spatial
  - isFinite
```
public boolean isFinite()
```
    Specified by:
    
    isFinite in interface Spatial
  - distance
```
public double distance(Point1S point)
```
    The returned value is the shortest angular distance between the two points, in the range [0, pi].
    
    Specified by:
    
    distance in interface Point<Point1S>
  - signedDistance
```
public double signedDistance(Point1S point)
```
    Return the signed distance (angular separation) between this instance and the given point in the range [-pi, pi). If p1 is the current instance, p2 the given point, and d the signed distance, then p1.getAzimuth() + d is an angle equivalent to p2.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:
    
    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:
    
    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,
                  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 of 2pi are considered equivalent.
    
    Parameters:
    
    other - point to compare with
    
    precision - 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 of 2pi will not necessarily have the same hash code.
    All NaN values have the same hash code.
    
    Overrides:
    
    hashCode in class Object
    
    Returns:
    
    a hash code value for this object
  - equals
```
public boolean equals(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 of 2pi 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 to Double.NaN, the point is equal to NaN.
    
    Overrides:
    
    equals in class 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 String toString()
```
    Overrides:
    
    toString in class 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(String str)
```
    Parse the given string and returns a new point instance. The expected string format is the same as that returned by toString().
    
    Parameters:
    
    str - the string to parse
    
    Returns:
    
    point instance represented by the string
    
    Throws:
    
    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 that p1.getAzimuth() + d (where d is the signed distance) is an angle equivalent to p2.getAzimuth().
    
    Parameters:
    
    p1 - first point
    
    p2 - 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 the signed distance.
    
    Parameters:
    
    p1 - first point
    
    p2 - second point
    
    Returns:
    
    the angular separation between p1 and p2, in the range [0, pi].
    
    See Also:
    
    signedDistance(Point1S, Point1S)

Class Point1S

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ZERO

PI

NaN

NORMALIZED_AZIMUTH_ASCENDING_ORDER

Method Detail

getAzimuth

getNormalizedAzimuth

getVector

getDimension

isNaN

isInfinite

isFinite

distance

signedDistance

above

above

antipodal

eq

hashCode

equals

toString

of

of

from

from

parse

signedDistance

distance