Quaternion Class Reference

The Quaternion class is the natural way for representing 3D rotations and orientations. More...

#include <quaternion.h>

List of all members.

Defining a Quaternion

 Quaternion ()
 Default Quaternion, a null rotation.

 Quaternion (const Vec &axis, const double angle)
 Simple constructor with any axis and angle (in radians).

 Quaternion (const Vec &v, const double sin_ha, const double cos_ha)
 Constructor with normalized axis, cos & sin of half angle.

 Quaternion (const double q0, const double q1, const double q2, const double q3)
 Constructor from the values (v*sin(a/2), cos(a/2)) of a Quaternion.

 Quaternion (const Vec &from, const Vec &to)
 Constructs a Quaternion that will rotate from the from direction to the to direction.

Quaternionoperator= (const Quaternion &Q)
 Equal operator.

 Quaternion (const Quaternion &Q)
 Copy constructor.

void setAxisAngle (const Vec &v, const double angle)
 To reset a Quaternion to the rotation of axis v and angle angle (in radians).

void setValue (const double q0, const double q1, const double q2, const double q3)
 Set the current Quaternion value.

void setFromRotationMatrix (const float m[3][3])
void setFromRotatedBase (const Vec &X, const Vec &Y, const Vec &Z)

Access values

Vec axis () const
float angle () const
void getAxisAngle (Vec &axis, float &angle) const
double operator[] (int i) const
 Bracket operator, with a constant return value.

double & operator[] (int i)
 Bracket operator, returns an l-value.


Calculus

Quaternionoperator *= (const Quaternion &q)
Vec inverseRotate (const Vec &v) const
 Vec v is applied the inverse Quaternion rotation (inverseRotate() * rotate() is the identity).

Vec rotate (const Vec &v) const
 Vec v is rotated by the Quaternion rotation (see also inverseRotate()).

const Quaternion operator * (const Quaternion &a, const Quaternion &b)
const Vec operator * (const Quaternion &a, const Vec &b)
 Same as a.rotate(b).


Inversion

Quaternion inverse () const
void invert ()
void negate ()
double normalize ()

Associated matrix

const GLdouble * matrix () const
void getMatrix (GLdouble m[4][4]) const
void getMatrix (GLdouble m[16]) const
void getRotationMatrix (float m[3][3]) const
const GLdouble * inverseMatrix () const
void getInverseMatrix (GLdouble m[4][4]) const
void getInverseMatrix (GLdouble m[16]) const
void getInverseRotationMatrix (float m[3][3]) const

Slerp rotation interpolation

Quaternion log ()
Quaternion exp ()
Quaternion slerp (const Quaternion &a, const Quaternion &b, float t, bool allowFlip=true)
Quaternion squad (const Quaternion &a, const Quaternion &tgA, const Quaternion &tgB, const Quaternion &b, float t)
double dot (const Quaternion &a, const Quaternion &b)
Quaternion lnDif (const Quaternion &a, const Quaternion &b)
Quaternion squadTangent (const Quaternion &a, const Quaternion &b, const Quaternion &c)

XML representation

QDomElement domElement (const QString &name, QDomDocument &doc) const
void initFromDOMElement (const QDomElement &de)

Random orientation

Quaternion randomOrientation ()


Detailed Description

The Quaternion class is the natural way for representing 3D rotations and orientations.

A Quaternion is a clean representation of a 3D rotation matrix or of an orientation. In this implementation, the Quaternion are supposed to be normalized, so that the inverse() is actually a conjugate function.

Many tools are provided define a 3D rotation (constructors, setAxisAngle(), setFromRotationMatrix(), setFromRotatedBase()...). Apply the rotation to 3D points using rotate() and inverseRotate(). Also consider the Frame coordinate system conversion functions like Frame::coordinatesOf() and Frame::coordinatesOfFrom().

The Quaternion corresponding to a rotation vector v, with an angle alpha is :

  {q[0],q[1],q[2]} = sin(alpha/2) * {v[0],v[1],v[2]}
  q[3] = cos(alpha/2)

