agi.foundation.coordinates

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

Class UnitQuaternion

java.lang.Object

agi.foundation.coordinates.UnitQuaternion

All Implemented Interfaces:

IEquatable<UnitQuaternion>, ImmutableValueType, ValueType, IEquatableEpsilon<UnitQuaternion>

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

A set of 4-dimensional coordinates used to represent rotation in 3-dimensional space. This represents an 'alias' rotation which transforms coordinates by modifying the underlying coordinate basis rather than modifying the coordinates themselves. To transform a Cartesian with this rotation, see Cartesian.rotate(UnitQuaternion).

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

The normalization of the quaternion 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.

See Also:

AngleAxisRotation, ElementaryRotation, EulerSequence, Matrix3By3, Quaternion, YawPitchRoll

Constructor Summary

Constructors

Constructor and Description
UnitQuaternion() Initializes a new instance.
UnitQuaternion(AngleAxisRotation rotation) Initializes a set of UnitQuaternion coordinates from the provided AngleAxisRotation.
UnitQuaternion(double[] elements) Initializes a set of UnitQuaternion coordinates from the first 4 consecutive elements in the provided array.
UnitQuaternion(double[] elements, int startIndex) Initializes a set of UnitQuaternion coordinates from 4 consecutive elements in the provided array.
UnitQuaternion(double w, double x, double y, double z) Initializes a set of UnitQuaternion coordinates from the provided values.
UnitQuaternion(double w, double x, double y, double z, double[] magnitude) Initializes a set of UnitQuaternion coordinates from the provided values.
UnitQuaternion(ElementaryRotation rotation) Initializes a set of UnitQuaternion coordinates from the provided ElementaryRotation.
UnitQuaternion(EulerSequence sequence) Initializes a set of UnitQuaternion coordinates from the provided EulerSequence.
UnitQuaternion(Matrix3By3 matrix) Initializes a set of UnitQuaternion coordinates from the provided rotation matrix (Matrix3By3).
UnitQuaternion(Quaternion coordinates) Initializes a set of UnitQuaternion coordinates from the provided set of Quaternion coordinates.
UnitQuaternion(YawPitchRoll sequence) Initializes a set of UnitQuaternion coordinates from the provided YawPitchRoll.

Method Summary

