Class Point1S

  • All Implemented Interfaces:
    Point<Point1S>, Spatial

    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 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 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 to pi.
      static 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

      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()
      • 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 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).
    • Constructor Detail

      • 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 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 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:
        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 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 java.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 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 java.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 class java.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 by toString().
        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 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)