Package jme3utilities.math

Class MyQuaternion

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

  • Field Details

    • logger

      public static final Logger logger
      message logger for this class

  • Method Details

    • accumulateScaled

      public static void accumulateScaled(Quaternion total, 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

    • cardinalizeLocal

      public static void cardinalizeLocal(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 Quaternion conjugate(Quaternion q, 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)

    • describe

      public static String describe(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(Quaternion q1, Quaternion q2)
      Return the dot (scalar) product of 2 quaternions.

      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 Quaternion exp(Quaternion q, 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(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(Quaternion q)
      Test whether the specified Quaternion represents an identity rotation.

      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(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(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 Quaternion log(Quaternion q, 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)

    • ne

      public static boolean ne(Quaternion a, 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(Quaternion input)
      Normalize the specified Quaternion in place.
      Parameters:
      input - the instance to normalize (not null, modified)

    • pow

      public static Quaternion pow(Quaternion base, float exponent, 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 Vector3f rotate(Quaternion rotation, Vector3f input, Vector3f storeResult)
      Rotate the input vector using the specified quaternion.

      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 Vector3f rotateInverse(Quaternion rotation, Vector3f input, 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 Quaternion slerp(float t, Quaternion q0, Quaternion q1, Quaternion storeResult)
      Interpolate between 2 normalized quaternions using spherical linear (Slerp) interpolation.

      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)

    • squad

      public static Quaternion squad(float t, Quaternion p, Quaternion a, Quaternion b, Quaternion q, 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 Quaternion squadA(Quaternion q0, Quaternion q1, Quaternion q2, 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 Quaternion standardize(Quaternion input, 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(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