Package org.apache.commons.geometry.spherical.oned

Class Point1S

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
    Description
    private final double
    azimuth
    Azimuthal angle in radians.
    static final Point1S
    NaN
    A point with all coordinates set to NaN.
    static final Comparator<Point1S>
    NORMALIZED_AZIMUTH_ASCENDING_ORDER
    Comparator that sorts points by normalized azimuth in ascending order.
    private final double
    normalizedAzimuth
    Normalized azimuth value in the range [0, 2pi).
    static final Point1S
    PI
    A point with coordinates set to pi.
    static final Point1S
    ZERO
    A point with coordinates set to 0*pi.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    Point1S(double azimuth, double normalizedAzimuth)
    Build a point from its internal components.

  • Method Summary

    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(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(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 Details

    • 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:

    • azimuth

      private final double azimuth
      Azimuthal angle in radians.

    • normalizedAzimuth

      private final double normalizedAzimuth
      Normalized 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 angle
      normalizedAzimuth - 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

      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 interface Spatial
      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.
      Specified by:
      isNaN in interface Spatial
      Returns:
      true if any value in this element is NaN

    • 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 interface Spatial
      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.
      Specified by:
      isFinite in interface Spatial
      Returns:
      true if all values in this element are finite

    • 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].

      Specified by:
      distance in interface Point<Point1S>
      Parameters:
      point - second point
      Returns:
      the distance between this point and p

    • 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, 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 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:

    • 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:

    • 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: