Quatd (sim-math 1.6.0 API)

java.lang.Object
- com.simsilica.mathd.Quatd

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable
```
public final class Quatd
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
```
Used to efficiently represent rotations and orientations in 3-dimensional space, without risk of gimbal lock. Each instance has 4 double-precision components: 3 imaginary components (X, Y, and Z) and a real component (W).
Methods with names ending in "Local" modify the current instance. They are used to avoid creating temporary objects.
Mathematically, quaternions are an extension of complex numbers. In mathematics texts, W often appears first, but here the conventional order is (X, Y, Z, W).

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type	Field and Description
`double`	`w` The real (W) component.
`double`	`x` The first imaginary (X) component.
`double`	`y` The 2nd imaginary (Y) component.
`double`	`z` The 3rd imaginary (Z) component.

Constructor Summary

Constructors
Constructor and Description
`Quatd()` Instantiates an identity quaternion: all components zeroed except `w`, which is set to 1.
`Quatd(double x, double y, double z, double w)` Instantiates a quaternion with the specified components.
`Quatd(Quatd quat)` Instantiates a copy of the argument.
`Quatd(com.jme3.math.Quaternion quat)` Instantiates based on the specified (single-precision) Quaternion.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Quatd`	`add(Quatd q)` Adds the argument and returns the sum as a new instance.
`Quatd`	`addLocal(Quatd q)` Adds the argument and returns the (modified) current instance.
`Quatd`	`addScaledVectorLocal(Vec3d v, double scale)`
`Quatd`	`clone()` Creates a copy.
`boolean`	`equals(java.lang.Object o)` Tests for exact equality with the argument, distinguishing -0 from 0.
`Quatd`	`fromAngles(double[] angles)` Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll).
`Quatd`	`fromAngles(double xAngle, double yAngle, double zAngle)` Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll).
`double`	`get(int i)` Returns the indexed component.
`int`	`hashCode()` Returns a hash code.
`Quatd`	`inverse()` Returns the multiplicative inverse.
`boolean`	`isRotationIdentity()` Tests for an identity rotation.
`boolean`	`isSimilar(Quatd other, double epsilon)` Returns true if this Quatd is similar to the specified Quatd within some value of epsilon.
`boolean`	`isZero()` Tests for a zero value.
`double`	`lengthSq()` Returns the squared length.
`Quatd`	`mult(Quatd q)` Takes the Hamilton product of the current instance times the argument to yield a new Quatd.
`Quatd`	`mult(Quatd q, Quatd result)` Takes the Hamilton product of the current instance times the first argument and returns the product in the 2nd argument.
`Vec3d`	`mult(Vec3d v)` Rotates the argument vector to produce a new vector.
`Vec3d`	`mult(Vec3d v, Vec3d result)` Rotates a specified vector and return the result in another vector.
`Quatd`	`multLocal(Quatd q)` Takes the Hamilton product of the current instance times the argument, in place.
`Quatd`	`normalizeLocal()` Normalizes the current instance in place.
`Quatd`	`set(double x, double y, double z, double w)` Sets all 4 components to the specified values.
`Quatd`	`set(int i, double d)` Alters the indexed component.
`Quatd`	`set(Quatd q)` Copies all 4 components from the argument.
`Quatd`	`set(com.jme3.math.Quaternion quat)` Copies all 4 components of the specified (single-precision) Quaternion to the current instance.
`Quatd`	`slerpLocal(Quatd start, Quatd end, double mix)` Sets this Quatd's value to the linear interpolation of start and end using the mix value as the amount to interpolate.
`Quatd`	`subtract(Quatd q)` Subtracts the argument and returns the difference as a new instance.
`Quatd`	`subtractLocal(Quatd q)` Subtracts the argument and returns the (modified) current instance.
`double[]`	`toAngles(double[] angles)` Returns this quaternion converted to Euler rotation angles (yaw,roll,pitch).
`com.jme3.math.Quaternion`	`toQuaternion()` Creates a (single-precision) Quaternion that approximates the current instance.
`Matrix3d`	`toRotationMatrix()` Converts the quaternion to an equivalent rotation matrix.
`java.lang.String`	`toString()` Returns a string representation of the quaternion, which is unaffected.

Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - x
```
public double x
```
    The first imaginary (X) component. Not an angle!
  - y
```
public double y
```
    The 2nd imaginary (Y) component. Not an angle!
  - z
```
public double z
```
    The 3rd imaginary (Z) component. Not an angle!
  - w
```
public double w
```
    The real (W) component. Not an angle!
- Constructor Detail
  - Quatd
```
public Quatd()
```
    Instantiates an identity quaternion: all components zeroed except w, which is set to 1.
  - Quatd
```
public Quatd(double x,
             double y,
             double z,
             double w)
