agi.foundation.coordinates

(agi.foundation.core-2025r1.jar)

Class Cartesian

java.lang.Object

agi.foundation.coordinates.Cartesian

All Implemented Interfaces:

IEquatable<Cartesian>, ImmutableValueType, ValueType, IEquatableEpsilon<Cartesian>

public final class Cartesian
extends Object
implements IEquatable<Cartesian>, IEquatableEpsilon<Cartesian>, ImmutableValueType

A set of rectilinear 3-dimensional coordinates.

The corresponding 2-dimensional coordinates are Rectangular coordinates.

Constructor Summary

Constructors

Constructor and Description
Cartesian() Initializes a new instance.
Cartesian(AzimuthElevationRange coordinates) Initializes a set of Cartesian coordinates from the provided set of AzimuthElevationRange coordinates.
Cartesian(Cylindrical coordinates) Initializes a set of Cartesian coordinates from the provided set of Cylindrical coordinates.
Cartesian(double[] elements) Initializes a set of Cartesian coordinates from the first 3 consecutive elements in the provided array.
Cartesian(double[] elements, int startIndex) Initializes a set of Cartesian coordinates from 3 consecutive elements in the provided array.
Cartesian(double x, double y, double z) Initializes a set of Cartesian coordinates from the provided values.
Cartesian(LongitudeLatitudeRadius coordinates) Initializes a set of Cartesian coordinates from the provided set of LongitudeLatitudeRadius coordinates.
Cartesian(Pyramidal coordinates) Initializes a set of Cartesian coordinates from the provided set of Pyramidal coordinates.
Cartesian(Spherical coordinates) Initializes a set of Cartesian coordinates from the provided set of Spherical coordinates.

Method Summary

Modifier and Type	Method and Description
Cartesian	add(Cartesian other) Adds the specified set of Cartesian coordinates to this instance.
static Cartesian	add(Cartesian left, Cartesian right) Adds a specified set of Cartesian coordinates to another specified set of Cartesian coordinates.
static Motion1<Cartesian>	convertMotion(Motion1<LongitudeLatitudeRadius> motion, int order) Converts the motion given in terms of a set of LongitudeLatitudeRadius coordinates to motion of the corresponding set of Cartesian coordinates.
Cartesian	cross(Cartesian other) Forms the cross product of the specified set of Cartesian coordinates with this instance.
static Cartesian	divide(Cartesian left, double right) Divides a specified set of Cartesian coordinates by a scalar.
Cartesian	divide(double scalar) Divides this instance by a scalar.
double	dot(Cartesian other) Forms the dot product of the specified set of Cartesian coordinates with this instance.
static boolean	equals(Cartesian left, Cartesian right) Returns true if the two instances are exactly equal.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
boolean	equalsEpsilon(Cartesian other, double epsilon) Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.
boolean	equalsType(Cartesian other) Indicates whether another instance of this type is exactly equal to this instance.
double	get(int index) Gets the value of the specified element with index of 0, 1, and 2 corresponding to the coordinates X (get), Y (get), and Z (get).
boolean	getHasZeroMagnitude() Gets a value indicating whether the Magnitude (get) of this instance is zero.
boolean	getIsUndefined() Gets a value indicating whether or not any of the coordinates for this instance have the value Double.NaN.
int	getLength() Gets the number of elements in this set of coordinates.
double	getMagnitude() Gets the magnitude of this instance.
double	getMagnitudeSquared() Gets the square of the Magnitude (get) of this instance.
UnitCartesian	getMostOrthogonalAxis() Gets the axis which is most orthogonal to this instance.
UnitCartesian	getMostParallelAxis() Gets the axis which is most parallel to this instance.
static Cartesian	getUndefined() Gets a set of Cartesian coordinates with values of Double.NaN.
double	getX() Gets the linear coordinate along the positive x-axis.
double	getY() Gets the linear coordinate along the positive y-axis.
double	getZ() Gets the linear coordinate along the positive z-axis.
static Cartesian	getZero() Gets a set of Cartesian coordinates with values of zero.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
Cartesian	invert() Inverts this instance.
static Cartesian	multiply(Cartesian left, double right) Multiplies a specified set of Cartesian coordinates by a scalar.
static Cartesian	multiply(Cartesian left, Matrix3By3 right) Multiplies a specified set of Cartesian coordinates by a Matrix3By3.
Cartesian	multiply(double scalar) Multiplies this instance by a scalar.
static Cartesian	multiply(double left, Cartesian right) Multiplies a scalar by a specified set of Cartesian coordinates.
Cartesian	multiply(Matrix3By3 matrix) Multiplies this instance (treated as a row vector) by a Matrix3By3.
static Cartesian	negate(Cartesian coordinates) Negates the specified set of Cartesian coordinates, yielding a new set of Cartesian coordinates.
UnitCartesian	normalize() Forms a set of UnitCartesian coordinates from this instance.
UnitCartesian	normalize(double[] magnitude) Forms a set of UnitCartesian coordinates from this instance and returns the Magnitude (get) of the original instance in the provided parameter.
static boolean	notEquals(Cartesian left, Cartesian right) Returns true if the two instances are not exactly equal.
Cartesian	rotate(ElementaryRotation rotation) Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided ElementaryRotation rotation.
Cartesian	rotate(Matrix3By3 rotation) Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided Matrix3By3 rotation.
Cartesian	rotate(UnitQuaternion rotation) Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided UnitQuaternion rotation.
Cartesian	subtract(Cartesian other) Subtracts the specified set of Cartesian coordinates from this instance.
static Cartesian	subtract(Cartesian left, Cartesian right) Subtracts a specified set of Cartesian coordinates from another specified set of Cartesian coordinates.
static Cartesian	toCartesian(UnitCartesian coordinates) Converts a set of UnitCartesian coordinates to a set of Cartesian coordinates.
String	toString() Returns the string representation of the value of this instance.

