Package civitas.celestis.math.complex

Class Quaternion

java.lang.Object
civitas.celestis.util.tuple.Double4
civitas.celestis.math.complex.Quaternion
All Implemented Interfaces:
BaseTuple<Double>, DoubleTuple, Serializable
public class Quaternion extends Double4
A complex number with three imaginary parts. Quaternions are used to describe the rotational motion of three-dimensional vectors.
See Also:

  • Field Details

    • IDENTITY

      public static final Quaternion IDENTITY
      The identity quaternion. This will produce no rotation.

  • Constructor Details

    • Quaternion

      public Quaternion(double w, double x, double y, double z)
      Creates a new quaternion.
      Parameters:
      w - The W component of this quaternion
      x - The X component of this quaternion
      y - The Y component of this quaternion
      z - The Z component of this quaternion

    • Quaternion

      public Quaternion(double s, @Nonnull Double3 v)
      Creates a new quaternion.
      Parameters:
      s - The scalar part of this quaternion
      v - The vector part of this quaternion

    • Quaternion

      public Quaternion(@Nonnull double[] components)
      Creates a new quaternion.
      Parameters:
      components - An array containing the component of this quaternion in WXYZ order
      Throws:
      IllegalArgumentException - When the provided array's length is not 4

    • Quaternion

      public Quaternion(@Nonnull DoubleTuple t)
      Creates a new quaternion.
      Parameters:
      t - The tuple of which to copy component values from
      Throws:
      IllegalArgumentException - When the provided tuple t's size is not 4

  • Method Details

    • norm

      public double norm()
      Returns the Euclidean norm (the magnitude) of this quaternion.
      Returns:
      The Euclidean norm of this quaternion

    • norm2

      public double norm2()
      Returns the squared Euclidean norm (the squared magnitude) of this quaternion.
      Returns:
      The squared Euclidean norm of this quaternion

    • scalar

      public double scalar()
      Returns the scalar part of this quaternion.
      Returns:
      The scalar part of this quaternion

    • vector

      @Nonnull public Vector3 vector()
      Returns the vector part of this quaternion.
      Returns:
      The vector part of this quaternion

    • add

      @Nonnull public Quaternion add(double s)
      Adds a scalar to this quaternion, then returns the resulting quaternion.
      Parameters:
      s - The scalar of which to add to this quaternion
      Returns:
      The resulting quaternion

    • subtract

      @Nonnull public Quaternion subtract(double s)
      Subtracts this quaternion by a scalar, then returns the resulting quaternion.
      Parameters:
      s - The scalar of which to subtract this quaternion by
      Returns:
      The resulting quaternion

    • scale

      @Nonnull public Quaternion scale(double s)
      Scales the rotation of this quaternion, then returns the resulting quaternion. This will only work properly if this quaternion is a rotation quaternion. (a quaternion with a Euclidean norm of 1)
      Parameters:
      s - The scale factor to apply to the rotation
      Returns:
      The scaled quaternion

    • multiply

      @Nonnull public Quaternion multiply(double s)
      Multiplies this quaternion by a scalar, then returns the resulting quaternion.
      Parameters:
      s - The scalar of which to multiply this quaternion by
      Returns:
      The resulting quaternion

    • divide

      @Nonnull public Quaternion divide(double s) throws ArithmeticException
      Divides this quaternion by a scalar, then returns the resulting quaternion.
      Parameters:
      s - The scalar of which to divide this quaternion by
      Returns:
      The resulting quaternion
      Throws:
      ArithmeticException - When the denominator s is zero

    • add

      @Nonnull public Quaternion add(@Nonnull Quaternion q)
      Adds another quaternion to this quaternion, then returns the resulting quaternion.
      Parameters:
      q - The quaternion of which to add to this quaternion
      Returns:
      The resulting quaternion

    • subtract

      @Nonnull public Quaternion subtract(@Nonnull Quaternion q)
      Subtracts this quaternion by another quaternion, then returns the resulting quaternion.
      Parameters:
      q - The quaternion of which to subtract from this quaternion
      Returns:
      The resulting quaternion

    • multiply

      @Nonnull public Quaternion multiply(@Nonnull Quaternion q)
      Multiplies this quaternion by the provided quaternion q.
      Parameters:
      q - The quaternion of which to multiply this quaternion by
      Returns:
      The quaternion left-product of the two quaternions

    • dot

      public double dot(@Nonnull Quaternion q)
      Returns the dot product between this quaternion and the provided quaternion q.
      Parameters:
      q - The quaternion of which to get the dot product between
      Returns:
      The dot product of the two quaternions

    • conjugate

      @Nonnull public Quaternion conjugate()
      Returns the conjugate of this quaternion.
      Returns:
      The conjugate of this quaternion

    • inverse

      @Nonnull public Quaternion inverse() throws ArithmeticException
      Returns the inverse of this quaternion.
      Returns:
      The inverse of this quaternion
      Throws:
      ArithmeticException - When the squared Euclidean norm (the squared magnitude) of this quaternion is zero

    • negate

      @Nonnull public Quaternion negate()
      Negates this quaternion, then returns the negated quaternion.
      Returns:
      The negation of this quaternion

    • normalize

      @Nonnull public Quaternion normalize() throws ArithmeticException
      Normalizes this quaternion to have a Euclidean norm (magnitude) of 1.
      Returns:
      The normalized quaternion of this quaternion
      Throws:
      ArithmeticException - When the Euclidean norm of this quaternion is zero

    • normalizeOrIdentity

      @Nonnull public Quaternion normalizeOrIdentity()
      Normalizes this quaternion to have a Euclidean norm (magnitude) of 1. If this quaternion has no direction (the Euclidean norm is zero), this will the identity quaternion. (IDENTITY)
      Returns:
      The normalized quaternion of this quaternion if successful, the identity quaternion otherwise

    • normalizeOrDefault

      @Nonnull public Quaternion normalizeOrDefault(@Nonnull Quaternion q)
      Normalizes this quaternion to have a Euclidean norm (magnitude) of 1. If this quaternion has no direction (the Euclidean norm is zero), this will return the provided fallback value q instead of throwing an exception.
      Parameters:
      q - The fallback value to default to when normalization is impossible
      Returns:
      The normalized quaternion of this quaternion if successful, the fallback value otherwise