```
    Instantiates a quaternion with the specified components.
    
    Parameters:
    
    x - the desired X component
    
    y - the desired Y component
    
    z - the desired Z component
    
    w - the desired W component
  - Quatd
```
public Quatd(Quatd quat)
```
    Instantiates a copy of the argument.
    
    Parameters:
    
    quat - the quaternion to copy (not null, unaffected)
  - Quatd
```
public Quatd(com.jme3.math.Quaternion quat)
```
    Instantiates based on the specified (single-precision) Quaternion.
    
    Parameters:
    
    quat - the input Quaternion (not null, unaffected)
- Method Detail
  - clone
```
public final Quatd clone()
```
    Creates a copy. The current instance is unaffected.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    
    a new instance, equivalent to this one
  - toQuaternion
```
public com.jme3.math.Quaternion toQuaternion()
```
    Creates a (single-precision) Quaternion that approximates the current instance.
    
    Returns:
    
    a new Quaternion
  - hashCode
```
public int hashCode()
```
    Returns a hash code. If two quaternions have identical values, they will have the same hash code. The current instance is unaffected.
    
    Overrides:
    
    hashCode in class java.lang.Object
    
    Returns:
    
    a 32-bit value for use in hashing
  - equals
```
public boolean equals(java.lang.Object o)
```
    Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.
    
    Overrides:
    
    equals in class java.lang.Object
    
    Parameters:
    
    o - the object to compare (may be null, unaffected)
    
    Returns:
    
    true if this and o have identical values, otherwise false
  - isSimilar
```
public boolean isSimilar(Quatd other,
                         double epsilon)
```
    Returns true if this Quatd is similar to the specified Quatd within some value of epsilon.
    
    Parameters:
    
    other - the Quatd to compare (may be null, unaffected)
    
    epsilon - the tolerance for comparison
    
    Returns:
    
    true if all components are sufficiently similar, otherwise false
  - isRotationIdentity
```
public boolean isRotationIdentity()
```
    Tests for an identity rotation. The quaternion is unaffected.
    
    Returns:
    
    true if W is non-zero and not NaN and X, Y, and Z are all 0 or -0, otherwise false
  - isZero
```
public boolean isZero()
```
    Tests for a zero value. The quaternion is unaffected.
    
    Returns:
    
    true if all components are 0 or -0, otherwise false
  - set
```
public final Quatd set(double x,
                       double y,
                       double z,
                       double w)
```
    Sets all 4 components to the specified values.
    
    Parameters:
    
    x - the desired X component
    
    y - the desired Y component
    
    z - the desired Z component
    
    w - the desired W component
    
    Returns:
    
    the (modified) current instance (for chaining)
  - set
```
public final Quatd set(Quatd q)
```
    Copies all 4 components from the argument.
    
    Parameters:
    
    q - the quaternion to copy (not null, unaffected)
    
    Returns:
    
    the (modified) current instance (for chaining)
  - set
```
public final Quatd set(com.jme3.math.Quaternion quat)
```
    Copies all 4 components of the specified (single-precision) Quaternion to the current instance.
    
    Parameters:
    
    quat - the input Quaternion (not null, unaffected)
    
    Returns:
    
    the (modified) current instance (for chaining)
  - get
```
public double get(int i)
```
    Returns the indexed component. The quaternion is unaffected.
    
    Parameters:
    
    i - 0, 1, 2, or 3
    
    Returns:
    
    the X component if i=0, the Y component if i=1, the Z component if i=2, or the W component if i=3
    
    Throws:
    
    java.lang.IndexOutOfBoundsException - if i is not 0, 1, 2, or 3
  - set
```
public Quatd set(int i,
                 double d)
