Package jahuwaldt.js.param

Class Quaternion

  • All Implemented Interfaces:
    Rotation<Quaternion>, java.io.Serializable, javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, javolution.xml.XMLSerializable
    public final class Quaternion
extends AbstractRotation<Quaternion>
implements javolution.xml.XMLSerializable

    This class represents a 4 element quaternion made up of Float64 elements. Quaternions may be used to represents a relative attitude (attitude transformation) between two different reference frames; B wrt A or BA. It can be used to transform coordinates in reference frame A to reference frame B (A2B).

    The following quaternion definition is used: 

          q.x = e.x * sin(phi/2);
      q.y = e.y * sin(phi/2);
      q.z = e.z * sin(phi/2);
      q.w = cos(phi/2);

    Reference: Glaese, John, "Quaternions -- A Brief Exposition", Rev. 2, NASA MSFC, 1974 and
    Farrell, Jay A. and Matthew Barth, "The Global Positioning System & Inertial Navigation", pp. 39 - 42.

    Modified by: Joseph A. Huwaldt

    Version:
    February 22, 2025
    Author:
    Joseph A. Huwaldt Date: January 28, 2009
    See Also:
    Serialized Form

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static int W
      The index to the scalar W component of this quaternion.
      static int X
      The index to the vector X component of this quaternion.
      static int Y
      The index to the vector Y component of this quaternion.
      static int Z
      The index to the vector Z component of this quaternion.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      Quaternion conjugate()
      Returns the conjugate or spatial inverse of this quaternion.
      Quaternion copy()
      Returns a copy of this quaternion allocated by the calling thread (possibly on the stack).
      Quaternion divide​(Rotation<?> that)
      Returns the quaternion division of this quaternion with the specified rotation transform.
      boolean equals​(java.lang.Object obj)
      Compares this Quaternion against the specified object for strict equality (same rotation type and same values).
      Float64 get​(int i)
      Returns the value of an element from this quaternion (0=x, 1=y, 2=z, 3=w).
      Float64 getScalar()
      Return the scalar part of this quaternion.
      double getScalarValue()
      Return the scalar part of this quaternion as a floating point number.
      double getValue​(int i)
      Returns the value of a floating point number from this quaternion (0=x, 1=y, 2=z, 3=w).
      Vector3D<javax.measure.quantity.Dimensionless> getVector()
      Returns the vector part of this quaternion.
      int hashCode()
      Returns the hash code for this rotation.
      Quaternion inverse()
      Returns the quaternion inverse of this quaternion.
      boolean isApproxEqual​(Rotation<?> obj)
      Compares this Rotation against the specified Rotation for approximate equality (a Rotation object with rotation is equal to this one to within the numerical roundoff tolerance).
      static void main​(java.lang.String[] args)
      Tests the methods in this class.
      Quaternion minus​(Quaternion that)
      Returns the difference between this quaternion and the one specified.
      Float64 norm()
      Returns the Euclidian norm, magnitude, or length of this quaternion (square root of the dot product of this quaternion and it's conjugate).
      double normValue()
      Returns the norm(), magnitude, or length value of this quaternion.
      static Float64Matrix omega​(Vector3D<javax.measure.quantity.AngularVelocity> w)
      Compute the angular velocity quaternion matrix (Omega) from an angular velocity vector of three-space.
      Quaternion opposite()
      Returns the negation of this quaternion (all elements are multiplied by -1).
      Quaternion plus​(Quaternion that)
      Returns the sum of this quaternion with the one specified.
      Quaternion times​(double k)
      Returns the product of this quaternion with the specified coefficient.
      Quaternion times​(Rotation<?> that)
      Returns the quaternion product of this quaternion with the specified rotation transform.
      Quaternion times​(Float64 k)
      Returns the product of this quaternion with the specified coefficient.
      DCMatrix toDCM()
      Returns a direction cosine transformation matrix from this quaternion.
      Float64Vector toFloat64Vector()
      Returns the values stored in this vector as a Float64Vector with the values ordered (x, y, z, w).
      Float64Matrix toLeftMatrix()
      Returns a 4x4 matrix version of this quaternion used to multiply on the left (q*p = Lq*p) where "Lq" is the matrix returned by this method and "p" is treated as a 4-element column vector.
      Quaternion toQuaternion()
      Returns a quaternion representing this attitude transformation.
      Float64Matrix toRightMatrix()
      Returns a 4x4 matrix version of this quaternion used to multiply on the right (p*q = p*Rq) where "Rq" is the matrix returned by this method and "p" is treated as a 4-element column vector.
      javolution.text.Text toText()
      Returns the text representation of this quaternion.
      Quaternion toUnit()
      Returns this quaternion with unit length (a versor).
      <Q extends javax.measure.quantity.Quantity>
      Vector3D<Q>      		 transform​(Coordinate3D<Q> v)
      Transforms a 3D vector from frame A to B using this quaternion.
      Quaternion transpose()
      Returns the spatial inverse of this transformation: AB rather than BA.
      static Quaternion valueOf​(double[] values)
      Returns a Quaternion instance holding the specified double values for the quaternion elements in the order (x, y, z, w).
      static Quaternion valueOf​(double x, double y, double z, double w)
      Returns a Quaternion instance holding the specified double values for the quaternion elements.
      static Quaternion valueOf​(Rotation<?> transform)
      Returns a new Quaternion instance constructed from the specified rotation transform.
      static Quaternion valueOf​(Vector3D<javax.measure.quantity.Dimensionless> vector, double scalar)
      Returns a Quaternion instance containing the specified unit vector and scalar.
      static Quaternion valueOf​(Vector3D<javax.measure.quantity.Dimensionless> uv, Parameter<javax.measure.quantity.Angle> phi)
      Returns a Quaternion representing a rotation about an arbitrary axis.
      static Quaternion valueOf​(Vector<Float64> vector)
      Returns a Quaternion instance containing the specified vector of Float64 values.

      • Methods inherited from class java.lang.Object

        getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • X

        public static final int X
        The index to the vector X component of this quaternion.
        See Also:
        Constant Field Values

      • Y

        public static final int Y
        The index to the vector Y component of this quaternion.
        See Also:
        Constant Field Values

      • Z

        public static final int Z
        The index to the vector Z component of this quaternion.
        See Also:
        Constant Field Values

      • W

        public static final int W
        The index to the scalar W component of this quaternion.
        See Also:
        Constant Field Values

    • Method Detail

      • valueOf

        public static Quaternion valueOf​(double x,
                                 double y,
                                 double z,
                                 double w)
        Returns a Quaternion instance holding the specified double values for the quaternion elements.
        Parameters:
        x - the x value.
        y - the y value.
        z - the z value.
        w - the w value.
        Returns:
        The quaternion having the specified values.

      • valueOf

        public static Quaternion valueOf​(double[] values)
        Returns a Quaternion instance holding the specified double values for the quaternion elements in the order (x, y, z, w).
        Parameters:
        values - A 4 element array of quaternion elements (x, y, z, w).
        Returns:
        The quaternion having the specified values.
        Throws:
        DimensionException - if the input array does not have 4 elements.

      • valueOf

        public static Quaternion valueOf​(Vector3D<javax.measure.quantity.Dimensionless> vector,
                                 double scalar)
        Returns a Quaternion instance containing the specified unit vector and scalar.
        Parameters:
        vector - The unit vector part of the quaternion.
        scalar - The scalar part of the quaternion.
        Returns:
        The quaternion having the specified values.

      • valueOf

        public static Quaternion valueOf​(Vector<Float64> vector)
        Returns a Quaternion instance containing the specified vector of Float64 values. The vector must have exactly 4 elements in the order (x, y, z, w).
        Parameters:
        vector - The vector of Float64 quaternion element values (must have dimension of 4).
        Returns:
        The quaternion having the specified values.
        Throws:
        DimensionException - if the input vector does not have 4 elements.

      • valueOf

        public static Quaternion valueOf​(Vector3D<javax.measure.quantity.Dimensionless> uv,
                                 Parameter<javax.measure.quantity.Angle> phi)
        Returns a Quaternion representing a rotation about an arbitrary axis.
        Parameters:
        uv - The unit vector axis of rotation expressed in a reference frame.
        phi - The rotation angle about the specified rotation axis.
        Returns:
        The quaternion representing the specified rotation angle about the specified rotation axis.

      • valueOf

        public static Quaternion valueOf​(Rotation<?> transform)
        Returns a new Quaternion instance constructed from the specified rotation transform.
        Parameters:
        transform - The Rotation transform to convert to a new quaternion.
        Returns:
        the quaternion representing the specified attitude transform.

      • getVector

        public Vector3D<javax.measure.quantity.Dimensionless> getVector()
        Returns the vector part of this quaternion.
        Returns:
        The vector part of this quaternion.

      • getScalar

        public Float64 getScalar()
        Return the scalar part of this quaternion.
        Returns:
        The scalar part of this quaternion.

      • getScalarValue

        public double getScalarValue()
        Return the scalar part of this quaternion as a floating point number.
        Returns:
        The scalar part of this quaternion as a floating point number.

      • get

        public Float64 get​(int i)
        Returns the value of an element from this quaternion (0=x, 1=y, 2=z, 3=w).
        Parameters:
        i - the dimension index (0=x, 1=y, 2=z, 3=w).
        Returns:
        the value of the element at i.
        Throws:
        java.lang.IndexOutOfBoundsException - (i < 0) || (i >= dimension())

      • getValue

        public double getValue​(int i)
        Returns the value of a floating point number from this quaternion (0=x, 1=y, 2=z, 3=w).
        Parameters:
        i - the floating point number index (0=x, 1=y, 2=z, 3=w).
        Returns:
        the value of the floating point number at i.
        Throws:
        java.lang.IndexOutOfBoundsException - (i < 0) || (i >= dimension())

      • norm

        public Float64 norm()
        Returns the Euclidian norm, magnitude, or length of this quaternion (square root of the dot product of this quaternion and it's conjugate).
        Returns:
        sqrt(this · this^*).

      • normValue

        public double normValue()
        Returns the norm(), magnitude, or length value of this quaternion.
        Returns:
        this.norm().doubleValue().

      • opposite

        public Quaternion opposite()
        Returns the negation of this quaternion (all elements are multiplied by -1).
        Returns:
        -this.
        See Also:
        conjugate()

      • transpose

        public Quaternion transpose()
        Returns the spatial inverse of this transformation: AB rather than BA. This implementation returns the conjugate of this quaternion.
        Specified by:
        transpose in interface Rotation<Quaternion>
        Returns:
        this' = this^*

      • plus

        public Quaternion plus​(Quaternion that)
        Returns the sum of this quaternion with the one specified.
        Parameters:
        that - the quaternion to be added.
        Returns:
        this + that.

      • minus

        public Quaternion minus​(Quaternion that)
        Returns the difference between this quaternion and the one specified.
        Parameters:
        that - the quaternion to be subtracted.
        Returns:
        this - that.

      • times

        public Quaternion times​(Float64 k)
        Returns the product of this quaternion with the specified coefficient.
        Parameters:
        k - the coefficient multiplier.
        Returns:
        this · k

      • times

        public Quaternion times​(double k)
        Returns the product of this quaternion with the specified coefficient.
        Parameters:
        k - the coefficient multiplier.
        Returns:
        this times k

      • times

        public Quaternion times​(Rotation<?> that)
        Returns the quaternion product of this quaternion with the specified rotation transform. If this quaternion is BA and that is AC then the returned value is: BC = BA times AC (or C2B = A2B times C2A).
        Specified by:
        times in interface Rotation<Quaternion>
        Parameters:
        that - the rotation transform multiplier.
        Returns:
        this times that

      • divide

        public Quaternion divide​(Rotation<?> that)
        Returns the quaternion division of this quaternion with the specified rotation transform.
        Parameters:
        that - the rotation transform divisor.
        Returns:
        this / that = this times that^-1

      • inverse

        public Quaternion inverse()
        Returns the quaternion inverse of this quaternion.
        Returns:
        this^-1 = this^* / norm(this)^2

      • transform

        public <Q extends javax.measure.quantity.Quantity> Vector3D<Q> transform​(Coordinate3D<Q> v)
        Transforms a 3D vector from frame A to B using this quaternion.
        Specified by:
        transform in interface Rotation<Quaternion>
        Type Parameters:
        Q - The Quantity or unit type for this parameter.
        Parameters:
        v - the vector expressed in frame A.
        Returns:
        the vector expressed in frame B.

      • toUnit

        public Quaternion toUnit()
        Returns this quaternion with unit length (a versor).
        Returns:
        this.divide(norm(this))

      • toFloat64Vector

        public Float64Vector toFloat64Vector()
        Returns the values stored in this vector as a Float64Vector with the values ordered (x, y, z, w). The scalar is in the 4th element.
        Returns:
        The values stored in this vector as a Float64Vector with the values ordered (x, y, z, w).

      • omega

        public static Float64Matrix omega​(Vector3D<javax.measure.quantity.AngularVelocity> w)

        Compute the angular velocity quaternion matrix (Omega) from an angular velocity vector of three-space. Used to propagate quaternions: qdot = Omega * q ==> Float64Vector qdot = Quaternion.omega(w).times(q.toFloat64Vector());

        Values are ordered as follows: 

           M = 0.5* {   0   r  -q   p,  = { [Omega]' |  [w] }   where [Omega] = skewsym([w])
               -r   0   p   q,    {-----------------}         and [w] = [p q r]' = ang. vel. vect.
                q  -p   0   r,    {    -[w]  |   0  }
               -p  -q  -r   0}
        Parameters:
        w - The angular velocity vector [p q r]'.
        Returns:
        A 4x4 angular velocity quaternion matrix in units of radians/second.

      • toLeftMatrix

        public Float64Matrix toLeftMatrix()
        Returns a 4x4 matrix version of this quaternion used to multiply on the left (q*p = Lq*p) where "Lq" is the matrix returned by this method and "p" is treated as a 4-element column vector. Values are ordered as follows: 
          M = {  w  -z   y   x,  = { w*[E] + [Q]  |  [q]  }   where [Q] = skewsym([q])  and [q] = q.getVector()
         z   w  -x   y,    {----------------------}         [E] = identity matrix
        -y   x   w   z,    {      -[q]    |   w   }
        -x  -y  -z   w}
        Returns:
        4x4 Lq matrix such that Lq.times(p.toFloat64Vector()) == q.times(p).toFloat64Vector()

      • toRightMatrix

        public Float64Matrix toRightMatrix()
        Returns a 4x4 matrix version of this quaternion used to multiply on the right (p*q = p*Rq) where "Rq" is the matrix returned by this method and "p" is treated as a 4-element column vector. Values are ordered as follows: 
          M = {  w   z  -y   x,  = { w*[E] + [Q]' |  [q]  }   where [Q] = skewsym([q])  and [q] = q.getVector()
        -z   w   x   y,    {----------------------}         [E] = identity matrix
         y  -x   w   z,    {      -[q]    |   w   }
        -x  -y  -z   w}
        Returns:
        4x4 Rq matrix such that Rq.times(p.toFloat64Vector()) == p.times(q.toFloat64Vector()).toFloat64Vector()

      • copy

        public Quaternion copy()
        Returns a copy of this quaternion allocated by the calling thread (possibly on the stack).
        Specified by:
        copy in interface Rotation<Quaternion>
        Specified by:
        copy in interface javolution.lang.ValueType
        Returns:
        an identical and independent copy of this quaternion.

      • toText

        public javolution.text.Text toText()
        Returns the text representation of this quaternion.
        Specified by:
        toText in interface javolution.lang.Realtime
        Returns:
        the text representation of this quaternion.

      • isApproxEqual

        public boolean isApproxEqual​(Rotation<?> obj)
        Compares this Rotation against the specified Rotation for approximate equality (a Rotation object with rotation is equal to this one to within the numerical roundoff tolerance).
        Overrides:
        isApproxEqual in class AbstractRotation<Quaternion>
        Parameters:
        obj - the Rotation object to compare with.
        Returns:
        true if this Rotation is approximately identical to that Rotation; false otherwise.

      • equals

        public boolean equals​(java.lang.Object obj)
        Compares this Quaternion against the specified object for strict equality (same rotation type and same values).
        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - the object to compare with.
        Returns:
        true if this rotation is identical to that rotation; false otherwise.

      • hashCode

        public int hashCode()
        Returns the hash code for this rotation.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value.

      • main

        public static void main​(java.lang.String[] args)
        Tests the methods in this class.
        Parameters:
        args - the command-line arguments.