java.lang.Object
- org.apache.commons.geometry.euclidean.threed.SphericalCoordinates

All Implemented Interfaces:

Spatial
```
public final class SphericalCoordinates
extends java.lang.Object
implements Spatial
```
Class representing spherical coordinates in 3 dimensional Euclidean space.
Spherical coordinates for a point are defined by three values:
1. Radius - The distance from the point to a fixed referenced point.
2. Azimuth angle - The angle measured from a fixed reference direction in a plane to the orthogonal projection of the point on that plane.
3. Polar angle - The angle measured from a fixed zenith direction to the point. The zenith direction must be orthogonal to the reference plane.
This class follows the convention of using the origin as the reference point; the positive x-axis as the reference direction for the azimuth angle, measured in the x-y plane with positive angles moving counter-clockwise toward the positive y-axis; and the positive z-axis as the zenith direction. Spherical coordinates are related to Cartesian coordinates as follows:
```
 x = r cos(θ) sin(Φ)
 y = r sin(θ) sin(Φ)
 z = r cos(Φ)

 r = √(x^2 + y^2 + z^2)
 θ = atan2(y, x)
 Φ = acos(z/r)
 
```
where r is the radius, θ is the azimuth angle, and Φ is the polar angle of the spherical coordinates.
There are numerous, competing conventions for the symbols used to represent spherical coordinate values. For example, the mathematical convention is to use (r, θ, Φ) to represent radius, azimuth angle, and polar angle, whereas the physics convention flips the angle values and uses (r, Φ, θ). As such, this class avoids the use of these symbols altogether in favor of the less ambiguous formal names of the values, e.g. radius, azimuth, and polar.

In order to ensure the uniqueness of coordinate sets, coordinate values are normalized so that radius is in the range [0, +Infinity), azimuth is in the range [0, 2pi), and polar is in the range [0, pi].
See Also:

Spherical Coordinate System

Field Summary

Fields
Modifier and Type Field Description

private double azimuth
Azimuth angle in radians.

private double polar
Polar angle in radians.

private double radius
Radius value.

Constructor Summary

Constructors
Modifier Constructor Description

private SphericalCoordinates(double radius, double azimuth, double polar)
Simple constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`boolean`	`equals(java.lang.Object other)`	Test for the equality of two sets of spherical coordinates.
`static SphericalCoordinates`	`fromCartesian(double x, double y, double z)`	Convert the given set of Cartesian coordinates to spherical coordinates.
`static SphericalCoordinates`	`fromCartesian(Vector3D vec)`	Convert the given set of Cartesian coordinates to spherical coordinates.
`double`	`getAzimuth()`	Return the azimuth angle in radians.
`int`	`getDimension()`	Returns the number of dimensions in the space that this element belongs to.
`double`	`getPolar()`	Return the polar angle in radians.
`double`	`getRadius()`	Return the radius value.
`int`	`hashCode()`	Get a hashCode for this set of spherical coordinates.
`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 double`	`normalizeAzimuth(double azimuth)`	Normalize an azimuth value to be within the range `[0, 2pi)`.
`static double`	`normalizePolar(double polar)`	Normalize a polar value to be within the range `[0, +pi]`.
`static SphericalCoordinates`	`of(double radius, double azimuth, double polar)`	Return a new instance with the given spherical coordinate values.
`static SphericalCoordinates`	`parse(java.lang.String input)`	Parse the given string and return a new `SphericalCoordinates` instance.
`static Vector3D`	`toCartesian(double radius, double azimuth, double polar)`	Convert the given set of spherical coordinates to Cartesian coordinates.
`java.lang.String`	`toString()`
`Vector3D`	`toVector()`	Convert this set of spherical coordinates to a Cartesian form.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - radius
```
private final double radius
```
    Radius value.
  - azimuth
```
private final double azimuth
```
    Azimuth angle in radians.
  - polar
```
private final double polar
```
    Polar angle in radians.
- Constructor Detail
  - SphericalCoordinates
```
private SphericalCoordinates(double radius,
                             double azimuth,
                             double polar)
```
    Simple constructor. The given inputs are normalized.
    
    Parameters:
    
    radius - Radius value.
    
    azimuth - Azimuth angle in radians.
    
    polar - Polar angle in radians.
- Method Detail
  - getRadius
```
public double getRadius()
```
    Return the radius value. The value is in the range [0, +Infinity).
    
    Returns:
    
    the radius value
  - getAzimuth
```
public double getAzimuth()
```
    Return the azimuth angle in radians. This is the angle in the x-y plane measured counter-clockwise from the positive x axis. The angle is in the range [0, 2pi).
    
    Returns:
    
    the azimuth angle in radians
  - getPolar
