Class Quaternion

  • All Implemented Interfaces:
    java.io.Serializable

    public final class Quaternion
    extends java.lang.Object
    implements java.io.Serializable
    This class implements quaternions (Hamilton's hypercomplex numbers).
    Instance of this class are guaranteed to be immutable.
    Since:
    3.1
    See Also:
    Serialized Form
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Quaternion I
      i
      static Quaternion IDENTITY
      Identity quaternion.
      static Quaternion J
      j
      static Quaternion K
      k
      private double q0
      First component (scalar part).
      private double q1
      Second component (first vector part).
      private double q2
      Third component (second vector part).
      private double q3
      Fourth component (third vector part).
      private static long serialVersionUID
      Serializable version identifier.
      static Quaternion ZERO
      Zero quaternion.
    • Constructor Summary

      Constructors 
      Constructor Description
      Quaternion​(double[] v)
      Builds a pure quaternion from a vector (assuming that the scalar part is zero).
      Quaternion​(double scalar, double[] v)
      Builds a quaternion from scalar and vector parts.
      Quaternion​(double a, double b, double c, double d)
      Builds a quaternion from its components.
    • Field Detail

      • IDENTITY

        public static final Quaternion IDENTITY
        Identity quaternion.
      • ZERO

        public static final Quaternion ZERO
        Zero quaternion.
      • serialVersionUID

        private static final long serialVersionUID
        Serializable version identifier.
        See Also:
        Constant Field Values
      • q0

        private final double q0
        First component (scalar part).
      • q1

        private final double q1
        Second component (first vector part).
      • q2

        private final double q2
        Third component (second vector part).
      • q3

        private final double q3
        Fourth component (third vector part).
    • Constructor Detail

      • Quaternion

        public Quaternion​(double a,
                          double b,
                          double c,
                          double d)
        Builds a quaternion from its components.
        Parameters:
        a - Scalar component.
        b - First vector component.
        c - Second vector component.
        d - Third vector component.
      • Quaternion

        public Quaternion​(double scalar,
                          double[] v)
                   throws DimensionMismatchException
        Builds a quaternion from scalar and vector parts.
        Parameters:
        scalar - Scalar part of the quaternion.
        v - Components of the vector part of the quaternion.
        Throws:
        DimensionMismatchException - if the array length is not 3.
      • Quaternion

        public Quaternion​(double[] v)
        Builds a pure quaternion from a vector (assuming that the scalar part is zero).
        Parameters:
        v - Components of the vector part of the pure quaternion.
    • Method Detail

      • getConjugate

        public Quaternion getConjugate()
        Returns the conjugate quaternion of the instance.
        Returns:
        the conjugate quaternion
      • multiply

        public static Quaternion multiply​(Quaternion q1,
                                          Quaternion q2)
        Returns the Hamilton product of two quaternions.
        Parameters:
        q1 - First quaternion.
        q2 - Second quaternion.
        Returns:
        the product q1 and q2, in that order.
      • multiply

        public Quaternion multiply​(Quaternion q)
        Returns the Hamilton product of the instance by a quaternion.
        Parameters:
        q - Quaternion.
        Returns:
        the product of this instance with q, in that order.
      • add

        public static Quaternion add​(Quaternion q1,
                                     Quaternion q2)
        Computes the sum of two quaternions.
        Parameters:
        q1 - Quaternion.
        q2 - Quaternion.
        Returns:
        the sum of q1 and q2.
      • add

        public Quaternion add​(Quaternion q)
        Computes the sum of the instance and another quaternion.
        Parameters:
        q - Quaternion.
        Returns:
        the sum of this instance and q
      • subtract

        public static Quaternion subtract​(Quaternion q1,
                                          Quaternion q2)
        Subtracts two quaternions.
        Parameters:
        q1 - First Quaternion.
        q2 - Second quaternion.
        Returns:
        the difference between q1 and q2.
      • subtract

        public Quaternion subtract​(Quaternion q)
        Subtracts a quaternion from the instance.
        Parameters:
        q - Quaternion.
        Returns:
        the difference between this instance and q.
      • dotProduct

        public static double dotProduct​(Quaternion q1,
                                        Quaternion q2)
        Computes the dot-product of two quaternions.
        Parameters:
        q1 - Quaternion.
        q2 - Quaternion.
        Returns:
        the dot product of q1 and q2.
      • dotProduct

        public double dotProduct​(Quaternion q)
        Computes the dot-product of the instance by a quaternion.
        Parameters:
        q - Quaternion.
        Returns:
        the dot product of this instance and q.
      • getNorm

        public double getNorm()
        Computes the norm of the quaternion.
        Returns:
        the norm.
      • normalize

        public Quaternion normalize()
        Computes the normalized quaternion (the versor of the instance). The norm of the quaternion must not be zero.
        Returns:
        a normalized quaternion.
        Throws:
        ZeroException - if the norm of the quaternion is zero.
      • equals

        public boolean equals​(java.lang.Object other)
        Overrides:
        equals in class java.lang.Object
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(Quaternion q,
                              double eps)
        Checks whether this instance is equal to another quaternion within a given tolerance.
        Parameters:
        q - Quaternion with which to compare the current quaternion.
        eps - Tolerance.
        Returns:
        true if the each of the components are equal within the allowed absolute error.
      • isUnitQuaternion

        public boolean isUnitQuaternion​(double eps)
        Checks whether the instance is a unit quaternion within a given tolerance.
        Parameters:
        eps - Tolerance (absolute error).
        Returns:
        true if the norm is 1 within the given tolerance, false otherwise
      • isPureQuaternion

        public boolean isPureQuaternion​(double eps)
        Checks whether the instance is a pure quaternion within a given tolerance.
        Parameters:
        eps - Tolerance (absolute error).
        Returns:
        true if the scalar part of the quaternion is zero.
      • getPositivePolarForm

        public Quaternion getPositivePolarForm()
        Returns the polar form of the quaternion.
        Returns:
        the unit quaternion with positive scalar part.
      • getInverse

        public Quaternion getInverse()
        Returns the inverse of this instance. The norm of the quaternion must not be zero.
        Returns:
        the inverse.
        Throws:
        ZeroException - if the norm (squared) of the quaternion is zero.
      • getQ0

        public double getQ0()
        Gets the first component of the quaternion (scalar part).
        Returns:
        the scalar part.
      • getQ1

        public double getQ1()
        Gets the second component of the quaternion (first component of the vector part).
        Returns:
        the first component of the vector part.
      • getQ2

        public double getQ2()
        Gets the third component of the quaternion (second component of the vector part).
        Returns:
        the second component of the vector part.
      • getQ3

        public double getQ3()
        Gets the fourth component of the quaternion (third component of the vector part).
        Returns:
        the third component of the vector part.
      • getScalarPart

        public double getScalarPart()
        Gets the scalar part of the quaternion.
        Returns:
        the scalar part.
        See Also:
        getQ0()
      • getVectorPart

        public double[] getVectorPart()
        Gets the three components of the vector part of the quaternion.
        Returns:
        the vector part.
        See Also:
        getQ1(), getQ2(), getQ3()
      • multiply

        public Quaternion multiply​(double alpha)
        Multiplies the instance by a scalar.
        Parameters:
        alpha - Scalar factor.
        Returns:
        a scaled quaternion.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object