Quaternion is a QGLViewer internal class. It is part of the qglviewer namespace. You can use it in your programs by specifying qglviewer::Quaternion, or by using the qglviewer namespace :

  using namespace qglviewer;
See also the Vec and the Frame documentation.


Constructor & Destructor Documentation

Quaternion const double  q0,
const double  q1,
const double  q2,
const double  q3
[inline, explicit]
 

Constructor from the values (v*sin(a/2), cos(a/2)) of a Quaternion.

Attention:
To create an identity Quaternion, you should call Quaternion(0,0,0,1). Setting these four value to 0.0 would result in a non unitary Quaternion.


Member Function Documentation

float angle  )  const
 

Returns the angle (in radians) of the rotation represented by the Quaternion. See also axis() and getAxisAngle().

Note:
Returned value is in the range [0-pi]. Larger rotational angles are obtained by inverting the axis direction. See also axis().

Vec axis  )  const
 

Returns the axis of the rotation represented by the Quaternion. The axis may be null for an identity rotation. See also angle() and getAxisAngle().

QDomElement domElement const QString &  name,
QDomDocument &  doc
const
 

Creates an XML QDomElement that represents the Quaternion. name is the name of the QDomElement tag. You need to provide the QDomDocument doc that will hold the resulting element. Typical usage would be:

 QDomDocument doc("myDocument");
 Quaternion sunQuat;
 // ...
 anyNode.addElement(sunQuat.domElement("sunOrientation", doc));
 // ...
Use initFromDOMElement() to restore the Quaternion state from the resulting domElement.

See also Vec::domElement(), Camera::domElement(), KeyFrameInterpolator::domElement()...

double dot const Quaternion a,
const Quaternion b
[inline, static]
 

Return a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3]. See also negate() and slerp().

Quaternion exp  ) 
 

Returns the exponential of the Quaternion. See also log().

void getAxisAngle Vec axis,
float &  angle
const
 

Returns the axis and the angle (in radians) of the rotation represented by the Quaternion. See also axis() and angle().

void getInverseMatrix GLdouble  m[16]  )  const
 

double[16] parameter version of inverseMatrix(). See also getMatrix().

void getInverseMatrix GLdouble  m[4][4]  )  const
 

double[4][4] parameter version of inverseMatrix(). See also getMatrix().

void getInverseRotationMatrix float  m[3][3]  )  const
 

m is set to the 3x3 inverse rotation matrix associated with the Quaternion.

Attention:
This is the classical mathematical rotation matrix. The openGL format uses its transposed version. See inverseMatrix() and getInverseMatrix().

void getMatrix GLdouble  m[16]  )  const
 

double[16] parameter version of matrix(). See also getInverseMatrix() and Frame::getMatrix().

void getMatrix GLdouble  m[4][4]  )  const
 

double[4][4] parameter version of matrix(). See also getInverseMatrix() and Frame::getMatrix().

void getRotationMatrix float  m[3][3]  )  const
 

m is set to the 3x3 rotation matrix associated with the Quaternion.

Attention:
This is the classical mathematical rotation matrix. The openGL format uses its transposed version. See also matrix(), getInverseRotationMatrix() and getMatrix().

void initFromDOMElement const QDomElement &  de  ) 
 

Restore the Quaternion state from a QDomElement created by domElement(). The QDomElement must contain the q0, q1 , q2 and q3 attributes, otherwise these fields are set to 0.0, 0.0, 0.0, 1.0 (identity Quaternion) .

Quaternion inverse  )  const [inline]
 

Returns the inverse of the Quaternion (axis() is negated), which represents the opposite orientation. The original Quaternion is not modified. Use invert() to actually modify the Quaternion.

const GLdouble * inverseMatrix  )  const
 

Returns the associated 4x4 OpenGL inverse rotation matrix. This is simply the matrix() of the inverse().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getInverseRotationMatrix() instead.

The result is only valid until the next call to inverseMatrix(). Use it immediately (as in glLoadMatrixd(q.inverseMatrix()) or store it in an other variable. Consider using getInverseMatrix() if needed.

void invert  )  [inline]
 

