Class Point2S

  • All Implemented Interfaces:
    Point<Point2S>, Spatial

    public final class Point2S
    extends java.lang.Object
    implements Point<Point2S>
    This class represents a point on the 2-sphere.

    Instances of this class are guaranteed to be immutable.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private double azimuth
      Azimuthal angle in the x-y plane.
      static Point2S MINUS_I
      -I (coordinates: ( azimuth = pi, polar = pi/2 )).
      static Point2S MINUS_J
      -J (coordinates: ( azimuth = 3pi/2, polar = pi/2 )).
      static Point2S MINUS_K
      -K (coordinates: ( azimuth = any angle, polar = pi )).
      static Point2S NaN
      A point with all coordinates set to NaN.
      static Point2S PLUS_I
      +I (coordinates: ( azimuth = 0, polar = pi/2 )).
      static Point2S PLUS_J
      +J (coordinates: ( azimuth = pi/2, polar = pi/2 ))).
      static Point2S PLUS_K
      +K (coordinates: ( azimuth = any angle, polar = 0 )).
      private double polar
      Polar angle.
      static java.util.Comparator<Point2S> POLAR_AZIMUTH_ASCENDING_ORDER
      Comparator that sorts points in component-wise ascending order, first sorting by polar value and then by azimuth value.
      private Vector3D.Unit vector
      Corresponding 3D normalized vector.
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Point2S​(double azimuth, double polar, Vector3D.Unit vector)
      Build a point from its internal components.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Point2S antipodal()
      Get the point exactly opposite this point on the sphere.
      private static Vector3D.Unit computeVector​(double azimuth, double polar)
      Compute the 3D Euclidean vector associated with the given spherical coordinates.
      double distance​(Point2S point)
      Compute the distance between this point and another point.
      static double distance​(Point2S p1, Point2S p2)
      Compute the distance (angular separation) between two points.
      boolean eq​(Point2S point, org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
      Return true if this point should be considered equivalent to the argument using the given precision context.
      boolean equals​(java.lang.Object other)
      Test for the equality of two points.
      static Point2S from​(Vector3D vector)
      Build a point from its underlying 3D vector.
      double getAzimuth()
      Get the azimuth angle in the x-y plane in the range [0, 2pi).
      int getDimension()
      Returns the number of dimensions in the space that this element belongs to.
      double getPolar()
      Get the polar angle in the range [0, pi).
      Vector3D.Unit getVector()
      Get the corresponding normalized vector in 3D 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 Point2S of​(double azimuth, double polar)
      Build a vector from its spherical coordinates.
      static Point2S parse​(java.lang.String str)
      Parses the given string and returns a new point instance.
      Point2S slerp​(Point2S other, double t)
      Spherically interpolate a point along the shortest arc between this point and the given point.
      java.lang.String toString()
      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait
    • Field Detail

      • PLUS_I

        public static final Point2S PLUS_I
        +I (coordinates: ( azimuth = 0, polar = pi/2 )).
      • PLUS_J

        public static final Point2S PLUS_J
        +J (coordinates: ( azimuth = pi/2, polar = pi/2 ))).
      • PLUS_K

        public static final Point2S PLUS_K
        +K (coordinates: ( azimuth = any angle, polar = 0 )).
      • MINUS_I

        public static final Point2S MINUS_I
        -I (coordinates: ( azimuth = pi, polar = pi/2 )).
      • MINUS_J

        public static final Point2S MINUS_J
        -J (coordinates: ( azimuth = 3pi/2, polar = pi/2 )).
      • MINUS_K

        public static final Point2S MINUS_K
        -K (coordinates: ( azimuth = any angle, polar = pi )).
      • NaN

        public static final Point2S NaN
        A point with all coordinates set to NaN.
      • POLAR_AZIMUTH_ASCENDING_ORDER

        public static final java.util.Comparator<Point2S> POLAR_AZIMUTH_ASCENDING_ORDER
        Comparator that sorts points in component-wise ascending order, first sorting by polar value and then by azimuth value. Points are only considered equal if their components match exactly. Null arguments are evaluated as being greater than non-null arguments.
      • azimuth

        private final double azimuth
        Azimuthal angle in the x-y plane.
      • polar

        private final double polar
        Polar angle.
      • vector

        private final Vector3D.Unit vector
        Corresponding 3D normalized vector.
    • Constructor Detail

      • Point2S

        private Point2S​(double azimuth,
                        double polar,
                        Vector3D.Unit vector)
        Build a point from its internal components.
        Parameters:
        azimuth - azimuthal angle in the x-y plane
        polar - polar angle
        vector - corresponding vector; if null, the vector is computed
    • Method Detail

      • getAzimuth

        public double getAzimuth()
        Get the azimuth angle in the x-y plane in the range [0, 2pi).
        Returns:
        azimuth angle in the x-y plane in the range [0, 2pi).
        See Also:
        of(double, double)
      • getPolar

        public double getPolar()
        Get the polar angle in the range [0, pi).
        Returns:
        polar angle in the range [0, pi).
        See Also:
        of(double, double)
      • getVector

        public Vector3D.Unit getVector()
        Get the corresponding normalized vector in 3D Euclidean space. This value will be null if the spherical coordinates of the point are infinite or NaN.
        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
      • antipodal

        public Point2S antipodal()
        Get the point exactly opposite this point on the sphere. The returned point is pi distance away from the current instance.
        Returns:
        the point exactly opposite this point on the sphere
      • distance

        public double distance​(Point2S point)
        Compute the distance between this point and another point.
        Specified by:
        distance in interface Point<Point2S>
        Parameters:
        point - second point
        Returns:
        the distance between this point and p
      • slerp

        public Point2S slerp​(Point2S other,
                             double t)
        Spherically interpolate a point along the shortest arc between this point and the given point. The parameter t controls the interpolation and is expected to be in the range [0, 1], with 0 returning a point equivalent to the current instance 1 returning a point equivalent to the given instance. If the points are antipodal, then an arbitrary arc is chosen from the infinite number available.
        Parameters:
        other - other point to interpolate with
        t - interpolation parameter
        Returns:
        spherically interpolated point
        See Also:
        QuaternionRotation.slerp(QuaternionRotation), QuaternionRotation.createVectorRotation(Vector3D, Vector3D)
      • eq

        public boolean eq​(Point2S point,
                          org.apache.commons.numbers.core.Precision.DoubleEquivalence precision)
        Return true if this point should be considered equivalent to the argument using the given precision context. This will be true if the distance between the points is equivalent to zero as evaluated by the precision context.
        Parameters:
        point - point to compare with
        precision - precision context used to perform floating point comparisons
        Returns:
        true if this point should be considered equivalent to the argument using the given precision context
      • hashCode

        public int hashCode()
        Get a hashCode for the point. .

        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 equality of two points.

        If all spherical coordinates of two points are exactly the same, and none are Double.NaN, the two points are considered to be equal. Note that the comparison is made using the azimuth and polar coordinates only; the corresponding 3D vectors are not compared. This is significant at the poles, where an infinite number of points share the same underlying 3D vector but may have different spherical coordinates. For example, the points (0, 0) and (1, 0) (both located at a pole but with different azimuths) will not be considered equal by this method, even though they share the exact same underlying 3D vector.

        NaN coordinates are considered to affect the point globally 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 2-sphere objects are exactly equal, false if object is null, not an instance of Point2S, or not equal to this Point2S instance
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • of

        public static Point2S of​(double azimuth,
                                 double polar)
        Build a vector from its spherical coordinates.
        Parameters:
        azimuth - azimuthal angle in the x-y plane
        polar - polar angle
        Returns:
        point instance with the given coordinates
        See Also:
        getAzimuth(), getPolar()
      • from

        public static Point2S from​(Vector3D vector)
        Build a point from its underlying 3D vector.
        Parameters:
        vector - 3D vector
        Returns:
        point instance with the coordinates determined by the given 3D vector
        Throws:
        java.lang.IllegalStateException - if vector norm is zero
      • parse

        public static Point2S parse​(java.lang.String str)
        Parses 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
      • distance

        public static double distance​(Point2S p1,
                                      Point2S p2)
        Compute the distance (angular separation) between two points.
        Parameters:
        p1 - first vector
        p2 - second vector
        Returns:
        the angular separation between p1 and p2
      • computeVector

        private static Vector3D.Unit computeVector​(double azimuth,
                                                   double polar)
        Compute the 3D Euclidean vector associated with the given spherical coordinates. Null is returned if the coordinates are infinite or NaN.
        Parameters:
        azimuth - azimuth value
        polar - polar value
        Returns:
        the 3D Euclidean vector associated with the given spherical coordinates or null if either of the arguments are infinite or NaN.