This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# general/misc/quaternion

- MTOQ
- QANG
- QCOMPOSE
- QCONJ
- QDECOMPOSE
- QDIV
- QDOTP
- QHAM
- QINV
- QMULT
- QNORM
- QNORMALIZE
- QSLERP
- QTOM
- QUATERNION_ROTATION
- QUATERNION_TO_EULER_ANGLES
  returns euler angles
- QVALIDATE

# Routine Descriptions

## MTOQ

[Next Routine] [List of Routines]

    Function: mtoq

    Purpose: transforms a rotation matrix into a quaternion.  If the
    matrix does not perform a rotation, then its behavior may be ill-
    defined

    WARNING!!!! - this routine does not conform to the wikipedia definition.  see warning for qtom.pro

    Inputs: m: a 3x3 element array or an Nx3x3 element array

    Returns: q

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-12-16 13:31:22 -0800 (Wed, 16 Dec 2020) $
     $LastChangedRevision: 29515 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/mtoq.pro $

(See general/misc/quaternion/mtoq.pro)

## QANG

[Previous Routine] [Next Routine] [List of Routines]

    Function: qang,q

    Purpose: calculate the angle of a unit quaternion or an array of unit
    quaternions

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: phi where q = [cos(phi/2),V*sin(phi/2)]
             throws error of failure, because negative one could be
             an acceptable return value

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qang.pro $

(See general/misc/quaternion/qang.pro)

## QCOMPOSE

[Previous Routine] [Next Routine] [List of Routines]

    Function: qcompose,v,theta

    Purpose: compose quaternions from vectors and angles

    Inputs: vec: 3 element array or an Nx3 element array
            theta: an angle or an N element array of angles(in radians)

    Keywords: free: Flag to allow thetas outside [0,pi)

    Returns: a 4 element quaternion or an Nx4 element array of quaternions

    ;Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: egrimes $
     $LastChangedDate: 2017-06-02 10:32:30 -0700 (Fri, 02 Jun 2017) $
     $LastChangedRevision: 23388 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qcompose.pro $

(See general/misc/quaternion/qcompose.pro)

## QCONJ

[Previous Routine] [Next Routine] [List of Routines]

    Function: qconj,q

    Purpose: calculate the conjugate a quaternion or an array of quaternions

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q*

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qconj.pro $

(See general/misc/quaternion/qconj.pro)

## QDECOMPOSE

[Previous Routine] [Next Routine] [List of Routines]

    Function: qdecompose,q

    Purpose: decompose quaternions into axes and angeles

    Inputs: q:  a 4 element quaternion or an Nx4 element array of quaternions

    Returns: a 4 element array with a[0] = angle, and a[1:3] = axis, or
    an Nx4 element array or -1L on failure

    ;Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    As per the euve implementation, if q[0] is outside of the range of
    acos...[-1,1] the value of the quaternion will be turned into an
    identity quaternion...in other words clipped, this seems suspect,
    a better solution may be to wrap the value back into range using
    modular arithmatic, future modifiers of this routine should consider
    adding this.

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qdecompose.pro $

(See general/misc/quaternion/qdecompose.pro)

## QDIV

[Previous Routine] [Next Routine] [List of Routines]

    Function: qdiv,q1,q2

    Purpose: divide q1 by q2, in other words returns a quaternion q3
    s.t. q3*q2 = q1

    Inputs: q1: a 4 element array, or an Nx4 element array, representing quaternion(s)
            q2: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q1/q2, or -1 on failure

    ;Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qdiv.pro $

(See general/misc/quaternion/qdiv.pro)

## QDOTP

[Previous Routine] [Next Routine] [List of Routines]

    Function: qdotp,q1,q2

    Purpose: calculate the dot product of two quaternions or two arrays of quaternions

    Inputs: q1: a 4 element array, or an Nx4 element array, representing quaternion(s)
            q2: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q1.q2, or -1 on failure

    ;Notes:
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    The scalar component can be thought of as the amount of rotation that
    the quaternion performs

    like any vector the if t = the angle between q1 and q2 in 4-space
    the q1.q2 = ||q1||*||q2||*cos(t) where || denotes the norm(length) of
    the quaternion in 4-space

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: aaflores $
     $LastChangedDate: 2012-01-23 16:50:12 -0800 (Mon, 23 Jan 2012) $
     $LastChangedRevision: 9593 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qdotp.pro $

(See general/misc/quaternion/qdotp.pro)

## QHAM

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      qham

    Purpose:
      Calculate the Hamilton product of two quaternions

    Calling Sequence:
      p = qham(q1,q2)

    Input:
      q1: a 4 element array, or an Nx4 element array, representing quaternion(s)
      q2: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Output:
      Returns Hamilton product (q1)(q2) or -1 on failure

    Notes:
      General routine format copied from qdotp
      Represention has q[0] = scalar component
                       q[1] = vector x
                       q[2] = vector y
                       q[3] = vector z

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-02-11 18:04:52 -0800 (Thu, 11 Feb 2016) $
    $LastChangedRevision: 19966 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qham.pro $

(See general/misc/quaternion/qham.pro)

## QINV

[Previous Routine] [Next Routine] [List of Routines]

    Function: qinv,q

    Purpose: calculate the inverse of a quaternion or an array of quaternions

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q^-1

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qinv.pro $

(See general/misc/quaternion/qinv.pro)

## QMULT

[Previous Routine] [Next Routine] [List of Routines]

    Function: qmult,q1,q2

    Purpose: multiply two quaternions or two arrays of quaternions

    Inputs: q1: a 4 element array, or an Nx4 element array, representing quaternion(s)
            q2: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q1*q2, or -1 on failure

    ;Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qmult.pro $

(See general/misc/quaternion/qmult.pro)

