SF2 C++ FRC Class Library
Sensor Fusion Framework (SF2) for FRC
Classes | Public Member Functions | Static Public Member Functions | List of all members
Quaternion Class Reference

The Quaternion class provides methods to operate on a quaternion. More...

#include <Quaternion.h>

Inheritance diagram for Quaternion:
ICopy< Quaternion > IQuantity

Public Member Functions

 Quaternion ()
 Constructs a Quaternion instance, using default values for a Unit Quaternion.
 
 Quaternion (const Quaternion &src)
 Constructs a Quaternion instance, using values from another Quaternion instance. More...
 
 Quaternion (float w, float x, float y, float z)
 Constructs a Quaternion instance, using the provides w, x, y and z valuese. More...
 
void set (float w, float x, float y, float z)
 Modifies the Quaternion by setting the component W, X, Y and Z value. More...
 
void set (const Quaternion &src)
 Modifes the Quaternion to be equal to the provided Quaternion. More...
 
void getYawPitchRollRadians (FloatVectorStruct &ypr)
 Extracts the yaw, pitch and roll values from the Quaternion. More...
 
void getYawRadians (Scalar &yaw)
 Extracts the yaw angle value from the Quaternion. More...
 
void getPitch (Scalar &pitch)
 Extracts the pitch angle value from the Quaternion. More...
 
void getRoll (Scalar &roll)
 Extracts the roll angle value from the Quaternion. More...
 
void conjugate ()
 Modifies the Quaternion to be its complex conjugate. More...
 
void inverse ()
 Modifies the Quaternion to be its inverse (reciprocal). More...
 
void multiply (const Quaternion &q)
 Modifies this quaternion (the multiplicand) to be the product of multiplication by a multiplier Quaternion. More...
 
void divide (float s)
 Modifies a quaternion, scaling it by the provided parameter. More...
 
float dotProduct (const Quaternion &q1, const Quaternion &q2)
 
float getW ()
 Accessor for the Quaternion's W component value. More...
 
float getX ()
 Accessor for the Quaternion's X component value. More...
 
float getY ()
 Accessor for the Quaternion's Y component value. More...
 
float getZ ()
 Accessor for the Quaternion's Z component value. More...
 
void interpolate (const Quaternion &to, double time_ratio, Quaternion &out)
 
void copy (Quaternion &t)
 
Quaternioninstantiate_copy ()
 
bool getPrintableString (vector< string > &printable_string)
 
bool getContainedQuantities (vector< IQuantity * > &quantities)
 
bool getContainedQuantityNames (vector< string > &quantity_names)
 

Static Public Member Functions

static void getGravity (FloatVectorStruct &v, const Quaternion &q)
 Extracts the gravity vector from the Quaternion. More...
 
static void getYawPitchRoll (const Quaternion &q, const FloatVectorStruct &gravity, FloatVectorStruct &ypr)
 Extracts the yaw, pitch and roll values from the Quaternion. More...
 
static void slerp (const Quaternion &qa, const Quaternion &qb, double t, Quaternion &out)
 Estimates an intermediate Quaternion given Quaternions representing each end of the path, and an interpolation ratio from 0.0 t0 1.0. More...
 
static void difference (const Quaternion &qa, const Quaternion &qb, Quaternion &q_diff)
 Divides two quaternions. More...
 
static void getUnits (vector< IUnit * > &units)
 

Detailed Description

The Quaternion class provides methods to operate on a quaternion.

