Package org.apache.commons.geometry.euclidean.twod

Class PolarCoordinates

java.lang.Object

org.apache.commons.geometry.euclidean.twod.PolarCoordinates

All Implemented Interfaces:

Spatial

public final class PolarCoordinates
extends java.lang.Object
implements Spatial

Class representing polar coordinates in 2 dimensional Euclidean space.

Polar coordinates are defined by a distance from a reference point and an angle from a reference direction. The distance value is called the radial coordinate, or radius, and the angle is called the angular coordinate, or azimuth. This class follows the standard mathematical convention of using the positive x-axis as the reference direction and measuring positive angles counter-clockwise, toward the positive y-axis. The origin is used as the reference point. Polar coordinate are related to Cartesian coordinates as follows:

 x = r * cos(θ)
 y = r * sin(θ)

 r = √(x^2 + y^2)
 θ = atan2(y, x)
 

where r is the radius and θ is the azimuth of the polar coordinates.

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

See Also:

Polar Coordinate System

Field Summary

Fields

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

Constructor Summary

Constructors

Modifier	Constructor	Description
private	PolarCoordinates(double radius, double azimuth)	Simple constructor.

Method Summary

Modifier and Type	Method	Description
boolean	equals(java.lang.Object other)	Test for the equality of two sets of polar coordinates.
static PolarCoordinates	fromCartesian(double x, double y)	Convert the given Cartesian coordinates to polar form.
static PolarCoordinates	fromCartesian(Vector2D vec)	Convert the given Cartesian coordinates to polar form.
double	getAzimuth()	Return the azimuth angle in radians.
int	getDimension()	Returns the number of dimensions in the space that this element belongs to.
double	getRadius()	Return the radius value.
int	hashCode()	Get a hashCode for this set of polar 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 PolarCoordinates	of(double radius, double azimuth)	Return a new instance with the given polar coordinate values.
static PolarCoordinates	parse(java.lang.String input)	Parse the given string and return a new polar coordinates instance.
Vector2D	toCartesian()	Convert this set of polar coordinates to Cartesian coordinates.
static Vector2D	toCartesian(double radius, double azimuth)	Convert the given polar coordinates to Cartesian form.
java.lang.String	toString()

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.

Constructor Detail

PolarCoordinates

private PolarCoordinates(double radius,
                         double azimuth)

Simple constructor. Input values are normalized.

Parameters:

radius - Radius value.

azimuth - Azimuth angle in radians.

Method Detail

getRadius

public double getRadius()

Return the radius value. The value will be greater than or equal to 0.

Returns:

radius value

getAzimuth

public double getAzimuth()

Return the azimuth angle in radians. The value will be in the range [0, 2pi).

Returns:

azimuth value 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

toCartesian

public Vector2D toCartesian()

Convert this set of polar coordinates to Cartesian coordinates.

Returns:

A 2-dimensional vector with an equivalent set of coordinates in Cartesian form

hashCode

public int hashCode()

Get a hashCode for this set of polar 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 polar 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 either (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 PolarCoordinates objects are equal, false if object is null, not an instance of PolarCoordinates, or not equal to this PolarCoordinates instance

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

of

public static PolarCoordinates of(double radius,
                                  double azimuth)

Return a new instance with the given polar coordinate values. The values are normalized so that radius lies in the range [0, +Infinity) and azimuth in the range [0, 2pi).

Parameters:

radius - Radius value.

azimuth - Azimuth angle in radians.

Returns:

new PolarCoordinates instance

fromCartesian

public static PolarCoordinates fromCartesian(double x,
                                             double y)

Convert the given Cartesian coordinates to polar form.

Parameters:

x - X coordinate value

y - Y coordinate value

Returns:

polar coordinates equivalent to the given Cartesian coordinates

fromCartesian

public static PolarCoordinates fromCartesian(Vector2D vec)

Convert the given Cartesian coordinates to polar form.

Parameters:

vec - vector containing Cartesian coordinates

Returns:

polar coordinates equivalent to the given Cartesian coordinates

toCartesian

public static Vector2D toCartesian(double radius,
                                   double azimuth)

Convert the given polar coordinates to Cartesian form.

Parameters:

radius - Radius value.

azimuth - Azimuth angle in radians.

Returns:

A 2-dimensional vector with an equivalent set of coordinates in Cartesian form

parse

public static PolarCoordinates parse(java.lang.String input)

Parse the given string and return a new polar coordinates instance. The parsed coordinates are normalized as in the of(double, double) method. The expected string format is the same as that returned by toString().

Parameters:

input - the string to parse

Returns:

new PolarCoordinates 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).

Parameters:

azimuth - azimuth value in radians

Returns:

equivalent azimuth value in the range [0, 2pi).