Class Point2S

java.lang.Object
org.apache.commons.geometry.spherical.twod.Point2S
All Implemented Interfaces:
Point<Point2S>, Spatial
public final class Point2S extends 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
    static final Point2S
    MINUS_I
    -I (coordinates: ( azimuth = pi, polar = pi/2 )).
    static final Point2S
    MINUS_J
    -J (coordinates: ( azimuth = 3pi/2, polar = pi/2 )).
    static final Point2S
    MINUS_K
    -K (coordinates: ( azimuth = any angle, polar = pi )).
    static final Point2S
    NaN
    A point with all coordinates set to NaN.
    static final Point2S
    PLUS_I
    +I (coordinates: ( azimuth = 0, polar = pi/2 )).
    static final Point2S
    PLUS_J
    +J (coordinates: ( azimuth = pi/2, polar = pi/2 ))).
    static final Point2S
    PLUS_K
    +K (coordinates: ( azimuth = any angle, polar = 0 )).
    static final 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    Point2S
    antipodal()
    Get the point exactly opposite this point on the sphere.
    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(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(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.
    String
    toString()

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

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

  • Method Details

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

    • getPolar

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

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

    • 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 Object
      Returns:
      a hash code value for this object

    • equals

      public boolean equals(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 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 String toString()
      Overrides:
      toString in class 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:

    • 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:
      IllegalStateException - if vector norm is zero

    • parse

      public static Point2S parse(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:
      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