Modifier and Type	Method and Description
UnitQuaternion	conjugate() Forms the conjugate of this instance.
boolean	equals(Object obj) Indicates whether another object is exactly equal to this instance.
static boolean	equals(UnitQuaternion left, UnitQuaternion right) Returns true if the two instances are exactly equal.
boolean	equalsEpsilon(UnitQuaternion 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(UnitQuaternion 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, 2, and 3 corresponding to the coordinates W (get), X (get), Y (get), and Z (get).
static UnitQuaternion	getIdentity() Gets a set of UnitQuaternion coordinates representing the identity vector.
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.
static UnitQuaternion	getUndefined() Gets a set of UnitQuaternion coordinates with values of Double.NaN.
double	getW() Gets the W coordinate.
double	getX() Gets the X coordinate.
double	getY() Gets the Y coordinate.
double	getZ() Gets the Z coordinate.
int	hashCode() Returns a hash code for this instance, which is suitable for use in hashing algorithms and data structures like a hash table.
boolean	isEquivalent(UnitQuaternion other) Indicates whether another instance of this type is mathematically equivalent to this instance.
boolean	isEquivalent(UnitQuaternion other, double epsilon) Indicates whether another instance of this type is mathematically equivalent to this instance, within the required tolerance.
Quaternion	multiply(double scalar) Multiplies this instance by a scalar.
static Quaternion	multiply(double scalar, UnitQuaternion quaternion) Multiplies a scalar by a specified UnitQuaternion, yielding a new Quaternion.
UnitQuaternion	multiply(ElementaryRotation rotation) Multiplies this instance by the specified ElementaryRotation, yielding a new UnitQuaternion.
UnitQuaternion	multiply(UnitQuaternion quaternion) Multiplies this instance by the specified UnitQuaternion, yielding a new UnitQuaternion.
static Quaternion	multiply(UnitQuaternion quaternion, double scalar) Multiplies a specified UnitQuaternion by a scalar, yielding a new Quaternion.
static UnitQuaternion	multiply(UnitQuaternion quaternion, ElementaryRotation rotation) Multiplies a specified UnitQuaternion by a specified ElementaryRotation, yielding a new UnitQuaternion.
static UnitQuaternion	multiply(UnitQuaternion left, UnitQuaternion right) Multiplies a specified UnitQuaternion by another specified UnitQuaternion, yielding a new UnitQuaternion.
static UnitQuaternion	negate(UnitQuaternion coordinates) Negates the specified UnitQuaternion, yielding a new UnitQuaternion.
static boolean	notEquals(UnitQuaternion left, UnitQuaternion right) Returns true if the two instances are not exactly equal.
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

UnitQuaternion

public UnitQuaternion()

Initializes a new instance.

UnitQuaternion

public UnitQuaternion(double w,
                      double x,
                      double y,
                      double z)

Initializes a set of UnitQuaternion coordinates from the provided values.

The given values will be normalized to ensure a unit magnitude.

Parameters:

w - The W coordinate.

x - The X coordinate.

y - The Y coordinate.

z - The Z coordinate.

Throws:

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

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

UnitQuaternion

public UnitQuaternion(double w,
                      double x,
                      double y,
                      double z,
                      @Nonnull
                      double[] magnitude)

Initializes a set of UnitQuaternion coordinates from the provided values.

The given values will be normalized to ensure a unit magnitude.

Parameters:

w - The W coordinate.

x - The X coordinate.

y - The Y coordinate.

z - The Z coordinate.

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

Throws:

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

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

UnitQuaternion

public UnitQuaternion(@Nonnull
                      Quaternion coordinates)

Initializes a set of UnitQuaternion coordinates from the provided set of Quaternion coordinates.

The given values will be normalized to ensure a unit magnitude.

Parameters:

coordinates - The set of Quaternion coordinates.

Throws:

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

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

UnitQuaternion

public UnitQuaternion(@Nonnull
                      ElementaryRotation rotation)

Initializes a set of UnitQuaternion coordinates from the provided ElementaryRotation.

Parameters:

rotation - The elementary rotation.

Throws:

UnsupportedCaseException - Thrown if the Axis (get) property of rotation is not AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

UnitQuaternion

public UnitQuaternion(@Nonnull
                      AngleAxisRotation rotation)

Initializes a set of UnitQuaternion coordinates from the provided AngleAxisRotation.

Parameters:

rotation - The angle-axis rotation.

UnitQuaternion

public UnitQuaternion(@Nonnull
                      Matrix3By3 matrix)

Initializes a set of UnitQuaternion coordinates from the provided rotation matrix (Matrix3By3). Note that if the given matrix is not an orthogonal rotation matrix, it will create a non-unit UnitQuaternion and could cause problems in code which assumes that the UnitQuaternion represents a rotation.

For performance reasons, there is no check to ensure that the matrix is a unit rotation prior to converting to a unit quaternion. If necessary, the surrounding code is responsible for ensuring that the given matrix is a valid orthogonal rotation matrix. One simple way to ensure a valid UnitQuaternion is to first create a Quaternion from the Matrix3By3 and then Quaternion.normalize() the quaternion to produce a UnitQuaternion.

Parameters:

matrix - The 3-by-3 rotation matrix.

UnitQuaternion

public UnitQuaternion(@Nonnull
                      EulerSequence sequence)

Initializes a set of UnitQuaternion coordinates from the provided EulerSequence.

Parameters:

sequence - The Euler sequence of rotations.

UnitQuaternion

public UnitQuaternion(@Nonnull
                      YawPitchRoll sequence)

Initializes a set of UnitQuaternion coordinates from the provided YawPitchRoll.

Parameters:

sequence - The yaw-pitch-roll sequence of rotations.

UnitQuaternion

public UnitQuaternion(@Nonnull
                      double[] elements)

Initializes a set of UnitQuaternion coordinates from the first 4 consecutive elements in the provided array. Note that the elements will not be normalized and may represent an invalid unit quaternion.

For performance reasons, no checks or normalization procedures are performed when creating a UnitQuaternion from the given elements. The surrounding code is responsible for making sure that the given values represent a unit magnitude. To ensure proper normalization, create a Quaternion and then use the Quaternion.normalize() method to create a valid UnitQuaternion.

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 4 elements.

UnitQuaternion

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

Initializes a set of UnitQuaternion coordinates from 4 consecutive elements in the provided array. Note that the elements will not be normalized and may represent an invalid unit quaternion.

For performance reasons, no checks or normalization procedures are performed when creating a UnitQuaternion from the given elements. The surrounding code is responsible for making sure that the given values represent a unit magnitude. To ensure proper normalization, create a Quaternion and then use the Quaternion.normalize() method to create a valid UnitQuaternion.

Parameters:

elements - The array of coordinate values.

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

Throws:

ArgumentNullException - Thrown when elements is null.

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

Method Detail

getUndefined

@Nonnull
public static UnitQuaternion getUndefined()

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

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

getIdentity

@Nonnull
public static UnitQuaternion getIdentity()

Gets a set of UnitQuaternion coordinates representing the identity vector.

getW

public final double getW()

Gets the W coordinate.

getX

public final double getX()

Gets the X coordinate.

getY

public final double getY()

Gets the Y coordinate.

getZ

public final double getZ()

Gets the Z coordinate.

conjugate

@Nonnull
public final UnitQuaternion conjugate()

Forms the conjugate of this instance.

Returns:

A set of UnitQuaternion coordinates that represents the conjugate of this instance.

multiply

@Nonnull
public final Quaternion 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 Quaternion coordinates that represents the result of the multiplication.

multiply

@Nonnull
public static Quaternion multiply(@Nonnull
                                            UnitQuaternion quaternion,
                                            double scalar)

Multiplies a specified UnitQuaternion by a scalar, yielding a new Quaternion.

Parameters:

quaternion - The unit quaternion.

scalar - The scalar.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static Quaternion multiply(double scalar,
                                            @Nonnull
                                            UnitQuaternion quaternion)

Multiplies a scalar by a specified UnitQuaternion, yielding a new Quaternion.

Parameters:

scalar - The scalar.

quaternion - The unit quaternion.

Returns:

The result of the multiplication.

multiply

@Nonnull
public static UnitQuaternion multiply(@Nonnull
                                                UnitQuaternion quaternion,
                                                @Nonnull
                                                ElementaryRotation rotation)

Multiplies a specified UnitQuaternion by a specified ElementaryRotation, yielding a new UnitQuaternion.

Parameters:

quaternion - The unit quaternion.

rotation - The elementary rotation.

Returns:

The result of the multiplication.

multiply

@Nonnull
public final UnitQuaternion multiply(@Nonnull
                                               UnitQuaternion quaternion)

Multiplies this instance by the specified UnitQuaternion, yielding a new UnitQuaternion.

Parameters:

quaternion - The quaternion by which to multiply this quaternion.

Returns:

The result of the multiplication.

multiply

@Nonnull
public final UnitQuaternion multiply(@Nonnull
                                               ElementaryRotation rotation)

Multiplies this instance by the specified ElementaryRotation, yielding a new UnitQuaternion.

Parameters:

rotation - The rotation by which to multiply this quaternion.

Returns:

The result of the multiplication.

Throws:

UnsupportedCaseException - Thrown if the Axis (get) property of rotation is not AxisIndicator.FIRST, AxisIndicator.SECOND, or AxisIndicator.THIRD.

multiply

@Nonnull
public static UnitQuaternion multiply(@Nonnull
                                                UnitQuaternion left,
                                                @Nonnull
                                                UnitQuaternion right)

Multiplies a specified UnitQuaternion by another specified UnitQuaternion, yielding a new UnitQuaternion.

Parameters:

left - The first unit quaternion.

right - The second unit quaternion.

Returns:

The result of the multiplication.

negate

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

Negates the specified UnitQuaternion, yielding a new UnitQuaternion.

Parameters:

coordinates - The set of coordinates.

Returns:

The result of negating the elements of the original UnitQuaternion.

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, 2, and 3 corresponding to the coordinates W (get), 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
                                UnitQuaternion other)

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

Specified by:

equalsType in interface IEquatable<UnitQuaternion>

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
                                   UnitQuaternion 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<UnitQuaternion>

Parameters:

other - The set of UnitQuaternion 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.

isEquivalent

public final boolean isEquivalent(@Nonnull
                                  UnitQuaternion other)

Indicates whether another instance of this type is mathematically equivalent to this instance. Instances are equivalent if each coordinate value of one instance is equal to the corresponding coordinate value of the other instance, or if each coordinate value of one instance is the opposite of the corresponding coordinate value of the other instance.

Parameters:

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

Returns:

true if they are equivalent; otherwise false.

isEquivalent

public final boolean isEquivalent(@Nonnull
                                  UnitQuaternion other,
                                  double epsilon)

Indicates whether another instance of this type is mathematically equivalent to this instance, within the required tolerance. Instances are equivalent if each coordinate value of one instance is equal to the corresponding coordinate value of the other instance, or if each coordinate value of one instance is the opposite of the corresponding coordinate value of the other instance.

Parameters:

other - The set of UnitQuaternion 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 they are equivalent; 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 "W, X, Y, Z".

equals

public static boolean equals(@Nonnull
                             UnitQuaternion left,
                             @Nonnull
                             UnitQuaternion 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
                                UnitQuaternion left,
                                @Nonnull
                                UnitQuaternion 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.

getIsUndefined

public final boolean getIsUndefined()

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