```
public double getPolar()
```
    Return the polar angle in radians. This is the angle the coordinate ray makes with the positive z axis. The angle is in the range [0, pi].
    
    Returns:
    
    the polar angle in radians
  - 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
  - toVector
```
public Vector3D toVector()
```
    Convert this set of spherical coordinates to a Cartesian form.
    
    Returns:
    
    A 3-dimensional vector with an equivalent set of Cartesian coordinates.
  - hashCode
```
public int hashCode()
```
    Get a hashCode for this set of spherical coordinates.
    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 sets of spherical coordinates.
    If all values of two sets of coordinates are exactly the same, and none are Double.NaN, the two sets are considered to be equal.
    
    NaN values are considered to globally affect the coordinates and be equal to each other - i.e, if any (or all) values of the coordinate set are equal to Double.NaN, the set as a whole is considered to equal NaN.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    other - Object to test for equality to this
    
    Returns:
    
    true if two SphericalCoordinates objects are equal, false if object is null, not an instance of SphericalCoordinates, or not equal to this SphericalCoordinates instance
  - toString
```
public java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - of
```
public static SphericalCoordinates of(double radius,
                                      double azimuth,
                                      double polar)
```
    Return a new instance with the given spherical coordinate values. The values are normalized so that radius lies in the range [0, +Infinity), azimuth lies in the range [0, 2pi), and polar lies in the range [0, +pi].
    
    Parameters:
    
    radius - the length of the line segment from the origin to the coordinate point.
    
    azimuth - the angle in the x-y plane, measured in radians counter-clockwise from the positive x-axis.
    
    polar - the angle in radians between the positive z-axis and the ray from the origin to the coordinate point.
    
    Returns:
    
    a new SphericalCoordinates instance representing the same point as the given set of spherical coordinates.
  - fromCartesian
```
public static SphericalCoordinates fromCartesian(double x,
                                                 double y,
                                                 double z)
```
    Convert the given set of Cartesian coordinates to spherical coordinates.
    
    Parameters:
    
    x - X coordinate value
    
    y - Y coordinate value
    
    z - Z coordinate value
    
    Returns:
    
    a set of spherical coordinates equivalent to the given Cartesian coordinates
  - fromCartesian
```
public static SphericalCoordinates fromCartesian(Vector3D vec)
```
    Convert the given set of Cartesian coordinates to spherical coordinates.
    
    Parameters:
    
    vec - vector containing Cartesian coordinates to convert
    
    Returns:
    
    a set of spherical coordinates equivalent to the given Cartesian coordinates
  - toCartesian
```
public static Vector3D toCartesian(double radius,
                                   double azimuth,
                                   double polar)
```
    Convert the given set of spherical coordinates to Cartesian coordinates.
    
    Parameters:
    
    radius - The spherical radius value.
    
    azimuth - The spherical azimuth angle in radians.
    
    polar - The spherical polar angle in radians.
    
    Returns:
    
    A 3-dimensional vector with an equivalent set of Cartesian coordinates.
  - parse
```
public static SphericalCoordinates parse(java.lang.String input)
```
    Parse the given string and return a new SphericalCoordinates instance. The parsed coordinate values are normalized as in the of(double, double, double) method. The expected string format is the same as that returned by toString().
    
    Parameters:
    
    input - the string to parse
    
    Returns:
    
    new SphericalCoordinates instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if the string format is invalid.
  - normalizeAzimuth
```
public static double normalizeAzimuth(double azimuth)
```
    Normalize an azimuth value to be within the range [0, 2pi). This is exactly equivalent to PolarCoordinates.normalizeAzimuth(double).
    
    Parameters:
    
    azimuth - azimuth value in radians
    
    Returns:
    
    equivalent azimuth value in the range [0, 2pi).
    
    See Also:
    
    PolarCoordinates.normalizeAzimuth(double)
  - normalizePolar
```
public static double normalizePolar(double polar)
```
    Normalize a polar value to be within the range [0, +pi]. Since the polar angle is the angle between two vectors (the zenith direction and the point vector), the sign of the angle is not significant as in the azimuth angle. For example, a polar angle of -pi/2 and one of +pi/2 will both normalize to pi/2.
    
    Parameters:
    
    polar - polar value in radians
    
    Returns:
    
    equivalent polar value in the range [0, +pi]

Modifier and Type	Field	Description
`private double`	`azimuth`	Azimuth angle in radians.
`private double`	`polar`	Polar angle in radians.
`private double`	`radius`	Radius value.

Class SphericalCoordinates

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

radius

azimuth

polar

Constructor Detail

SphericalCoordinates

Method Detail

getRadius

getAzimuth

getPolar

getDimension

isNaN

isInfinite

isFinite

toVector

hashCode

equals

toString

of

fromCartesian

fromCartesian

toCartesian

parse

normalizeAzimuth

normalizePolar