Package com.github.stephengold.joltjni

Class Quat

java.lang.Object
com.github.stephengold.joltjni.Quat
All Implemented Interfaces:
QuatArg
public final class Quat extends Object implements QuatArg
A math object used to represent rotations and orientations in 3-dimensional space, without risk of gimbal lock. Each quaternion has 4 single-precision components: 3 imaginary ones (X, Y, and Z) and a real one (W).

Mathematically speaking, quaternions are an extension of complex numbers.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Quat()
    Instantiate an identity quaternion (0,0,0,1).
    Quat(float x, float y, float z, float w)
    Instantiate a quaternion with specified components.
    Quat(Vec3Arg v, float w)
    Instantiate a quaternion based on a Vec3Arg.

  • Method Summary

    Modifier and Type
    Method
    Description
    Quat
    conjugated()
    Return the conjugate.
    float
    getW()
    Return the real (W) component in single precision.
    float
    getX()
    Return the first imaginary (X) component in single precision.
    float
    getY()
    Return the 2nd imaginary (Y) component in single precision.
    float
    getZ()
    Return the 3rd imaginary (Z) component in single precision.
    boolean
    isNormalized()
    Test whether the quaternion is normalized to within a tolerance of 10^-5.
    boolean
    isNormalized(float tolerance)
    Test whether the quaternion is normalized to within the specified tolerance.
    float
    length()
    Return the length.
    float
    lengthSq()
    Return the squared length.
    Quat
    normalized()
    Generate a normalized quaternion that represents the same rotation.
    void
    set(float x, float y, float z, float w)
    Set all 4 components to specified values.
    static Quat
    sFromTo(Vec3Arg from, Vec3Arg to)
    Create a rotation quaternion that rotates from to to.
    static Quat
    sIdentity()
    Create an identity quaternion (0,0,0,1).
    static Quat
    sRandom(DefaultRandomEngine engine)
    Generate a pseudo-random unit quaternion.
    static Quat
    sRotation(Vec3 axis, float angle)
    Create a rotation quaternion from a normalized rotation axis.
    String
    toString()
    Return a string representation of the quaternion, which is unaffected.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Quat

      public Quat()
      Instantiate an identity quaternion (0,0,0,1).

    • Quat

      public Quat(float x, float y, float z, float w)
      Instantiate a quaternion with specified components.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component

    • Quat

      public Quat(Vec3Arg v, float w)
      Instantiate a quaternion based on a Vec3Arg.
      Parameters:
      v - the desired XYZ components
      w - the desired W component

  • Method Details

    • set

      public void set(float x, float y, float z, float w)
      Set all 4 components to specified values.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component
      w - the desired W component

    • sFromTo

      public static Quat sFromTo(Vec3Arg from, Vec3Arg to)
      Create a rotation quaternion that rotates from to to.
      Parameters:
      from - the first direction vector (not null, unaffected)
      to - the 2nd direction vector (not null, unaffected)
      Returns:
      a new quaternion

    • sIdentity

      public static Quat sIdentity()
      Create an identity quaternion (0,0,0,1).
      Returns:
      a new quaternion

    • sRandom

      public static Quat sRandom(DefaultRandomEngine engine)
      Generate a pseudo-random unit quaternion.
      Parameters:
      engine - the generator to use (not null)
      Returns:
      a new unit quaternion

    • sRotation

      public static Quat sRotation(Vec3 axis, float angle)
      Create a rotation quaternion from a normalized rotation axis.
      Parameters:
      axis - the desired rotation axis (not null, normalized)
      angle - the desired rotation angle (in radians)
      Returns:
      a new quaternion

    • conjugated

      public Quat conjugated()
      Return the conjugate. The current object is unaffected.
      Specified by:
      conjugated in interface QuatArg
      Returns:
      a new object

    • getW

      public float getW()
      Return the real (W) component in single precision. The quaternion is unaffected.
      Specified by:
      getW in interface QuatArg
      Returns:
      the component value

    • getX

      public float getX()
      Return the first imaginary (X) component in single precision. The quaternion is unaffected.
      Specified by:
      getX in interface QuatArg
      Returns:
      the component value

    • getY

      public float getY()
      Return the 2nd imaginary (Y) component in single precision. The quaternion is unaffected.
      Specified by:
      getY in interface QuatArg
      Returns:
      the component value

    • getZ

      public float getZ()
      Return the 3rd imaginary (Z) component in single precision. The quaternion is unaffected.
      Specified by:
      getZ in interface QuatArg
      Returns:
      the component value

    • isNormalized

      public boolean isNormalized()
      Test whether the quaternion is normalized to within a tolerance of 10^-5. The quaternion is unaffected.
      Specified by:
      isNormalized in interface QuatArg
      Returns:
      true if normalized, otherwise false

    • isNormalized

      public boolean isNormalized(float tolerance)
      Test whether the quaternion is normalized to within the specified tolerance. The quaternion is unaffected.
      Specified by:
      isNormalized in interface QuatArg
      Parameters:
      tolerance - the desired tolerance (default=1e-5)
      Returns:
      true if normalized, otherwise false

    • length

      public float length()
      Return the length. The quaternion is unaffected.
      Specified by:
      length in interface QuatArg
      Returns:
      the length

    • lengthSq

      public float lengthSq()
      Return the squared length. The quaternion is unaffected.
      Specified by:
      lengthSq in interface QuatArg
      Returns:
      the squared length

    • normalized

      public Quat normalized()
      Generate a normalized quaternion that represents the same rotation. The current object is unaffected.
      Specified by:
      normalized in interface QuatArg
      Returns:
      a new quaternion

    • toString

      public String toString()
      Return a string representation of the quaternion, which is unaffected. For example, an identity quaternion is represented by: 
       Quat(0.0 0.0 0.0 1.0)
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)