Class Quaternion


  • public class Quaternion
    extends Object
    A 4 element unit quaternion represented by single precision floating point x,y,z,w coordinates. This class API aims to conform that of the great libQGLViewer Quaternion.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      float[] _quaternion
      The x, y, z, and w coordinates of the quaternion represented as a public array.
      static Quaternion identity
      Returns a quaternion whose components are set to (0, 0, 0, 1).
    • Constructor Summary

      Constructors 
      Constructor Description
      Quaternion()
      Constructs and initializes a quaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.
      Quaternion​(float angle)
      Same as fromAxisAngle(new Vector(0,0,1), angle).
      Quaternion​(float[] source)
      Convenience constructor that simply calls this(source, true)
      Quaternion​(float[] source, boolean normalize)
      Constructs and initializes a quaternion from the array of length 4.
      Quaternion​(float roll, float pitch, float yaw)
      Constructs a quaternion from the given Euler angles.
      Quaternion​(float x, float y, float z, float w)
      Default constructor for Quaternion(float x, float y, float z, float w, boolean normalize), with normalize=true.
      Quaternion​(float x, float y, float z, float w, boolean normalize)
      Constructs and initializes a quaternion from the specified xyzw coordinates.
      Quaternion​(Matrix matrix)
      Constructs a quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.
      Quaternion​(Quaternion quaternion, boolean normalize)
      Copy constructor.
      Quaternion​(Vector axis, float angle)
      Constructs and initializes a quaternion from the specified rotation axis (non null) and angle (in radians).
      Quaternion​(Vector from, Vector to)
      Constructs a quaternion that will rotate from the from direction to the to direction.
      Quaternion​(Vector X, Vector Y, Vector Z)
      Constructs a quaternion from the three rotated vectors of an orthogonal basis.
    • Field Detail

      • _quaternion

        public float[] _quaternion
        The x, y, z, and w coordinates of the quaternion represented as a public array.
      • identity

        public static final Quaternion identity
        Returns a quaternion whose components are set to (0, 0, 0, 1).
        See Also:
        from(Object...)
    • Constructor Detail

      • Quaternion

        public Quaternion()
        Constructs and initializes a quaternion to (0.0,0.0,0.0,1.0), i.e., an identity rotation.
      • Quaternion

        public Quaternion​(float x,
                          float y,
                          float z,
                          float w)
        Default constructor for Quaternion(float x, float y, float z, float w, boolean normalize), with normalize=true.
      • Quaternion

        public Quaternion​(float x,
                          float y,
                          float z,
                          float w,
                          boolean normalize)
        Constructs and initializes a quaternion from the specified xyzw coordinates.
        Parameters:
        x - the x coordinate
        y - the y coordinate
        z - the z coordinate
        w - the w scalar component
        normalize - tells whether or not the constructed Quaternion should be normalized.
      • Quaternion

        public Quaternion​(float[] source)
        Convenience constructor that simply calls this(source, true)
      • Quaternion

        public Quaternion​(float[] source,
                          boolean normalize)
        Constructs and initializes a quaternion from the array of length 4.
        Parameters:
        source - the array of length 4 containing xyzw in order
      • Quaternion

        public Quaternion​(Quaternion quaternion,
                          boolean normalize)
        Copy constructor. If normalize is true this quaternion is normalize().
        Parameters:
        quaternion - the Quaternion containing the initialization x y z w data
      • Quaternion

        public Quaternion​(float angle)
        Same as fromAxisAngle(new Vector(0,0,1), angle).

        Constructs and initializes a quaternion from the specified 2d rotation angle (in radians). The axis of the quaternion is Z.

        Parameters:
        angle - the angle in radians
        See Also:
        fromAxisAngle(Vector, float)
      • Quaternion

        public Quaternion​(Vector axis,
                          float angle)
        Constructs and initializes a quaternion from the specified rotation axis (non null) and angle (in radians).
        Parameters:
        axis - the Vector representing the axis
        angle - the angle in radians
        See Also:
        fromAxisAngle(Vector, float)
      • Quaternion

        public Quaternion​(Vector from,
                          Vector to)
        Constructs a quaternion that will rotate from the from direction to the to direction.
        Parameters:
        from - the first Vector
        to - the second Vector
        See Also:
        fromTo(Vector, Vector)
      • Quaternion

        public Quaternion​(float roll,
                          float pitch,
                          float yaw)
        Constructs a quaternion from the given Euler angles.
        Parameters:
        roll - Rotation angle in radians around the x-Axis
        pitch - Rotation angle in radians around the y-Axis
        yaw - Rotation angle in radians around the z-Axis
        See Also:
        fromEulerAngles(float, float, float)
      • Quaternion

        public Quaternion​(Matrix matrix)
        Constructs a quaternion from a (supposedly correct) 3x3 rotation matrix given in the upper left 3x3 sub-matrix of the Matrix.
        Parameters:
        matrix -
        See Also:
        fromMatrix(Matrix)
    • Method Detail

      • matches

        public boolean matches​(Quaternion quaternion)
        Returns whether or not this quaternion matches other.
        Parameters:
        quaternion - other quaternion
      • copy

        public Quaternion copy()
        Returns a deep copy of this quaternion.
      • randomize

        public void randomize()
        Randomize this quaternion. The quaternion is normalized too.
        See Also:
        random()
      • random

        public static Quaternion random()
        Returns a normalized random quaternion.
        See Also:
        randomize()
      • reset

        public void reset()
        Make this an identity quaternion.
      • get

        public float[] get​(float[] target)
        Returns a copy of this quaternion into the four length target array.
      • set

        public void set​(float[] source)
        Sets this quaternion from the four length source array.
      • x

        public float x()
        Returns:
        Quaternion x component
      • y

        public float y()
        Returns:
        Quaternion y component
      • z

        public float z()
        Returns:
        Quaternion z component
      • w

        public float w()
        Returns:
        Quaternion w component
      • setX

        public void setX​(float x)
        Sets the Quaternion x component
      • setY

        public void setY​(float y)
        Sets the Quaternion y component
      • setZ

        public void setZ​(float z)
        Sets the Quaternion z component
      • setW

        public void setW​(float w)
        Sets the Quaternion w component
      • set

        public void set​(Quaternion quaternion,
                        boolean normalize)
        Set this from quaternion quaternion. If normalize is true this Quaternion is normalize().
      • conjugate

        public void conjugate()
        Sets this as its conjugate.
      • conjugate

        public void conjugate​(Quaternion quaternion)
        Sets this as the quaternion conjugate.
        Parameters:
        quaternion - the source vector
      • negate

        public void negate()
        Negates all the coefficients of the quaternion.
      • dotProduct

        public float dotProduct​(Quaternion quaternion)
        Returns the "dot" product of this quaternion and quaternion:

        this._quaternion[0] * quaternion._quaternion[0] + this._quaternion[1] * quaternion._quaternion[1] + this._quaternion[2] * quaternion._quaternion[2] + this._quaternion[3] * quaternion._quaternion[3]

        Parameters:
        quaternion - the Quaternion
      • dot

        public static float dot​(Quaternion a,
                                Quaternion b)
        Returns the "dot" product of a and b:

        a.x * b.x + a.y * b.y + a.z * b.z + a.w * b.w

        Parameters:
        a - the first Quaternion
        b - the second Quaternion
      • multiply

        public void multiply​(Quaternion quaternion)
        Sets this as the quaternion product of itself and quaternion, (i.e., this = this * quaternion).
        Parameters:
        quaternion - the other Quaternion
      • multiply

        public static Quaternion multiply​(Quaternion a,
                                          Quaternion b)
        Returns the product of quaternions a and b.
        Parameters:
        a - the first Quaternion
        b - the second Quaternion
      • multiplyInverse

        public void multiplyInverse​(Quaternion q1)
        Multiplies this by the inverse of Quaternion q1 and places the value into this (i.e., this = this * q^-1). The value of the argument quaternion is preserved.
        Parameters:
        q1 - the other Quaternion
      • multiplyInverse

        public static Quaternion multiplyInverse​(Quaternion q1,
                                                 Quaternion q2)
        Returns the product of quaternion q1 by the inverse of quaternion q2 (i.e., q1 * q2^-1). The value of both argument quaternions is preserved.
        Parameters:
        q1 - the first Quaternion
        q2 - the second Quaternion
      • inverse

        public Quaternion inverse()
        Returns the inverse quaternion (inverse rotation).

        The result has a negated axis() direction and the same angle().

        A composition of a quaternion and its inverse() results in an identity function. Use invert() to actually modify the quaternion.

        See Also:
        invert()
      • invert

        public void invert()
        Sets the value of this to the inverse of itself.
        See Also:
        inverse()
      • invert

        public void invert​(Quaternion quaternion)
        Sets the value of this to the Quaternion inverse of quaternion.
        Parameters:
        quaternion - the Quaternion to be inverted
      • normalize

        public float normalize()
        Normalize this quaternion return its norm().
      • norm

        public float norm()
        Returns the norm of this quaternion.
      • rotate

        public Vector rotate​(Vector vector)
        Returns the image of vector by the quaternion rotation.
        Parameters:
        vector - the Vector
      • inverseRotate

        public Vector inverseRotate​(Vector vector)
        Returns the image of vector by the quaternion inverse() rotation.

        rotate(Vector) performs an inverse transformation.

        Parameters:
        vector - the Vector
      • fromEulerAngles

        public void fromEulerAngles​(float roll,
                                    float pitch,
                                    float yaw)
        Converts Euler rotation angles roll, pitch and yaw, respectively defined to the x, y and z axes, to this quaternion. In the convention used here these angles represent a composition of extrinsic rotations (rotations about the reference node axes), which is also known as Tait-Bryan angles (See http://en.wikipedia.org/wiki/Euler_angles and http://en.wikipedia.org/wiki/Tait-Bryan_angles). eulerAngles() performs the inverse operation.

        Each rotation angle is converted to an axis-angle pair, with the axis corresponding to one of the Euclidean axes. The axis-angle pairs are converted to quaternions and multiplied together. The order of the rotations is: y,z,x which follows the convention found here: http://www.euclideanspace.com/maths/geometry/rotations/euler/index.htm

        See Also:
        fromTo(Vector, Vector), fromMatrix(Matrix), fromRotatedBasis(Vector, Vector, Vector), fromAxisAngle(Vector, float), eulerAngles()
      • eulerAngles

        public Vector eulerAngles()
        Converts this quaternion to Euler rotation angles roll, pitch and yaw in radians. fromEulerAngles(float, float, float) performs the inverse operation. The code was adapted from: http://www.euclideanspace.com/maths/geometry/rotations/conversions/ quaternionToEuler/index.htm. Attention: This method assumes that this quaternion is normalized.
        Returns:
        the Vector holding the roll (x coordinate of the vector), pitch (y coordinate of the vector) and yaw angles (z coordinate of the vector). Note: The order of the rotations that would produce this Quaternion (i.e., as with fromEulerAngles(roll, pitch, yaw)) is: y,z,x.
        See Also:
        fromEulerAngles(float, float, float)
      • axis

        public Vector axis()
        Returns the normalized axis direction of the rotation represented by the quaternion.

        The result is (0,0,0) for an identity quaternion.

        See Also:
        angle()
      • angle

        public float angle()
        Returns the angle (in radians) of the rotation represented by the quaternion.

        This value is always in the range [0-pi]. Larger rotational angles are obtained by inverting the axis() direction.

        See Also:
        axis()
      • angle2D

        public float angle2D()
        Same as return axis().z() > 0 ? angle() : -angle().
        See Also:
        angle()
      • matrix

        public Matrix matrix()
        Returns the rotation matrix associated with the quaternion.
      • inverseMatrix

        public Matrix inverseMatrix()
        Returns the associated inverse rotation matrix. This is simply matrix() of the inverse(). Attention: The result is only valid until the next call to inverseMatrix(). Use it immediately (as in applyMatrix(q.inverseMatrix())).
      • log

        public Quaternion log()
        Returns the quaternion logarithm.
        See Also:
        exp()
      • exp

        public Quaternion exp()
        Returns the quaternion exponential.
        See Also:
        log()
      • slerp

        public static Quaternion slerp​(Quaternion a,
                                       Quaternion b,
                                       float t,
                                       boolean allowFlip)
        Returns the slerp interpolation of quaternions a and b, at time t.

        t should range in [0,1]. Result is a when t=0 and b when t=1.

        When allowFlip is true (default) the slerp interpolation will always use the "shortest path" between the quaternions' orientations, by "flipping" the source quaternion if needed (see negate()).

        Parameters:
        a - the first Quaternion
        b - the second Quaternion
        t - the t interpolation parameter
        allowFlip - tells whether or not the interpolation allows axis flip
      • squad

        public static Quaternion squad​(Quaternion a,
                                       Quaternion tgA,
                                       Quaternion tgB,
                                       Quaternion b,
                                       float t)
        Returns the slerp interpolation of the two quaternions a and b, at time t, using tangents tgA and tgB.

        The resulting quaternion is "between" a and b (result is a when t=0 and b for t=1).

        Use squadTangent(Quaternion, Quaternion, Quaternion) to define the quaternion tangents tgA and tgB.

        Parameters:
        a - the first Quaternion
        tgA - the first tangent Quaternion
        tgB - the second tangent Quaternion
        b - the second Quaternion
        t - the t interpolation parameter
      • squadTangent

        public static Quaternion squadTangent​(Quaternion before,
                                              Quaternion center,
                                              Quaternion after)
        Returns a tangent quaternion for center, defined by before and after quaternions.
        Parameters:
        before - the first Quaternion
        center - the second Quaternion
        after - the third Quaternion
      • squaredNorm

        public static float squaredNorm​(Quaternion quaternion)
        Utility function that returns the squared norm of the quaternion.
      • toString

        public String toString()
        Return this quaternion components as a String.
        Overrides:
        toString in class Object