Class Quaternion

    • Field Detail

      • ALLOWED_DEVIANCE

        public static final float ALLOWED_DEVIANCE
        Quaternion Epsilon, used with equals method to determine if two Quaternions are close enough to be considered equal.

        Using 9.999999974752427E-7f, which is ~10 times FloatUtil.EPSILON.

        See Also:
        Constant Field Values
    • Constructor Detail

      • Quaternion

        public Quaternion()
      • Quaternion

        public Quaternion​(float x,
                          float y,
                          float z,
                          float w)
    • Method Detail

      • magnitudeSquared

        public final float magnitudeSquared()
        See magnitude() for special handling of epsilon, which is not applied here.
        Returns:
        the squared magnitude of this quaternion.
      • w

        public final float w()
      • setW

        public final void setW​(float w)
      • x

        public final float x()
      • setX

        public final void setX​(float x)
      • y

        public final float y()
      • setY

        public final void setY​(float y)
      • z

        public final float z()
      • setZ

        public final void setZ​(float z)
      • dot

        public final float dot​(float x,
                               float y,
                               float z,
                               float w)
        Returns the dot product of this quaternion with the given x,y,z and w components.
      • dot

        public final float dot​(Quaternion quat)
        Returns the dot product of this quaternion with the given quaternion
      • isIdentity

        public final boolean isIdentity()
        Returns true if this quaternion has identity.

        Implementation uses epsilon to compare W against 1f and X, Y and Z against zero.

      • setIdentity

        public final Quaternion setIdentity()
        Set this quaternion to identity (x=0,y=0,z=0,w=1)
        Returns:
        this quaternion for chaining.
      • normalize

        public final Quaternion normalize()
        Normalize a quaternion required if to be used as a rotational quaternion.

        Implementation Details:

        Returns:
        this quaternion for chaining.
      • conjugate

        public Quaternion conjugate()
        Conjugates this quaternion [-x, -y, -z, w].
        Returns:
        this quaternion for chaining.
        See Also:
        Matrix-FAQ Q49
      • set

        public final Quaternion set​(Quaternion src)
        Set all values of this quaternion using the given src.
        Returns:
        this quaternion for chaining.
      • set

        public final Quaternion set​(float x,
                                    float y,
                                    float z,
                                    float w)
        Set all values of this quaternion using the given components.
        Returns:
        this quaternion for chaining.
      • rotateByAngleNormalAxis

        public Quaternion rotateByAngleNormalAxis​(float angle,
                                                  float axisX,
                                                  float axisY,
                                                  float axisZ)
        Rotate this quaternion by the given angle and axis.

        The axis must be a normalized vector.

        A rotational quaternion is made from the given angle and axis.

        Parameters:
        angle - in radians
        axisX - x-coord of rotation axis
        axisY - y-coord of rotation axis
        axisZ - z-coord of rotation axis
        Returns:
        this quaternion for chaining.
      • rotateByAngleX

        public Quaternion rotateByAngleX​(float angle)
        Rotate this quaternion around X axis with the given angle in radians
        Parameters:
        angle - in radians
        Returns:
        this quaternion for chaining.
      • rotateByAngleY

        public Quaternion rotateByAngleY​(float angle)
        Rotate this quaternion around Y axis with the given angle in radians
        Parameters:
        angle - in radians
        Returns:
        this quaternion for chaining.
      • rotateByAngleZ

        public Quaternion rotateByAngleZ​(float angle)
        Rotate this quaternion around Z axis with the given angle in radians
        Parameters:
        angle - in radians
        Returns:
        this quaternion for chaining.
      • rotateByEuler

        public final Quaternion rotateByEuler​(Vec3f angradXYZ)
        Rotates this quaternion from the given Euler rotation array angradXYZ in radians.

        The angradXYZ array is laid out in natural order:

        • x - bank
        • y - heading
        • z - attitude

        For details see rotateByEuler(float, float, float).
        Parameters:
        angradXYZ - euler angle array in radians
        Returns:
        this quaternion for chaining.
        See Also:
        rotateByEuler(float, float, float)
      • rotateVector

        public final Vec3f rotateVector​(Vec3f vecIn,
                                        Vec3f vecOut)
        Rotate the given vector by this quaternion
        Parameters:
        vecIn - vector to be rotated
        vecOut - result storage for rotated vector, maybe equal to vecIn for in-place rotation
        Returns:
        the given vecOut store for chaining
        See Also:
        Matrix-FAQ Q63
      • setSlerp

        public final Quaternion setSlerp​(Quaternion a,
                                         Quaternion b,
                                         float changeAmnt)
        Set this quaternion to a spherical linear interpolation between the given start and end quaternions by the given change amount.

        Note: Method does not normalize this quaternion!

        Parameters:
        a - start quaternion
        b - end quaternion
        changeAmnt - float between 0 and 1 representing interpolation.
        Returns:
        this quaternion for chaining.
        See Also:
        euclideanspace.com-QuaternionSlerp
      • setLookAt

        public Quaternion setLookAt​(Vec3f directionIn,
                                    Vec3f upIn,
                                    Vec3f xAxisOut,
                                    Vec3f yAxisOut,
                                    Vec3f zAxisOut)
        Set this quaternion to equal the rotation required to point the z-axis at direction and the y-axis to up.

        Implementation generates a 3x3 matrix and is equal with ProjectFloat's lookAt(..).

        Implementation Details:

        Parameters:
        directionIn - where to look at
        upIn - a vector indicating the local up direction.
        xAxisOut - vector storing the orthogonal x-axis of the coordinate system.
        yAxisOut - vector storing the orthogonal y-axis of the coordinate system.
        zAxisOut - vector storing the orthogonal z-axis of the coordinate system.
        Returns:
        this quaternion for chaining.
        See Also:
        euclideanspace.com-LookUp
      • setFromVectors

        public final Quaternion setFromVectors​(Vec3f v1,
                                               Vec3f v2,
                                               Vec3f tmpPivotVec,
                                               Vec3f tmpNormalVec)
        Initialize this quaternion from two vectors
           q = (s,v) = (v1•v2 , v1 × v2),
             angle = angle(v1, v2) = v1•v2
              axis = normal(v1 x v2)
         

        Implementation Details:

        Parameters:
        v1 - not normalized
        v2 - not normalized
        tmpPivotVec - temp storage for cross product
        tmpNormalVec - temp storage to normalize vector
        Returns:
        this quaternion for chaining.
      • setFromNormalVectors

        public final Quaternion setFromNormalVectors​(Vec3f v1,
                                                     Vec3f v2,
                                                     Vec3f tmpPivotVec)
        Initialize this quaternion from two normalized vectors
           q = (s,v) = (v1•v2 , v1 × v2),
             angle = angle(v1, v2) = v1•v2
              axis = v1 x v2
         

        Implementation Details:

        Parameters:
        v1 - normalized
        v2 - normalized
        tmpPivotVec - temp storage for cross product
        Returns:
        this quaternion for chaining.
      • setFromAngleAxis

        public final Quaternion setFromAngleAxis​(float angle,
                                                 Vec3f vector,
                                                 Vec3f tmpV3f)
        Initialize this quaternion with given non-normalized axis vector and rotation angle

        Implementation Details:

        Parameters:
        angle - rotation angle (rads)
        vector - axis vector not normalized
        tmpV3f - temp storage to normalize vector
        Returns:
        this quaternion for chaining.
        See Also:
        Matrix-FAQ Q56, toAngleAxis(Vec3f)
      • setFromAngleNormalAxis

        public final Quaternion setFromAngleNormalAxis​(float angle,
                                                       Vec3f vector)
        Initialize this quaternion with given normalized axis vector and rotation angle

        Implementation Details:

        Parameters:
        angle - rotation angle (rads)
        vector - axis vector normalized
        Returns:
        this quaternion for chaining.
        See Also:
        Matrix-FAQ Q56, toAngleAxis(Vec3f)
      • toAngleAxis

        public final float toAngleAxis​(Vec3f axis)
        Transform the rotational quaternion to axis based rotation angles
        Parameters:
        axis - storage for computed axis
        Returns:
        the rotation angle in radians
        See Also:
        setFromAngleAxis(float, Vec3f, Vec3f)
      • setFromEuler

        public final Quaternion setFromEuler​(Vec3f angradXYZ)
        Initializes this quaternion from the given Euler rotation array angradXYZ in radians.

        The angradXYZ vector is laid out in natural order:

        • x - bank
        • y - heading
        • z - attitude

        For details see setFromEuler(float, float, float).
        Parameters:
        angradXYZ - euler angle vector in radians holding x-bank, y-heading and z-attitude
        Returns:
        this quaternion for chaining.
        See Also:
        setFromEuler(float, float, float)
      • setFromEuler

        public final Quaternion setFromEuler​(float bankX,
                                             float headingY,
                                             float attitudeZ)
        Initializes this quaternion from the given Euler rotation angles in radians.

        The rotations are applied in the given order:

        • y - heading
        • z - attitude
        • x - bank

        Implementation Details:

        Parameters:
        bankX - the Euler pitch angle in radians. (rotation about the X axis)
        headingY - the Euler yaw angle in radians. (rotation about the Y axis)
        attitudeZ - the Euler roll angle in radians. (rotation about the Z axis)
        Returns:
        this quaternion for chaining.
        See Also:
        Matrix-FAQ Q60, Gems, euclideanspace.com-eulerToQuaternion, toEuler(Vec3f)
      • toEuler

        public Vec3f toEuler​(Vec3f result)
        Transform this quaternion to Euler rotation angles in radians (pitchX, yawY and rollZ).

        The result array is laid out in natural order:

        • x - bank
        • y - heading
        • z - attitude

        Parameters:
        result - euler angle result vector for radians x-bank, y-heading and z-attitude
        Returns:
        the Vec3f `result` filled with x-bank, y-heading and z-attitude
        See Also:
        euclideanspace.com-quaternionToEuler, setFromEuler(float, float, float)
      • setFromAxes

        public final Quaternion setFromAxes​(Vec3f xAxis,
                                            Vec3f yAxis,
                                            Vec3f zAxis)
        Initializes this quaternion to represent a rotation formed by the given three orthogonal axes.

        No validation whether the axes are orthogonal is performed.

        Parameters:
        xAxis - vector representing the orthogonal x-axis of the coordinate system.
        yAxis - vector representing the orthogonal y-axis of the coordinate system.
        zAxis - vector representing the orthogonal z-axis of the coordinate system.
        Returns:
        this quaternion for chaining.
      • toAxes

        public void toAxes​(Vec3f xAxis,
                           Vec3f yAxis,
                           Vec3f zAxis,
                           Matrix4f tmpMat4)
        Extracts this quaternion's orthogonal rotation axes.
        Parameters:
        xAxis - vector representing the orthogonal x-axis of the coordinate system.
        yAxis - vector representing the orthogonal y-axis of the coordinate system.
        zAxis - vector representing the orthogonal z-axis of the coordinate system.
        tmpMat4 - temporary float[4] matrix, used to transform this quaternion to a matrix.
      • isRotationMatrix3f

        @Deprecated
        public final boolean isRotationMatrix3f​(float[] m)
        Deprecated.
        Check if the the 3x3 matrix (param) is in fact an affine rotational matrix
        Parameters:
        m - 3x3 column matrix
        Returns:
        true if representing a rotational matrix, false otherwise
      • equals

        public boolean equals​(Object o)
        Overrides:
        equals in class Object
        Parameters:
        o - the object to compare for equality
        Returns:
        true if this quaternion and the provided quaternion have roughly the same x, y, z and w values.
      • hashCode

        public final int hashCode()
        Overrides:
        hashCode in class Object