Package jme3utilities.math

Class MyQuaternion

java.lang.Object
jme3utilities.math.MyQuaternion
public final class MyQuaternion extends Object
Mathematical utility methods.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Logger
    logger
    message logger for this class

  • Method Summary

    Modifier and Type
    Method
    Description
    static void
    accumulateScaled(com.jme3.math.Quaternion total, com.jme3.math.Quaternion input, float scale)
    Accumulate a linear combination of quaternions.
    static float
    angleBetween(com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2)
    Return the angle (in radians) between the specified quaternions, provided both are normalized.
    static void
    cardinalizeLocal(com.jme3.math.Quaternion input)
    Find the cardinal rotation most similar to the specified Quaternion.
    static com.jme3.math.Quaternion
    conjugate(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
    Return the conjugate of a Quaternion.
    static int
    countNe(com.jme3.math.Quaternion[] quaternions)
    Count the number of distinct quaternions, without distinguishing 0 from -0.
    static String
    describe(com.jme3.math.Quaternion q)
    Generate a textual description of a Quaternion value.
    static double
    dot(com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2)
    Return the dot (scalar) product of 2 quaternions.
    static com.jme3.math.Quaternion
    exp(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
    Return the exponential of a pure Quaternion.
    static boolean
    isPure(com.jme3.math.Quaternion q)
    Test for a pure Quaternion.
    static boolean
    isRotationIdentity(com.jme3.math.Quaternion q)
    Test whether the specified Quaternion represents an identity rotation.
    static boolean
    isZero(com.jme3.math.Quaternion q)
    Test for a zero Quaternion.
    static double
    lengthSquared(com.jme3.math.Quaternion q)
    Return the squared length of the argument.
    static com.jme3.math.Quaternion
    log(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
    Return the natural logarithm of a normalized quaternion.
    static com.jme3.math.Quaternion
    mirrorAxis(com.jme3.math.Quaternion input, int axisIndex, com.jme3.math.Quaternion storeResult)
    Mirror the specified Quaternion along the indexed axis.
    static boolean
    ne(com.jme3.math.Quaternion a, com.jme3.math.Quaternion b)
    Test whether 2 quaternions are distinct, without distinguishing 0 from -0.
    static void
    normalizeLocal(com.jme3.math.Quaternion input)
    Normalize the specified Quaternion in place.
    static com.jme3.math.Quaternion
    pow(com.jme3.math.Quaternion base, float exponent, com.jme3.math.Quaternion storeResult)
    Raise a normalized quaternion to the specified real power.
    static com.jme3.math.Vector3f
    rotate(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f input, com.jme3.math.Vector3f storeResult)
    Rotate the input vector using the specified quaternion.
    static com.jme3.math.Vector3f
    rotateInverse(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f input, com.jme3.math.Vector3f storeResult)
    Rotate the input vector using the inverse of the specified quaternion.
    static com.jme3.math.Quaternion
    slerp(float t, com.jme3.math.Quaternion q0, com.jme3.math.Quaternion q1, com.jme3.math.Quaternion storeResult)
    Interpolate between 2 normalized quaternions using spherical linear (Slerp) interpolation.
    static void
    snapLocal(com.jme3.math.Quaternion input, int axisIndex)
    Round the rotation angle of the indexed axis to the nearest Pi/2 radians.
    static com.jme3.math.Quaternion
    squad(float t, com.jme3.math.Quaternion p, com.jme3.math.Quaternion a, com.jme3.math.Quaternion b, com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
    Interpolate between 4 normalized quaternions using the Squad function.
    static com.jme3.math.Quaternion
    squadA(com.jme3.math.Quaternion q0, com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2, com.jme3.math.Quaternion storeResult)
    Return Squad parameter "a" for a continuous first derivative at the middle point of 3 specified control points.
    static com.jme3.math.Quaternion
    standardize(com.jme3.math.Quaternion input, com.jme3.math.Quaternion storeResult)
    Standardize a Quaternion in preparation for hashing.
    static boolean
    validateUnit(com.jme3.math.Quaternion q, String description, float tolerance)
    Validate a normalized quaternion as a method argument.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • logger

      public static final Logger logger
      message logger for this class

  • Method Details

    • accumulateScaled

      public static void accumulateScaled(com.jme3.math.Quaternion total, com.jme3.math.Quaternion input, float scale)
      Accumulate a linear combination of quaternions.
      Parameters:
      total - sum of the scaled inputs so far (not null, modified, may be input)
      input - the Quaternion to scale and add (not null, unaffected unless it's total)
      scale - scale factor to apply to the input

    • angleBetween

      public static float angleBetween(com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2)
      Return the angle (in radians) between the specified quaternions, provided both are normalized.
      Parameters:
      q1 - the first quaternion (not null, norm approximately equal to 1, unaffected)
      q2 - the other quaternions (not null, norm approximately equal to 1, unaffected)
      Returns:
      the angle (in radians, not negative)

    • cardinalizeLocal

      public static void cardinalizeLocal(com.jme3.math.Quaternion input)
      Find the cardinal rotation most similar to the specified Quaternion. A cardinal rotation is one for which the rotation angles on all 3 axes are integer multiples of Pi/2 radians.
      Parameters:
      input - the input value (not null, modified)

    • conjugate

      public static com.jme3.math.Quaternion conjugate(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
      Return the conjugate of a Quaternion.

      For normalized quaternions, the conjugate is a fast way to calculate the inverse.

      Parameters:
      q - the input value (not null, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be q)
      Returns:
      a conjugate quaternion (either storeResult or a new instance)

    • countNe

      public static int countNe(com.jme3.math.Quaternion[] quaternions)
      Count the number of distinct quaternions, without distinguishing 0 from -0.
      Parameters:
      quaternions - (unaffected)
      Returns:
      the count (≥0)

    • describe

      public static String describe(com.jme3.math.Quaternion q)
      Generate a textual description of a Quaternion value.
      Parameters:
      q - the value to describe (may be null, unaffected)
      Returns:
      a description (not null, not empty)

    • dot

      public static double dot(com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2)
      Return the dot (scalar) product of 2 quaternions.

      Unlike Quaternion.dot(com.jme3.math.Quaternion), this method returns a double-precision value for precise comparison of angles.

      Parameters:
      q1 - the first input value (not null, unaffected)
      q2 - the 2nd input value (not null, unaffected)
      Returns:
      the dot product

    • exp

      public static com.jme3.math.Quaternion exp(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
      Return the exponential of a pure Quaternion.
      Parameters:
      q - the input value (not null, w=0, unaffected)
      storeResult - storage for the result (modified if not null)
      Returns:
      the exponential value (either storeResult or a new instance)

    • isPure

      public static boolean isPure(com.jme3.math.Quaternion q)
      Test for a pure Quaternion.
      Parameters:
      q - the value to test (not null, unaffected)
      Returns:
      true if w=0, false otherwise

    • isRotationIdentity

      public static boolean isRotationIdentity(com.jme3.math.Quaternion q)
      Test whether the specified Quaternion represents an identity rotation.

      This test is weaker than that implemented by Quaternion.isIdentity() because it accepts any finite, non-zero value for w.

      Parameters:
      q - the value to test (not null, unaffected)
      Returns:
      true for a rotation identity, otherwise false

    • isZero

      public static boolean isZero(com.jme3.math.Quaternion q)
      Test for a zero Quaternion.
      Parameters:
      q - the value to test (not null, unaffected)
      Returns:
      true if the argument equals (0,0,0,0), false otherwise

    • lengthSquared

      public static double lengthSquared(com.jme3.math.Quaternion q)
      Return the squared length of the argument.

      Unlike Quaternion.norm(), this method returns a double-precision value for precise comparison of lengths.

      Parameters:
      q - the input value (not null, unaffected)
      Returns:
      the squared length (≥0)

    • log

      public static com.jme3.math.Quaternion log(com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
      Return the natural logarithm of a normalized quaternion.

      In general, the result isn't itself normalized.

      Parameters:
      q - the input value (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be q)
      Returns:
      a pure quaternion (either storeResult or a new instance)

    • mirrorAxis

      public static com.jme3.math.Quaternion mirrorAxis(com.jme3.math.Quaternion input, int axisIndex, com.jme3.math.Quaternion storeResult)
      Mirror the specified Quaternion along the indexed axis.
      Parameters:
      input - the Quaternion to mirror (not null, unaffected unless it's storeResult)
      axisIndex - which axis to mirror: 0→X, 1→Y, 2→Z
      storeResult - storage for the result (modified if not null, may be input)
      Returns:
      a mirrored Quaternion (either storeResult or a new instance)

    • ne

      public static boolean ne(com.jme3.math.Quaternion a, com.jme3.math.Quaternion b)
      Test whether 2 quaternions are distinct, without distinguishing 0 from -0.
      Parameters:
      a - the first input value (not null, unaffected)
      b - the 2nd input value (not null, unaffected)
      Returns:
      true if distinct, otherwise false

    • normalizeLocal

      public static void normalizeLocal(com.jme3.math.Quaternion input)
      Normalize the specified Quaternion in place.

      This method is less vulnerable to overflow than Quaternion.normalizeLocal().

      Parameters:
      input - the instance to normalize (not null, modified)

    • pow

      public static com.jme3.math.Quaternion pow(com.jme3.math.Quaternion base, float exponent, com.jme3.math.Quaternion storeResult)
      Raise a normalized quaternion to the specified real power.
      Parameters:
      base - the input value (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      exponent - the exponent
      storeResult - storage for the result (modified if not null, may be base)
      Returns:
      the power (either storeResult or a new instance)

    • rotate

      public static com.jme3.math.Vector3f rotate(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f input, com.jme3.math.Vector3f storeResult)
      Rotate the input vector using the specified quaternion.

      Unlike Quaternion.mult(com.jme3.math.Vector3f, com.jme3.math.Vector3f), this method doesn't assume the quaternion is normalized. Instead, rotation is performed using a normalized version of the quaternion.

      Parameters:
      rotation - the desired rotation (not null, not zero, unaffected)
      input - the vector to rotate (not null, finite, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be input)
      Returns:
      the rotated vector (either storeResult or a new instance)

    • rotateInverse

      public static com.jme3.math.Vector3f rotateInverse(com.jme3.math.Quaternion rotation, com.jme3.math.Vector3f input, com.jme3.math.Vector3f storeResult)
      Rotate the input vector using the inverse of the specified quaternion.
      Parameters:
      rotation - the rotation (not null, not zero, unaffected)
      input - the vector to rotate (not null, finite, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be input)
      Returns:
      the rotated vector (either storeResult or a new instance)

    • slerp

      public static com.jme3.math.Quaternion slerp(float t, com.jme3.math.Quaternion q0, com.jme3.math.Quaternion q1, com.jme3.math.Quaternion storeResult)
      Interpolate between 2 normalized quaternions using spherical linear (Slerp) interpolation.

      This method is slower (but more accurate) than Quaternion.slerp(com.jme3.math.Quaternion, float), always produces a normalized result, and never trashes q1.

      The caller is responsible for flipping the sign of q0 or q1 when it's appropriate to do so.

      Parameters:
      t - the weight given to q1 (≥0, ≤1)
      q0 - the function value at t=0 (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      q1 - the function value at t=1 (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be q0 or q1)
      Returns:
      an interpolated value (either storeResult or a new instance)

    • snapLocal

      public static void snapLocal(com.jme3.math.Quaternion input, int axisIndex)
      Round the rotation angle of the indexed axis to the nearest Pi/2 radians.
      Parameters:
      input - (not null, modified)
      axisIndex - which axis (≥0, <3)

    • squad

      public static com.jme3.math.Quaternion squad(float t, com.jme3.math.Quaternion p, com.jme3.math.Quaternion a, com.jme3.math.Quaternion b, com.jme3.math.Quaternion q, com.jme3.math.Quaternion storeResult)
      Interpolate between 4 normalized quaternions using the Squad function. The caller is responsible for flipping signs when it's appropriate to do so.
      Parameters:
      t - the weight given to q (≥0, ≤1)
      p - function value at t=0 (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      a - the first control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      b - the 2nd control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      q - function value at t=1 (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null)
      Returns:
      the interpolated value (either storeResult or a new instance)

    • squadA

      public static com.jme3.math.Quaternion squadA(com.jme3.math.Quaternion q0, com.jme3.math.Quaternion q1, com.jme3.math.Quaternion q2, com.jme3.math.Quaternion storeResult)
      Return Squad parameter "a" for a continuous first derivative at the middle point of 3 specified control points.
      Parameters:
      q0 - the previous control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      q1 - the current control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      q2 - the following control point (not null, norm approximately equal to 1, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null)
      Returns:
      the Squad parameter (either storeResult or a new instance)

    • standardize

      public static com.jme3.math.Quaternion standardize(com.jme3.math.Quaternion input, com.jme3.math.Quaternion storeResult)
      Standardize a Quaternion in preparation for hashing.
      Parameters:
      input - the input value (not null, unaffected unless it's storeResult)
      storeResult - storage for the result (modified if not null, may be input)
      Returns:
      an equivalent Quaternion without negative zeros (either storeResult or a new instance)

    • validateUnit

      public static boolean validateUnit(com.jme3.math.Quaternion q, String description, float tolerance)
      Validate a normalized quaternion as a method argument.
      Parameters:
      q - the Quaternion to validate (not null, unaffected)
      description - description of the Quaternion
      tolerance - for the norm (≥0)
      Returns:
      true
      Throws:
      IllegalArgumentException - if the norm is out of tolerance
      NullPointerException - if the Quaternion is null