Inverse the Quaternion (same rotation angle, but opposite axis). The new orientation is the inverse (in the mathematical sense) of the previous one. The rotation represented by this Quaternion is now the inverse rotation. See also inverse().

Quaternion lnDif const Quaternion a,
const Quaternion b
[static]
 

Returns log(a. inverse() * b). Useful for squadTangent().

Quaternion log  ) 
 

Returns the logarithm of the Quaternion. See also exp().

const GLdouble * matrix  )  const
 

Returns the Quaternion associated 4x4 OpenGL rotation matrix. Can be used with glMultMatrixd(q.matrix()) or glLoadMatrixd(q.matrix()).

 Vec From,To;
 // Set the From and To directions
 ...
 // Computes a Quaternion which transform From in To
 Quaternion q(From, To);
 // Rotates the current openGL matrix.
 glMultMatrixd(q.matrix());

See also getMatrix(), getRotationMatrix() and inverseMatrix().

Attention:
The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getRotationMatrix() instead.

The result is only valid until the next call to matrix(). Use it immediately (as in glLoadMatrixd(q.matrix()) or glLoadMatrixd(q.matrix())) or store it in an other variable. Consider using getMatrix() if needed.

void negate  )  [inline]
 

Negate all the coefficients of the Quaternion. The axis and angle are negated. However, the result of axis() and angle() are unchanged, as it is just an other representation of the same Quaternion (see angle(), which always returns a value in [0,pi]). Useful for Quaternion interpolation, so that the spherical interpolation takes the shortest path. See also slerp(), squad(), dot().

double normalize  )  [inline]
 

Normalize the Quaternion. Should not need to be called as we only deal with unit Quaternion. Useful to prevent numerical drifts, especially with small rotational increments.

Quaternion& operator *= const Quaternion q  )  [inline]
 

Quaternion is composed with q.

Attention:
For efficiency reasons, the resulting Quaternion is not normalized. You may normalize() the quaternion after each application in case of numerical drift.

Quaternion randomOrientation  )  [static]
 

Returns a random unit Quaternion. A randomly directed unit vector can then be computed using :

Vec randomDir = Quaternion::randomOrientation() * Vec(1.0, 0.0, 0.0); // or any other Vec

Note:
This function uses rand() to create pseudo-random numbers and the random number generator can be initialized using srand().

void setFromRotatedBase const Vec X,
const Vec Y,
const Vec Z
 

Same as setFromRotationMatrix(), but the input are the three orthogonal axis of a rotated basis: X, Y and Z.

void setFromRotationMatrix const float  m[3][3]  ) 
 

Set the Quaternion from a (supposedly correct) 3x3 rotation matrix.

Use setFromRotatedBase() a fill the three columns of the matrix with your basis vectors in order to to set a Quaternion from the three axis of a rotated frame.

Quaternion slerp const Quaternion a,
const Quaternion b,
float  t,
bool  allowFlip = true
[static]
 

Returns the slerp interpolation of Quaternion a and b, at time t (in [0,1]). Result is when t=0 and when t=1.

When allowFlip is true (default) the slerp interpolation will always use the "shortest path" between the Quaternions' orientations, by "flipping" the source Quaternion if needed.

Quaternion squad const Quaternion a,
const Quaternion tgA,
const Quaternion tgB,
const Quaternion b,
float  t
[static]
 

Returns the slerp interpolation of the two Quaternion a and b, at time t (in [0,1]). The resulting Quaternion is "between" a and b (result is a when t=0 and is when t=1). The interpolation tangent are defined by tgA and tgB (see squadTangent()).

Quaternion squadTangent const Quaternion a,
const Quaternion b,
const Quaternion c
[static]
 

Returns a tangent Quaternion, which enables a smooth spline interpolation of Quaternion with squad().


Friends And Related Function Documentation

const Quaternion operator * const Quaternion a,
const Quaternion b
[friend]
 

Returns the composition of the two rotations (mind the order !).

Attention:
For efficiency reasons, the resulting Quaternion is not normalized. You may normalize() the quaternion after each application in case of numerical drift.


Generated on Wed Jul 7 12:17:47 2004 for libQGLViewer by doxygen 1.3.4