Methods inherited from class java.lang.Object

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

Constructor Detail

Cartesian

public Cartesian()

Initializes a new instance.

Cartesian

public Cartesian(double x,
                 double y,
                 double z)

Initializes a set of Cartesian coordinates from the provided values.

Parameters:

x - The linear coordinate along the positive x-axis.

y - The linear coordinate along the positive y-axis.

z - The linear coordinate along the positive z-axis.

Cartesian

public Cartesian(@Nonnull
                 Spherical coordinates)

Initializes a set of Cartesian coordinates from the provided set of Spherical coordinates.

Parameters:

coordinates - The set of Spherical coordinates.

Cartesian

public Cartesian(@Nonnull
                 LongitudeLatitudeRadius coordinates)

Initializes a set of Cartesian coordinates from the provided set of LongitudeLatitudeRadius coordinates.

Parameters:

coordinates - The set of LongitudeLatitudeRadius coordinates.

Cartesian

public Cartesian(@Nonnull
                 Cylindrical coordinates)

Initializes a set of Cartesian coordinates from the provided set of Cylindrical coordinates.

Parameters:

coordinates - The set of Cylindrical coordinates.

Cartesian

public Cartesian(@Nonnull
                 Pyramidal coordinates)

Initializes a set of Cartesian coordinates from the provided set of Pyramidal coordinates.

Parameters:

coordinates - The set of Pyramidal coordinates.

Cartesian

public Cartesian(@Nonnull
                 AzimuthElevationRange coordinates)

Initializes a set of Cartesian coordinates from the provided set of AzimuthElevationRange coordinates.

Parameters:

coordinates - The set of AzimuthElevationRange coordinates.

Cartesian

public Cartesian(@Nonnull
                 double[] elements)

Initializes a set of Cartesian coordinates from the first 3 consecutive elements in the provided array.

Parameters:

elements - The array of coordinate values.

Throws:

ArgumentNullException - Thrown when elements is null.

ArgumentOutOfRangeException - An object of this type must be constructed from an array with at least 3 elements.

Cartesian

public Cartesian(@Nonnull
                 double[] elements,
                 int startIndex)

Initializes a set of Cartesian coordinates from 3 consecutive elements in the provided array.

Parameters:

elements - The array of coordinate values.

startIndex - The index of the first element in the array to use.

Throws:

ArgumentNullException - Thrown when the array of elements is null.

ArgumentOutOfRangeException - Thrown when an object of this type is constructed from an array with less than 3 elements.

Method Detail

getZero

@Nonnull
public static Cartesian getZero()

Gets a set of Cartesian coordinates with values of zero.

getUndefined

@Nonnull
public static Cartesian getUndefined()

Gets a set of Cartesian coordinates with values of Double.NaN.

Use IsUndefined (get) to test whether a Cartesian instance is undefined since it will return true if any of the coordinate values are Double.NaN.

convertMotion

@Nonnull
public static Motion1<Cartesian> convertMotion(@Nonnull
                                                         Motion1<LongitudeLatitudeRadius> motion,
                                                         int order)

Converts the motion given in terms of a set of LongitudeLatitudeRadius coordinates to motion of the corresponding set of Cartesian coordinates.

Parameters:

motion - The LongitudeLatitudeRadius motion.

order - The order of the highest derivative to convert.

Returns:

The motion of the Cartesian.

getX

public final double getX()

Gets the linear coordinate along the positive x-axis.

getY

public final double getY()

Gets the linear coordinate along the positive y-axis.

getZ

public final double getZ()

Gets the linear coordinate along the positive z-axis.

invert

@Nonnull
public final Cartesian invert()

Inverts this instance.

Returns:

A set of Cartesian coordinates that represents the inverse of this instance.

multiply

@Nonnull
public final Cartesian multiply(double scalar)

Multiplies this instance by a scalar.

Parameters:

scalar - The multiplier, or value which is to multiply this instance.

Returns:

A set of Cartesian coordinates that represents the result of the multiplication.

multiply

@Nonnull
public final Cartesian multiply(@Nonnull
                                          Matrix3By3 matrix)

Multiplies this instance (treated as a row vector) by a Matrix3By3.

Parameters:

matrix - The Matrix3By3 which will be premultiplied by this instance.

Returns:

A set of Cartesian coordinates that represents the result of the multiplication.

divide

@Nonnull
public final Cartesian divide(double scalar)

Divides this instance by a scalar.

Parameters:

scalar - The divisor, or value which is to divide this instance.

Returns:

A set of Cartesian coordinates that represents the result of the division.

add

@Nonnull
public final Cartesian add(@Nonnull
                                     Cartesian other)

Adds the specified set of Cartesian coordinates to this instance.

Parameters:

other - The addend, or value which is to be added to this instance.

Returns:

A set of Cartesian coordinates that represents the result of the addition.

subtract

@Nonnull
public final Cartesian subtract(@Nonnull
                                          Cartesian other)

Subtracts the specified set of Cartesian coordinates from this instance.

Parameters:

other - The subtrahend, or value which is to be subtracted from this instance.

Returns:

A set of Cartesian coordinates that represents the result of the subtraction.

cross

@Nonnull
public final Cartesian cross(@Nonnull
                                       Cartesian other)

Forms the cross product of the specified set of Cartesian coordinates with this instance.

Parameters:

other - The set of Cartesian coordinates to cross with this instance.

Returns:

A set of Cartesian coordinates that represents the result of the product.

dot

public final double dot(@Nonnull
                        Cartesian other)

Forms the dot product of the specified set of Cartesian coordinates with this instance.

Parameters:

other - The set of Cartesian coordinates to dot with this instance.

Returns:

A double that represents the result of the product.

multiply

@Nonnull
public static Cartesian multiply(@Nonnull
                                           Cartesian left,
                                           @Nonnull
                                           Matrix3By3 right)

Multiplies a specified set of Cartesian coordinates by a Matrix3By3.

Parameters:

left - The multiplicand, or value which is to be multiplied by right.

right - The multiplier, or value which is to multiply left.

Returns:

A set of Cartesian coordinates that represents the result of the multiplication.

multiply

@Nonnull
public static Cartesian multiply(@Nonnull
                                           Cartesian left,
                                           double right)

Multiplies a specified set of Cartesian coordinates by a scalar.

Parameters:

left - The multiplicand, or value which is to be multiplied by right.

right - The multiplier, or value which is to multiply left.