## QNORM

[Previous Routine] [Next Routine] [List of Routines]

    Function: qnorm,q

    Purpose: calculate the norm a quaternion or an array of quaternions

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: norm(q): sqrt(a^2+b^2+c^2+d^2) or -1L on fail
                      will be a single element or an N length array

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    This implementation of norm does not apply the squareroot sometimes
    applied to a norm.  If required the sqrt can easily be applied by the user

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qnorm.pro $

(See general/misc/quaternion/qnorm.pro)

## QNORMALIZE

[Previous Routine] [Next Routine] [List of Routines]

    Function: qnormalize

    Purpose: normalize a quaternion or an array of quaternions

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)

    Returns: q/(sqrt(norm(q))) or -1L on fail

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qnormalize.pro $

(See general/misc/quaternion/qnormalize.pro)

## QSLERP

[Previous Routine] [Next Routine] [List of Routines]

    Function: qslerp,q,x1,x2

    Purpose: uses spherical linear interpolation to interpolate
    quaternions between elements of q

    Inputs: q: an Nx4 element array, representing a list of quaternions
    with N > 1, all quaternions must be unit quaternions(ie length/norm = 1)
            x1: The input abscissa values of the quaternions,an array of
            length N, abscissa values must also be monotonic

            x2: The output abscissa values for the quaternions, can have
            as many elements as wanted but must fall on the interval
            [x[0],x[N-1]], an M element array, abscissa values must also
            be monotonic

            geometric(optional): this keyword allows you to specify that
            it use the geometric formula for the slerp. The default
            formula is probably faster and more numerically stable, the
            geometric option is just available for testing
            Testing of the geometric method indicates that the norm of
            the interpolated quaternions strays easily from unit length,
            when it renormalizes results may be destabilized

            eq_tolerance: Set to specify the tolerance used when determining
            whether two numbers are equal (default: 1e-12). This tolerance
            will be used in checking equivalence of:
                    -quaternion lengths
                    -input vs. output abscissae
                    -quaternion direction (inner product)

    Returns: an Mx4 element array of interpolated quaternions or -1L on
    failure

    ;Notes:
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    The scalar component can be thought of as the amount of rotation that
    the quaternion performs

    While the code may seem a little esoteric, it is vectorized and
    provides the most accurate results it can get

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: aaflores $
     $LastChangedDate: 2016-04-05 12:33:56 -0700 (Tue, 05 Apr 2016) $
     $LastChangedRevision: 20724 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qslerp.pro $

(See general/misc/quaternion/qslerp.pro)

## QTOM

[Previous Routine] [Next Routine] [List of Routines]

    Function: qtom

    Purpose: transforms quaternions into rotation matrices
    WARNING!!! It appears that this routine returns the transpose (inverse) of the rotation matrix!
    It differs from the CSPICE library and Wikipedia

    Inputs: a 4 element array representing a quaternion or an Nx4 element
    array representing an array of quaternions

    Returns: a 3x3 matrix or an Nx3x3 array

    Notes: Implementation largely copied from the euve c library for
    quaternions
    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-12-16 13:31:22 -0800 (Wed, 16 Dec 2020) $
     $LastChangedRevision: 29515 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qtom.pro $

(See general/misc/quaternion/qtom.pro)

## QUATERNION_ROTATION

[Previous Routine] [Next Routine] [List of Routines]

    Function quaternion_rotation,v,q
    Usage:  v_prime = quaternion_rotation(v,q)

    Purpose: Rotate a vector v using the quaternion q

    Inputs: v: a 3 element array, or an Nx3 element array, representing the vectors
            q: a 4 element array, or an Nx4 element array, representing UNIT quaternion(s)

    Alternatively- If last_index=1 then:
                  arrays can be v: 3xN element array
                                Q: 4xN element array

    Written by: Davin Larson

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-12-16 13:29:21 -0800 (Wed, 16 Dec 2020) $
     $LastChangedRevision: 29514 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/quaternion_rotation.pro $

(See general/misc/quaternion/quaternion_rotation.pro)

## QUATERNION_TO_EULER_ANGLES

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  quaternion_to_euler_angles,quaternion
    PURPOSE:
      returns euler angles
      (This function may be used with the "fit" curve fitting procedure.)

    KEYWORDS:
      PARAMETERS: a structure that contain the parameters that define the gaussians
         If this parameter is not a structure then it will be created.

    Written by: Davin Larson  2020-11-28

     $LastChangedBy:  $
     $LastChangedDate: 2020-11-29 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision:  $
     $URL: svn+/general/m.pro $

(See general/misc/quaternion/quaternion_to_euler_angles.pro)

## QVALIDATE

[Previous Routine] [List of Routines]

    Function: qvalidate,q,argname,fxname

    Purpose: validate inputs for the idl quaternion library

    Inputs: q: a 4 element array, or an Nx4 element array, representing quaternion(s)
            argname: the name of the argument to be used in error messages

    Returns: an Nx4 array or -1, it will turn 4 element quaternion arrays
             into 1x4 element quaternion arrays

    Notes: This function is here because I noticed a lot of the error
    checking code was being repeated, and it was making the functions
    long and hard to read

    Represention has q[0] = scalar component
                     q[1] = vector x
                     q[2] = vector y
                     q[3] = vector z

    The vector component of the quaternion can also be thought of as
    an eigenvalue of the rotation the quaterion performs

    Written by: Patrick Cruce(pcruce@igpp.ucla.edu)

     $LastChangedBy: pcruce $
     $LastChangedDate: 2016-10-14 11:01:12 -0700 (Fri, 14 Oct 2016) $
     $LastChangedRevision: 22098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/quaternion/qvalidate.pro $

(See general/misc/quaternion/qvalidate.pro)