Quatd (Libbulletjme API)

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

All Implemented Interfaces:

java.lang.Cloneable
```
public final class Quatd
extends java.lang.Object
implements java.lang.Cloneable
```
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).

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(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`	`clone()` Creates a copy.
`boolean`	`equals(java.lang.Object o)` Tests for exact equality with the argument, distinguishing -0 from 0.
`Quatd`	`fromAngles(double xAngle, double yAngle, double zAngle)` Builds a Quaternion from the Euler rotation angles (x,y,z) aka (pitch, yaw, roll).
`int`	`hashCode()` Returns a hash code.
`Quatd`	`inverse()` Returns the multiplicative inverse.
`boolean`	`isRotationIdentity()` Tests for an identity rotation.
`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(Quatd q)` Copies all 4 components from the argument.
`Quatd`	`set(Quaternion quat)` Copies all 4 components of the specified (single-precision) Quaternion to the current instance.
`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(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 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
  - 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(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)
  - 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 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
  - 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

isRotationIdentity

isZero

set

set

set

mult

mult

multLocal

mult

mult

lengthSq

normalizeLocal

toRotationMatrix

inverse

fromAngles

toString