Returns:

A set of Cartesian coordinates that represents the result of the multiplication.

multiply

@Nonnull
public static Cartesian multiply(double left,
                                           @Nonnull
                                           Cartesian right)

Multiplies a scalar by a specified set of Cartesian coordinates.

Parameters:

left - The multiplicand, or value which is to be multiplied by right.

right - The multiplier, or value which is to multiply left.

Returns:

A set of Cartesian coordinates that represents the result of the multiplication.

divide

@Nonnull
public static Cartesian divide(@Nonnull
                                         Cartesian left,
                                         double right)

Divides a specified set of Cartesian coordinates by a scalar.

Parameters:

left - The dividend, or value which is to be divided by right.

right - The divisor, or value which is to divide left.

Returns:

A set of Cartesian coordinates that represents the result of the division.

add

@Nonnull
public static Cartesian add(@Nonnull
                                      Cartesian left,
                                      @Nonnull
                                      Cartesian right)

Adds a specified set of Cartesian coordinates to another specified set of Cartesian coordinates.

Parameters:

left - The augend, or value to which right is to be added.

right - The addend, or value which is to be added to left.

Returns:

A set of Cartesian coordinates that represents the result of the addition.

subtract

@Nonnull
public static Cartesian subtract(@Nonnull
                                           Cartesian left,
                                           @Nonnull
                                           Cartesian right)

Subtracts a specified set of Cartesian coordinates from another specified set of Cartesian coordinates.

Parameters:

left - The minuend, or value from which right is to be subtracted.

right - The subtrahend, or value which is to be subtracted from left.

Returns:

A set of Cartesian coordinates that represents the result of the subtraction.

negate

@Nonnull
public static Cartesian negate(@Nonnull
                                         Cartesian coordinates)

Negates the specified set of Cartesian coordinates, yielding a new set of Cartesian coordinates.

Parameters:

coordinates - The set of coordinates.

Returns:

The result of negating the elements of the original set of Cartesian coordinates.

rotate

@Nonnull
public final Cartesian rotate(@Nonnull
                                        ElementaryRotation rotation)

Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided ElementaryRotation rotation. This type of rotation is sometimes referred to as an "alias rotation".

For more information on how quaternions and other coordinates are used to represent rotations, see the Coordinates topic.

Parameters:

rotation - The ElementaryRotation.

Returns:

A set of Cartesian coordinates which is the result of the rotation.

Throws:

UnsupportedCaseException - Thrown if rotation's Axis (get) property is not an AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

rotate

@Nonnull
public final Cartesian rotate(@Nonnull
                                        Matrix3By3 rotation)

Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided Matrix3By3 rotation. This type of rotation is sometimes referred to as an "alias rotation".

For more information on how quaternions and other coordinates are used to represent rotations, see the Coordinates topic.

Parameters:

rotation - The Matrix3By3 rotation.

Returns:

A set of Cartesian coordinates which is the result of the rotation.

rotate

@Nonnull
public final Cartesian rotate(@Nonnull
                                        UnitQuaternion rotation)

Produces a set of Cartesian coordinates representing this instance which results from rotating the original axes used to represent this instance by the provided UnitQuaternion rotation. This type of rotation is sometimes referred to as an "alias rotation".

For more information on how quaternions and other coordinates are used to represent rotations, see the Coordinates topic.

Parameters:

rotation - The UnitQuaternion rotation.

Returns:

A set of Cartesian coordinates which is the result of the rotation.

getMostOrthogonalAxis

@Nonnull
public final UnitCartesian getMostOrthogonalAxis()

Gets the axis which is most orthogonal to this instance.

getMostParallelAxis

@Nonnull
public final UnitCartesian getMostParallelAxis()

Gets the axis which is most parallel to this instance.

getIsUndefined

public final boolean getIsUndefined()

Gets a value indicating whether or not any of the coordinates for this instance have the value Double.NaN.

getLength

public final int getLength()

Gets the number of elements in this set of coordinates.

get

public final double get(int index)

Gets the value of the specified element with index of 0, 1, and 2 corresponding to the coordinates X (get), Y (get), and Z (get).

Parameters:

