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

Last modified: Wed Jul 4 01:15:21 2012.

# Directory Listing of Routines

# ssl_general/misc/quaternion

- MTOQ
- QANG
- QCOMPOSE
- QCONJ
- QDECOMPOSE
- QDIV
- QDOTP
- QINV
- QMULT
- QNORM
- QNORMALIZE
- QSLERP
- QTOM
- QUATERNION_ROTATION
- 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

    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: pcruce $
     $LastChangedDate: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: pcruce $
     $LastChangedDate: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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/ssl_general/trunk/misc/quaternion/qdotp.pro $

(See ssl_general/misc/quaternion/qdotp.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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

(See ssl_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 abcissa values of the quaternions,an array of
            length N, abcissa values must also be monotonic

            x2: The output abcissa 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, abcissa 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

    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: 2012-01-26 16:59:44 -0800 (Thu, 26 Jan 2012) $
     $LastChangedRevision: 9629 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/misc/quaternion/qslerp.pro $

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

## QTOM

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

    Function: qtom

    Purpose: transforms quaternions into rotation matrices

    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: pcruce $
     $LastChangedDate: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

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

## QUATERNION_ROTATION

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

    Function 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)

    Written by: Davin Larson

     $LastChangedBy: davin-win $
     $LastChangedDate: 2011-02-15 15:07:24 -0800 (Tue, 15 Feb 2011) $
     $LastChangedRevision: 8213 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/misc/quaternion/quaternion_rotation.pro $

(See ssl_general/misc/quaternion/quaternion_rotation.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: 2007-11-11 17:12:08 -0800 (Sun, 11 Nov 2007) $
     $LastChangedRevision: 2027 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/cotrans/cotrans.pro $

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