Quaternion

java.lang.Object
- agi.foundation.coordinates.Quaternion

All Implemented Interfaces:

IEquatable<Quaternion>, ImmutableValueType, ValueType, IEquatableEpsilon<Quaternion>
```
public final class Quaternion
extends Object
implements IEquatable<Quaternion>, IEquatableEpsilon<Quaternion>, ImmutableValueType
```
A set of 4-dimensional coordinates used to represent rotation in 3-dimensional space. In general, UnitQuaternion is used to represent rotations. This type is available for completeness, providing quaternion operations on non-normalized quaternions.
For more information on how quaternions and other coordinates are used to represent rotations, see the Coordinates topic.

See Also:

AngleAxisRotation, ElementaryRotation, EulerSequence, Matrix3By3, UnitQuaternion, YawPitchRoll

Constructor Summary

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

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Quaternion`	`conjugate()` Forms the conjugate of this instance, yielding a new `Quaternion`.
`boolean`	`equals(Object obj)` Indicates whether another object is exactly equal to this instance.
`static boolean`	`equals(Quaternion left, Quaternion right)` Returns `true` if the two instances are exactly equal.
`boolean`	`equalsEpsilon(Quaternion 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(Quaternion 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`).
`boolean`	`getHasZeroNorm()` Gets a value indicating whether the `Norm` (`get`) of this instance is zero.
`static Quaternion`	`getIdentity()` Gets the set of `Quaternion` 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.
`double`	`getNorm()` Gets the norm of this instance.
`double`	`getNormSquared()` Gets the square of the `Norm` (`get`) of this instance.
`static Quaternion`	`getUndefined()` Gets a set of `Quaternion` 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.
`static Quaternion`	`getZero()` Gets a set of `Quaternion` 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.
`Quaternion`	`multiply(double scalar)` Multiplies this instance by a scalar, yielding a new `Quaternion`.
`static Quaternion`	`multiply(double scalar, Quaternion quaternion)` Multiplies a scalar by a specified `Quaternion`, yielding a new `Quaternion`.
`Quaternion`	`multiply(ElementaryRotation rotation)` Multiplies this instance by the specified `ElementaryRotation`, yielding a new `Quaternion`.
`Quaternion`	`multiply(Quaternion quaternion)` Multiplies this instance by the specified `Quaternion`, yielding a new `Quaternion`.
`static Quaternion`	`multiply(Quaternion quaternion, double scalar)` Multiplies a specified `Quaternion` by a scalar, yielding a new `Quaternion`.
`static Quaternion`	`multiply(Quaternion quaternion, ElementaryRotation rotation)` Multiplies a specified `Quaternion` by a specified `ElementaryRotation`, yielding a new `Quaternion`.
`static Quaternion`	`multiply(Quaternion left, Quaternion right)` Multiplies a specified `Quaternion` by another specified `Quaternion`, yielding a new `Quaternion`.
`static Quaternion`	`negate(Quaternion coordinates)` Negates the specified `Quaternion`, yielding a new `Quaternion`.
`UnitQuaternion`	`normalize()` Forms a set of `UnitQuaternion` coordinates from this instance.
`UnitQuaternion`	`normalize(double[] magnitude)` Forms a set of `UnitQuaternion` coordinates from this instance and returns the magnitude of the original instance in the provided parameter.
`static boolean`	`notEquals(Quaternion left, Quaternion right)` Returns `true` if the two instances are not exactly equal.
`static Quaternion`	`toQuaternion(UnitQuaternion coordinates)` Converts a set of `UnitQuaternion` coordinates to a set of `Quaternion` 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
  - Quaternion
```
public Quaternion()
```
    Initializes a new instance.
  - Quaternion
```
public Quaternion(double w,
                  double x,
                  double y,
                  double z)
```
    Initializes a set of Quaternion coordinates from the provided values.
    
    Parameters:
    
    w - The W coordinate.
    
    x - The X coordinate.
    
    y - The Y coordinate.
    
    z - The Z coordinate.
  - Quaternion
```
public Quaternion(@Nonnull
                  EulerSequence sequence)
```
    Initializes a set of Quaternion coordinates from the provided EulerSequence.
    
    Parameters:
    
    sequence - The Euler sequence of rotations.
  - Quaternion
```
public Quaternion(@Nonnull
                  YawPitchRoll sequence)
```
    Initializes a set of Quaternion coordinates from the provided YawPitchRoll.
    
    Parameters:
    
    sequence - The yaw-pitch-roll sequence of rotations.
  - Quaternion
```
public Quaternion(@Nonnull
                  ElementaryRotation rotation)
```
    Initializes a set of Quaternion 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.
  - Quaternion
```
public Quaternion(@Nonnull
                  AngleAxisRotation rotation)
```
    Initializes a set of Quaternion coordinates from the provided AngleAxisRotation.
    
    Parameters:
    
    rotation - The angle-axis rotation.
  - Quaternion
```
public Quaternion(@Nonnull
                  Matrix3By3 matrix)
```
    Initializes a set of Quaternion coordinates from the provided Matrix3By3.
    
    Parameters:
    
    matrix - The 3-by-3 rotation matrix.
  - Quaternion
```
public Quaternion(@Nonnull
                  double[] elements)
```
    Initializes a set of Quaternion coordinates from the first 4 consecutive elements in the provided array.
    
    Parameters:
    
    elements - The array of coordinate values.
    
    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.
  - Quaternion
```
public Quaternion(@Nonnull
                  double[] elements,
                  int startIndex)
```
    Initializes a set of Quaternion coordinates from 4 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 elements is null.
    
    ArgumentOutOfRangeException - Thrown when an object of this type is constructed from an array with less than 4 elements.
- Method Detail
  - getZero
```
@Nonnull
public static Quaternion getZero()
```
    Gets a set of Quaternion coordinates with values of zero.
  - getUndefined
```
@Nonnull
public static Quaternion getUndefined()
```
    Gets a set of Quaternion coordinates with values of Double.NaN.
    Use IsUndefined (get) to test whether a Quaternion instance is undefined since it will return true if any of the coordinate values are Double.NaN.
  - getIdentity
```
@Nonnull
public static Quaternion getIdentity()
```
    Gets the set of Quaternion 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 Quaternion conjugate()
```
    Forms the conjugate of this instance, yielding a new Quaternion.
    
    Returns:
    
    The new quaternion.
  - multiply
```
@Nonnull
public final Quaternion multiply(double scalar)
```
    Multiplies this instance by a scalar, yielding a new Quaternion.
    
    Parameters:
    
    scalar - The scalar.
    
    Returns:
    
    The result of the multiplication.
  - multiply
```
@Nonnull
public final Quaternion multiply(@Nonnull
                                           Quaternion quaternion)
```
    Multiplies this instance by the specified Quaternion, yielding a new Quaternion.
    
    Parameters:
    
    quaternion - The quaternion.
    
    Returns:
    
    The result of the multiplication.
  - multiply
```
@Nonnull
public final Quaternion multiply(@Nonnull
                                           ElementaryRotation rotation)
```
    Multiplies this instance by the specified ElementaryRotation, yielding a new Quaternion.
    
    Parameters:
    
    rotation - The elementary rotation.
    
    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 Quaternion multiply(@Nonnull
                                            Quaternion quaternion,
                                            double scalar)
```
    Multiplies a specified Quaternion by a scalar, yielding a new Quaternion.
    
    Parameters:
    
    quaternion - The quaternion.
    
    scalar - The scalar.
    
    Returns:
    
    The result of the multiplication.
  - multiply
```
@Nonnull
public static Quaternion multiply(double scalar,
                                            @Nonnull
                                            Quaternion quaternion)
```
    Multiplies a scalar by a specified Quaternion, yielding a new Quaternion.
    
    Parameters:
    
    scalar - The scalar.
    
    quaternion - The quaternion.
    
    Returns:
    
    The result of the multiplication.
  - multiply
```
@Nonnull
public static Quaternion multiply(@Nonnull
                                            Quaternion quaternion,
                                            @Nonnull
                                            ElementaryRotation rotation)
```
    Multiplies a specified Quaternion by a specified ElementaryRotation, yielding a new Quaternion.
    
    Parameters:
    
    quaternion - The quaternion.
    
    rotation - The elementary rotation.
    
    Returns:
    
    The result of the multiplication.
  - multiply
```
@Nonnull
public static Quaternion multiply(@Nonnull
                                            Quaternion left,
                                            @Nonnull
                                            Quaternion right)
```
    Multiplies a specified Quaternion by another specified Quaternion, yielding a new Quaternion.
    
    Parameters:
    
    left - The first quaternion.
    
    right - The second quaternion.
    
    Returns:
    
    The result of the multiplication.
  - negate
```
@Nonnull
public static Quaternion negate(@Nonnull
                                          Quaternion coordinates)
```
    Negates the specified Quaternion, yielding a new Quaternion.
    
    Parameters:
    
    coordinates - The set of coordinates.
    
    Returns:
    
    The result of negating the elements of the original Quaternion.
  - 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
                                Quaternion other)
```
    Indicates whether another instance of this type is exactly equal to this instance.
    
    Specified by:
    
    equalsType in interface IEquatable<Quaternion>
    
    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
                                   Quaternion 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<Quaternion>
    
    Parameters:
    
    other - The set of Quaternion 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 "W, X, Y, Z".
  - equals
```
public static boolean equals(@Nonnull
                             Quaternion left,
                             @Nonnull
                             Quaternion 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
                                Quaternion left,
                                @Nonnull
                                Quaternion 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.
  - getNorm
```
public final double getNorm()
```
    Gets the norm of this instance.
  - getNormSquared
```
public final double getNormSquared()
```
    Gets the square of the Norm (get) of this instance.
  - getHasZeroNorm
```
public final boolean getHasZeroNorm()
```
    Gets a value indicating whether the Norm (get) of this instance is zero.
  - getIsUndefined
```
public final boolean getIsUndefined()
```
    Gets a value indicating whether or not any of the coordinates for this instance have the value Double.NaN.
  - toQuaternion
```
@Nonnull
public static Quaternion toQuaternion(@Nonnull
                                                UnitQuaternion coordinates)
```
    Converts a set of UnitQuaternion coordinates to a set of Quaternion coordinates.
    
    Parameters:
    
    coordinates - The set of UnitQuaternion coordinates.
    
    Returns:
    
    The resulting set of Quaternion coordinates.
  - normalize
```
@Nonnull
public final UnitQuaternion normalize()
```
    Forms a set of UnitQuaternion coordinates from this instance.
    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.
    
    Returns:
    
    The resulting set of UnitQuaternion 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 UnitQuaternion normalize(@Nonnull
                                                double[] magnitude)
```
    Forms a set of UnitQuaternion coordinates from this instance and returns the magnitude of the original instance in the provided parameter.
    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.
    
    Parameters:
    
    magnitude - On input, an array with one element. On return, the array is populated with the magnitude of the original set of Quaternion coordinates.
    
    Returns:
    
    The resulting set of UnitQuaternion coordinates.
    
    Throws:
    
    ArithmeticException - The magnitude of the provided coordinates must not be zero.
    
    NotFiniteNumberException - The magnitude of the provided coordinates must not be infinite.

Class Quaternion

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Quaternion

Quaternion

Quaternion

Quaternion

Quaternion

Quaternion

Quaternion

Quaternion

Method Detail

getZero

getUndefined

getIdentity

getW

getX

getY

getZ

conjugate

multiply

multiply

multiply

multiply

multiply

multiply

multiply

negate

getLength

get

equals

equalsType

equalsEpsilon

hashCode

toString

equals

notEquals

getNorm

getNormSquared

getHasZeroNorm

getIsUndefined

toQuaternion

normalize

normalize