S2Point (Apache Commons Math 3.3 API)

org.apache.commons.math3.geometry.spherical.twod

## Class S2Point

- java.lang.Object
- - org.apache.commons.math3.geometry.spherical.twod.S2Point

- All Implemented Interfaces:
    Serializable, Point<Sphere2D>

      public class S2Point
      extends Object
      implements Point<Sphere2D>

  This class represents a point on the 2-sphere.

  We use the mathematical convention to use the azimuthal angle \( \theta \) in the x-y plane as the first coordinate, and the polar angle \( \varphi \) as the second coordinate (see Spherical Coordinates in MathWorld).

  Instances of this class are guaranteed to be immutable.

  Since:
    3.3
  Version:
    $Id: S2Point.java 1554651 2014-01-01 17:27:48Z luc $
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static S2Point` | `MINUS_I` -I (coordinates: \( \theta = \pi, \varphi = \pi/2 \)).
    `static S2Point` | `MINUS_J` -J (coordinates: \( \theta = 3\pi/2, \varphi = \pi/2 \)).
    `static S2Point` | `MINUS_K` -K (coordinates: \( \theta = any angle, \varphi = \pi \)).
    `static S2Point` | `NaN` A vector with all coordinates set to NaN.
    `static S2Point` | `PLUS_I` +I (coordinates: \( \theta = 0, \varphi = \pi/2 \)).
    `static S2Point` | `PLUS_J` +J (coordinates: \( \theta = \pi/2, \varphi = \pi/2 \))).
    `static S2Point` | `PLUS_K` +K (coordinates: \( \theta = any angle, \varphi = 0 \)).

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `S2Point(double theta, double phi)` Simple constructor.
    `S2Point(Vector3D vector)` Simple constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `double` | `distance(Point<Sphere2D> point)` Compute the distance between the instance and another point.
    `static double` | `distance(S2Point p1, S2Point p2)` Compute the distance (angular separation) between two points.
    `boolean` | `equals(Object other)` Test for the equality of two points on the 2-sphere.
    `double` | `getPhi()` Get the polar angle \( \varphi \).
    `Space` | `getSpace()` Get the space to which the point belongs.
    `double` | `getTheta()` Get the azimuthal angle \( \theta \) in the x-y plane.
    `Vector3D` | `getVector()` Get the corresponding normalized vector in the 3D euclidean space.
    `int` | `hashCode()` Get a hashCode for the 2D vector.
    `boolean` | `isNaN()` Returns true if any coordinate of this point is NaN; false otherwise
    `S2Point` | `negate()` Get the opposite of the instance.

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PLUS_I

          public static final S2Point PLUS_I

      +I (coordinates: \( \theta = 0, \varphi = \pi/2 \)).

    - #### PLUS_J

          public static final S2Point PLUS_J

      +J (coordinates: \( \theta = \pi/2, \varphi = \pi/2 \))).

    - #### PLUS_K

          public static final S2Point PLUS_K

      +K (coordinates: \( \theta = any angle, \varphi = 0 \)).

    - #### MINUS_I

          public static final S2Point MINUS_I

      -I (coordinates: \( \theta = \pi, \varphi = \pi/2 \)).

    - #### MINUS_J

          public static final S2Point MINUS_J

      -J (coordinates: \( \theta = 3\pi/2, \varphi = \pi/2 \)).

    - #### MINUS_K

          public static final S2Point MINUS_K

      -K (coordinates: \( \theta = any angle, \varphi = \pi \)).

    - #### NaN

          public static final S2Point NaN

      A vector with all coordinates set to NaN.

  - ### Constructor Detail

    - #### S2Point

          public S2Point(double theta,
                 double phi)
                  throws OutOfRangeException

      Simple constructor. Build a vector from its spherical coordinates
      Parameters:
        `theta` - azimuthal angle \( \theta \) in the x-y plane
        `phi` - polar angle \( \varphi \)
      Throws:
        `OutOfRangeException` - if \( \varphi \) is not in the [\( 0; \pi \)] range
      See Also:
        `getTheta()`, `getPhi()`

    - #### S2Point

          public S2Point(Vector3D vector)
                  throws MathArithmeticException

      Simple constructor. Build a vector from its underlying 3D vector
      Parameters:
        `vector` - 3D vector
      Throws:
        `MathArithmeticException` - if vector norm is zero

  - ### Method Detail

    - #### getTheta

          public double getTheta()

      Get the azimuthal angle \( \theta \) in the x-y plane.
      Returns:
        azimuthal angle \( \theta \) in the x-y plane
      See Also:
        `S2Point(double, double)`

    - #### getPhi

          public double getPhi()

      Get the polar angle \( \varphi \).
      Returns:
        polar angle \( \varphi \)
      See Also:
        `S2Point(double, double)`

    - #### getVector

          public Vector3D getVector()

      Get the corresponding normalized vector in the 3D euclidean space.
      Returns:
        normalized vector

    - #### getSpace

          public Space getSpace()

      Get the space to which the point belongs.
      Specified by:
        `getSpace` in interface `Point<Sphere2D>`
      Returns:
        containing space

    - #### isNaN

          public boolean isNaN()

      Returns true if any coordinate of this point is NaN; false otherwise
      Specified by:
        `isNaN` in interface `Point<Sphere2D>`
      Returns:
        true if any coordinate of this point is NaN; false otherwise

    - #### negate

          public S2Point negate()

      Get the opposite of the instance.
      Returns:
        a new vector which is opposite to the instance

    - #### distance

          public double distance(Point<Sphere2D> point)

      Compute the distance between the instance and another point.
      Specified by:
        `distance` in interface `Point<Sphere2D>`
      Parameters:
        `point` - second point
      Returns:
        the distance between the instance and p

    - #### distance

          public static double distance(S2Point p1,
                        S2Point p2)

      Compute the distance (angular separation) between two points.
      Parameters:
        `p1` - first vector
        `p2` - second vector
      Returns:
        the angular separation between p1 and p2

    - #### equals

          public boolean equals(Object other)

      Test for the equality of two points on the 2-sphere.

      If all coordinates of two points are exactly the same, and none are `Double.NaN`, the two points are considered to be 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 2D vector are equal to `Double.NaN`, the 2D vector 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 equal, false if object is null, not an instance of S2Point, or not equal to this S2Point instance

    - #### hashCode

          public int hashCode()

      Get a hashCode for the 2D vector.

      All NaN values have the same hash code.

      Overrides:
        `hashCode` in class `Object`
      Returns:
        a hash code value for this object

Copyright © 2003–2014 The Apache Software Foundation. All rights reserved.