Quaternions are used among other things to describe rotation in 3D dimensions. This is typically performed using a Unit Quaternion (also known as a "Versor".

Provided Quaternion operations include basic mathematic operations as well as a method for interpolation.

Quaternions actually describe 4 separate rotations - 3 dimensions of rotation about a coordinate reference frame, and then a fourth rotation of the coodinate reference frame to another reference frame.

At their core, Quaternions are comprised of W, X, Y and Z components, which in the case of the Unit Quaternion are expressed in units of Radians which have a range from -2 to 2.

From a number theory perspecive, a quaternion is a complex number. A quaternion is a formal sum of a real number and real multiples of the symbols i, j, and k. For example,

<t>q = W + Xi + Yj + Zk</t>

A Unit Quaternion can express not only rotations, but also the gravity vector. Therefore, the Quaternion class provides methods for deriving the gravity vector as well as the more commonly-used Yaw, Pitch and Roll angles (also known as Tait/Bryan angles).

Author
Scott

Constructor & Destructor Documentation

Quaternion::Quaternion ( const Quaternion src)
inline

Constructs a Quaternion instance, using values from another Quaternion instance.

Parameters
src- the Quaternion instance used to initialize this Quaternion.
Quaternion::Quaternion ( float  w,
float  x,
float  y,
float  z 
)
inline

Constructs a Quaternion instance, using the provides w, x, y and z valuese.

Parameters
w- the Quaternion W component value.
x- the Quaternion X component value.
y- the Quaternion Y component value.
z- the Quaternion Z component value.

Member Function Documentation

void Quaternion::conjugate ( )
inline

Modifies the Quaternion to be its complex conjugate.

The complex conjugate of a complex number is the number with equal real part and imaginary part equal in magnitude but opposite in sign.

static void Quaternion::difference ( const Quaternion qa,
const Quaternion qb,
Quaternion q_diff 
)
inlinestatic

Divides two quaternions.

Since Quaternion multiplication is not commutative, to perform this operation, the multiplicand Quaternion is multiplied by the inverse of the multiplier Quaternion.

Key point: the result of dividing two Quaternions is to logically subtract their respective rotations. Thus, use difference() to calculate the amount of 3D rotation between two Quaternions.

Parameters
qa- the dividend Quaternion
qb- the divisor Quaternion
q_diff- the resulting quotient Quaternion representing the difference in rotation
void Quaternion::divide ( float  s)
inline

Modifies a quaternion, scaling it by the provided parameter.

Parameters
s- the value by which to divide each Quaternion component value.
static void Quaternion::getGravity ( FloatVectorStruct &  v,
const Quaternion q 
)
inlinestatic

Extracts the gravity vector from the Quaternion.

Parameters
v- the output vector containing the quaternion's gravity component.
q- the source quaternion.
void Quaternion::getPitch ( Scalar pitch)
inline

Extracts the pitch angle value from the Quaternion.

The Return value is in units of Radians.

void Quaternion::getRoll ( Scalar roll)
inline

Extracts the roll angle value from the Quaternion.

The Return value is in units of Radians.

float Quaternion::getW ( )
inline

Accessor for the Quaternion's W component value.

Returns
Quaternion W component value.
float Quaternion::getX ( )
inline

Accessor for the Quaternion's X component value.

Returns
Quaternion X component value.
float Quaternion::getY ( )
inline

Accessor for the Quaternion's Y component value.

Returns
Quaternion Y component value.
static void Quaternion::getYawPitchRoll ( const Quaternion q,
const FloatVectorStruct &  gravity,
FloatVectorStruct &  ypr 
)
inlinestatic

Extracts the yaw, pitch and roll values from the Quaternion.

Returned values are in units of Radians

Parameters
q- the source quaternion
gravity- the gravity component of the quaternion
ypr- a FloatVectorStruct containing the yaw/pitch/roll values extracted from the Quaternion. x: yaw; y: pitch; z: roll.
void Quaternion::getYawPitchRollRadians ( FloatVectorStruct &  ypr)
inline

Extracts the yaw, pitch and roll values from the Quaternion.

Returned values are in units of Radians.

void Quaternion::getYawRadians ( Scalar yaw)
inline

Extracts the yaw angle value from the Quaternion.

The Return value is in units of Radians.

float Quaternion::getZ ( )
inline

Accessor for the Quaternion's Z component value.

Returns
Quaternion Z component value.
void Quaternion::inverse ( )
inline

Modifies the Quaternion to be its inverse (reciprocal).

The quaternion inverse of a rotation is the opposite rotation, so it can be thought of as a mirror image of the original quaternion

void Quaternion::multiply ( const Quaternion q)
inline

Modifies this quaternion (the multiplicand) to be the product of multiplication by a multiplier Quaternion.

Key point: the result of multiplying two Quaternions is to logically add together their respective rotations.

Note that Quaternion multiplication is NOT commutative, in other words when multiplying Quaternions, the result of a * b is NOT the same as b * a.

Parameters
q- the multiplier quaternion.
void Quaternion::set ( float  w,
float  x,
float  y,
float  z 
)
inline

Modifies the Quaternion by setting the component W, X, Y and Z value.

Parameters
w- the Quaternion W component value.
x- the Quaternion X component value.
y- the Quaternion Y component value.
z- the Quaternion Z component value.
void Quaternion::set ( const Quaternion src)
inline

Modifes the Quaternion to be equal to the provided Quaternion.

Parameters
src- the Quaternion instance used to initialize this Quaternion.
static void Quaternion::slerp ( const Quaternion qa,
const Quaternion qb,
double  t,
Quaternion out 
)
inlinestatic

Estimates an intermediate Quaternion given Quaternions representing each end of the path, and an interpolation ratio from 0.0 t0 1.0.

Uses Quaternion SLERP (Spherical Linear Interpolation), an algorithm originally introduced by Ken Shoemake in the context of quaternion interpolation for the purpose of animating 3D rotation. This estimation is based upon the assumption of constant-speed motion along a unit-radius great circle arc.

For more info:

http://www.euclideanspace.com/maths/algebra/realNormedAlgebra/quaternions/slerp/index.htm


The documentation for this class was generated from the following files: