Package org.apache.commons.numbers.quaternion

Class Quaternion

java.lang.Object
org.apache.commons.numbers.quaternion.Quaternion
All Implemented Interfaces:
Serializable
public final class Quaternion extends Object implements Serializable
This class implements quaternions (Hamilton's hypercomplex numbers).

Wherever quaternion components are listed in sequence, this class follows the convention of placing the scalar (w) component first, e.g. [w, x, y, z]. Other libraries and textbooks may place the w component last.

Instances of this class are guaranteed to be immutable.

See Also:

  • Field Details

  • Method Details

    • of

      public static Quaternion of(double w, double x, double y, double z)
      Builds a quaternion from its components.
      Parameters:
      w - Scalar component.
      x - First vector component.
      y - Second vector component.
      z - Third vector component.
      Returns:
      a quaternion instance.

    • of

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

    • of

      public static Quaternion of(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.
      Returns:
      a quaternion instance.

    • conjugate

      public Quaternion conjugate()
      Returns the conjugate of this quaternion number. The conjugate of a + bi + cj + dk is a - bi -cj -dk.
      Returns:
      the conjugate of this quaternion object.

    • 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.

    • dot

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

    • dot

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

    • norm

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

    • normSq

      public double normSq()
      Computes the square of the norm of the quaternion.
      Returns:
      the square of the norm.

    • normalize

      public Quaternion normalize()
      Computes the normalized quaternion (the versor of the instance). The norm of the quaternion must not be near zero.
      Returns:
      a normalized quaternion.
      Throws:
      IllegalStateException - if the norm of the quaternion is NaN, infinite, or near zero.

    • equals

      public boolean equals(Object other)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class 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.

    • isUnit

      public boolean isUnit(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

    • isPure

      public boolean isPure(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.

    • positivePolarForm

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

    • negate

      public Quaternion negate()
      Returns the opposite of this instance.
      Returns:
      the quaternion for which all components have an opposite sign to this one.

    • inverse

      public Quaternion inverse()
      Returns the inverse of this instance. The norm of the quaternion must not be zero.
      Returns:
      the inverse.
      Throws:
      IllegalStateException - if the norm (squared) of the quaternion is NaN, infinite, or near zero.

    • getW

      public double getW()
      Gets the first component of the quaternion (scalar part).
      Returns:
      the scalar part.

    • getX

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

    • getY

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

    • getZ

      public double getZ()
      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:

    • getVectorPart

      public double[] getVectorPart()
      Gets the three components of the vector part of the quaternion.
      Returns:
      the vector part.
      See Also:

    • multiply

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

    • divide

      public Quaternion divide(double alpha)
      Divides the instance by a scalar.
      Parameters:
      alpha - Scalar factor.
      Returns:
      a scaled quaternion.

    • parse

      public static Quaternion parse(String s)
      Parses a string that would be produced by toString() and instantiates the corresponding object.
      Parameters:
      s - String representation.
      Returns:
      an instance.
      Throws:
      NumberFormatException - if the string does not conform to the specification.

    • toString

      public String toString()
      Overrides:
      toString in class Object