Class SphericalCoordinates
- All Implemented Interfaces:
Spatial
Spherical coordinates for a point are defined by three values:
- Radius - The distance from the point to a fixed referenced point.
- Azimuth angle - The angle measured from a fixed reference direction in a plane to the orthogonal projection of the point on that plane.
- Polar angle - The angle measured from a fixed zenith direction to the point. The zenith direction must be orthogonal to the reference plane.
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:
-
Field Summary
Fields -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
SphericalCoordinates
(double radius, double azimuth, double polar) Simple constructor. -
Method Summary
Modifier and TypeMethodDescriptionboolean
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
Return the azimuth angle in radians.int
Returns the number of dimensions in the space that this element belongs to.double
getPolar()
Return the polar angle in radians.double
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
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 the given string and return a newSphericalCoordinates
instance.static Vector3D
toCartesian
(double radius, double azimuth, double polar) Convert the given set of spherical coordinates to Cartesian coordinates.toString()
toVector()
Convert this set of spherical coordinates to a Cartesian form.
-
Field Details
-
radius
private final double radiusRadius value. -
azimuth
private final double azimuthAzimuth angle in radians. -
polar
private final double polarPolar angle in radians.
-
-
Constructor Details
-
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 Details
-
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 interfaceSpatial
- 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. -
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 interfaceSpatial
- 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. -
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.
-
equals
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 toDouble.NaN
, the set as a whole is considered to equal NaN. -
toString
-
of
Return a new instance with the given spherical coordinate values. The values are normalized so thatradius
lies in the range[0, +Infinity)
,azimuth
lies in the range[0, 2pi)
, andpolar
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
Convert the given set of Cartesian coordinates to spherical coordinates.- Parameters:
x
- X coordinate valuey
- Y coordinate valuez
- Z coordinate value- Returns:
- a set of spherical coordinates equivalent to the given Cartesian coordinates
-
fromCartesian
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
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
Parse the given string and return a newSphericalCoordinates
instance. The parsed coordinate values are normalized as in theof(double, double, double)
method. The expected string format is the same as that returned bytoString()
.- Parameters:
input
- the string to parse- Returns:
- new
SphericalCoordinates
instance - Throws:
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 toPolarCoordinates.normalizeAzimuth(double)
.- Parameters:
azimuth
- azimuth value in radians- Returns:
- equivalent azimuth value in the range
[0, 2pi)
. - See Also:
-
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 topi/2
.- Parameters:
polar
- polar value in radians- Returns:
- equivalent polar value in the range
[0, +pi]
-