```
    Alters the indexed component.
    
    Parameters:
    
    i - which component to set: 0 → the X component, 1 → the Y component, 2 → the Z component, 3 → the W component
    
    d - the desired component value
    
    Returns:
    
    the (modified) current instance (for chaining)
    
    Throws:
    
    java.lang.IllegalArgumentException - if i is not 0, 1, 2, or 3
  - add
```
public final Quatd add(Quatd q)
```
    Adds the argument and returns the sum as a new instance. The current instance is unaffected.
    
    Parameters:
    
    q - the Quatd to add (not null, unaffected)
    
    Returns:
    
    a new Quatd
  - addLocal
```
public final Quatd addLocal(Quatd q)
```
    Adds the argument and returns the (modified) current instance.
    It IS safe for q and this to be the same object.
    
    Parameters:
    
    q - the Quatd to add (not null, unaffected unless it's this)
    
    Returns:
    
    the (modified) current instance (for chaining)
  - subtract
```
public final Quatd subtract(Quatd q)
```
    Subtracts the argument and returns the difference as a new instance. The current instance is unaffected.
    
    Parameters:
    
    q - the Quatd to subtract (not null, unaffected)
    
    Returns:
    
    a new Quatd
  - subtractLocal
```
public final Quatd subtractLocal(Quatd q)
```
    Subtracts the argument and returns the (modified) current instance.
    It IS safe for q and this to be the same object.
    
    Parameters:
    
    q - the Quatd to subtract (not null, unaffected unless it's this)
    
    Returns:
    
    the (modified) current instance (for chaining)
  - addScaledVectorLocal
```
public final Quatd addScaledVectorLocal(Vec3d v,
                                        double scale)
```
  - mult
```
public final Quatd mult(Quatd q)
```
    Takes the Hamilton product of the current instance times the argument to yield a new Quatd. The current instance is unaffected.
    It is safe for q and this to be the same object.
    This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.
    
    Parameters:
    
    q - the right factor (not null, unaffected)
    
    Returns:
    
    this * q (a new instance)
  - mult
```
public final Quatd mult(Quatd q,
                        Quatd result)
```
    Takes the Hamilton product of the current instance times the first argument and returns the product in the 2nd argument. The current instance is unaffected, unless it's result.
    This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.
    It is safe for any or all of q, result, and this to be the same object.
    
    Parameters:
    
    q - the right factor (not null, unaffected unless it's result)
    
    result - storage for the product, or null for a new Quatd
    
    Returns:
    
    this * q (either result or a new Quatd)
  - multLocal
```
public final Quatd multLocal(Quatd q)
```
    Takes the Hamilton product of the current instance times the argument, in place.
    This method is used to combine rotations. Note that the Hamilton product is noncommutative, so generally q * p != p * q.
    It IS safe for q and this to be the same object.
    
    Parameters:
    
    q - the right factor (not null, unaffected unless it's this)
    
    Returns:
    
    the (modified) current instance (for chaining)
  - mult
```
public Vec3d mult(Vec3d v)
```
    Rotates the argument vector to produce a new vector. The quaternion is unaffected.
    
    Parameters:
    
    v - the input vector (not null, unaffected)
    
    Returns:
    
    a new instance
  - mult
```
public Vec3d mult(Vec3d v,
                  Vec3d result)