index - The index to retrieve.

Returns:

The coordinate associated with the specified index.

Throws:

ArgumentOutOfRangeException - Thrown when index is less than 0 or greater than or equal to Length (get).

equals

public boolean equals(Object obj)

Indicates whether another object is exactly equal to this instance.

Overrides:

equals in class Object

Parameters:

obj - The object to compare to this instance.

Returns:

true if obj is an instance of this type and represents the same value as this instance; otherwise false.

See Also:

Object.hashCode(), HashMap

equalsType

public final boolean equalsType(@Nonnull
                                Cartesian other)

Indicates whether another instance of this type is exactly equal to this instance.

Specified by:

equalsType in interface IEquatable<Cartesian>

Parameters:

other - The instance to compare to this instance.

Returns:

true if other represents the same value as this instance; otherwise false.

equalsEpsilon

public final boolean equalsEpsilon(@Nonnull
                                   Cartesian other,
                                   double epsilon)

Indicates whether each coordinate value of another instance of this type is within the required tolerance of the corresponding coordinate value of this instance.

Specified by:

equalsEpsilon in interface IEquatableEpsilon<Cartesian>

Parameters:

other - The set of Cartesian coordinates to compare to this instance.

epsilon - The limit at which the absolute differences between the coordinate values will not be considered equal.

Returns:

true if the absolute differences are less than or equal to epsilon; otherwise false.

hashCode

public int hashCode()

Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.

Overrides:

hashCode in class Object

Returns:

A hash code for the current object.

See Also:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)

toString

public String toString()

Returns the string representation of the value of this instance.

Overrides:

toString in class Object

Returns:

A string that represents the value of this instance in the form "X, Y, Z".

equals

public static boolean equals(@Nonnull
                             Cartesian left,
                             @Nonnull
                             Cartesian right)

Returns true if the two instances are exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left represents the same value as right; otherwise false.

notEquals

public static boolean notEquals(@Nonnull
                                Cartesian left,
                                @Nonnull
                                Cartesian right)

Returns true if the two instances are not exactly equal.

Parameters:

left - The instance to compare to right.

right - The instance to compare to left.

Returns:

true if left does not represent the same value as right; otherwise false.

getMagnitude

public final double getMagnitude()

Gets the magnitude of this instance.

getMagnitudeSquared

public final double getMagnitudeSquared()

Gets the square of the Magnitude (get) of this instance.

getHasZeroMagnitude

public final boolean getHasZeroMagnitude()

Gets a value indicating whether the Magnitude (get) of this instance is zero.

normalize

@Nonnull
public final UnitCartesian normalize()

Forms a set of UnitCartesian coordinates from this instance.

The normalization of the cartesian components is accomplished in the usual way. It should be noted that this does not guarantee a result whose magnitude will be 1.0 in cases where an individual component underflows upon squaring.

Returns:

The resulting set of UnitCartesian coordinates.

Throws:

ArithmeticException - The magnitude of the provided coordinates must not be zero.

NotFiniteNumberException - The magnitude of the provided coordinates must not be infinite.

normalize

@Nonnull
public final UnitCartesian normalize(@Nonnull
                                               double[] magnitude)

Forms a set of UnitCartesian coordinates from this instance and returns the Magnitude (get) of the original instance in the provided parameter.

The normalization of the cartesian components is accomplished in the usual way. It should be noted that this does not guarantee a result whose magnitude will be 1.0 in cases where an individual component underflows upon squaring.

Parameters:

magnitude - On input, an array with one element. On return, the array is populated with the magnitude of the original set of Cartesian coordinates.

Returns:

The resulting set of UnitCartesian coordinates.

Throws:

ArithmeticException - The magnitude of the provided coordinates must not be zero.

NotFiniteNumberException - The magnitude of the provided coordinates must not be infinite.

toCartesian

@Nonnull
public static Cartesian toCartesian(@Nonnull
                                              UnitCartesian coordinates)

Converts a set of UnitCartesian coordinates to a set of Cartesian coordinates.

Parameters:

coordinates - The set of UnitCartesian coordinates.

Returns:

The resulting set of Cartesian coordinates.