```
    Rotates a specified vector and return the result in another vector. The quaternion is unaffected.
    It IS safe for v and result to be the same object.
    
    Parameters:
    
    v - the vector to rotate (not null, unaffected unless it's result)
    
    result - storage for the result (not null)
    
    Returns:
    
    the (rotated) vector result
  - lengthSq
```
public final double lengthSq()
```
    Returns the squared length.
    
    Returns:
    
    the squared length (≥0)
  - normalizeLocal
```
public final Quatd normalizeLocal()
```
    Normalizes the current instance in place.
    
    Returns:
    
    the (modified) current instance (for chaining)
  - toRotationMatrix
```
public Matrix3d toRotationMatrix()
```
    Converts the quaternion to an equivalent rotation matrix. The quaternion is unaffected.
    Note: the result is created from a normalized version of the current instance.
    
    Returns:
    
    a new 3x3 rotation matrix
  - inverse
```
public Quatd inverse()
```
    Returns the multiplicative inverse. For a quaternion with norm=0, null is returned. Either way, the current instance is unaffected.
    
    Returns:
    
    a new instance, or null if not invertible
  - fromAngles
```
public Quatd fromAngles(double[] angles)
```
    Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll). They are applied in order: (y, z, x) aka (yaw, roll, pitch).
    
    Parameters:
    
    angles - the rotation angles for each axis (in radians, not null, length ≥3)
    
    Returns:
    
    the (modified) current instance (for chaining)
    
    See Also:
    
    http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm
  - fromAngles
```
public Quatd fromAngles(double xAngle,
                        double yAngle,
                        double zAngle)
```
    Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll). They are applied in order: (y, z, x) aka (yaw, roll, pitch).
    
    Parameters:
    
    xAngle - the desired rotation about the +X axis (in radians)
    
    yAngle - the desired rotation about the +Y axis (in radians)
    
    zAngle - the desired rotation about the +Z axis (in radians)
    
    Returns:
    
    the (modified) current instance (for chaining)
    
    See Also:
    
    http://www.euclideanspace.com/maths/geometry/rotations/conversions/eulerToQuaternion/index.htm
  - toAngles
```
public double[] toAngles(double[] angles)
```
    Returns this quaternion converted to Euler rotation angles (yaw,roll,pitch). Note that the result is not always 100% accurate due to the implications of euler angles.
    
    Parameters:
    
    angles - the double[] in which the angles should be stored, or null if you want a new double[] to be created
    
    Returns:
    
    the double[] in which the angles are stored.
    
    See Also:
    
    http://www.euclideanspace.com/maths/geometry/rotations/conversions/quaternionToEuler/index.htm
  - slerpLocal
```
public Quatd slerpLocal(Quatd start,
                        Quatd end,
                        double mix)
```
    Sets this Quatd's value to the linear interpolation of start and end using the mix value as the amount to interpolate.
    
    Parameters:
    
    start - the desired value when mix is zero (not null, unaffected unless it's this)
    
    end - the desired value when mix is one (not null, unaffected unless it's this)
    
    mix - typically between 0 and 1 inclusive
    
    Returns:
    
    the (modified) current instance (for chaining)
  - toString
```
public java.lang.String toString()
```
    Returns a string representation of the quaternion, which is unaffected. For example, the identity quaternion is represented by:
```
 Quatd[0.0, 0.0, 0.0, 1.0]
 
```
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    the string representation (not null, not empty)

Class Quatd

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

x

y

z

w

Constructor Detail

Quatd

Quatd

Quatd

Quatd

Method Detail

clone

toQuaternion

hashCode

equals

isSimilar

isRotationIdentity

isZero

set

set

set

get

set

add

addLocal

subtract

subtractLocal

addScaledVectorLocal

mult

mult

multLocal

mult

mult

lengthSq

normalizeLocal

toRotationMatrix

inverse

fromAngles

fromAngles

toAngles

slerpLocal

toString