The Quaternion class represents 3D rotations and orientations. More...

#include <QGLViewer/quaternion.h>

Private Attributes
qreal	q [4]

Defining a Quaternion
	Quaternion ()

	Quaternion (const Vec &axis, qreal angle)

	Quaternion (const Vec &from, const Vec &to)

	Quaternion (qreal q0, qreal q1, qreal q2, qreal q3)

	Quaternion (const Quaternion &Q)

Quaternion &	operator= (const Quaternion &Q)

void	setAxisAngle (const Vec &axis, qreal angle)

void	setValue (qreal q0, qreal q1, qreal q2, qreal q3)

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

void	setFromRotatedBase (const Vec &X, const Vec &Y, const Vec &Z)

void	setFromRotationMatrix (const qreal m[3][3])

void	setFromRotatedBasis (const Vec &X, const Vec &Y, const Vec &Z)

Accessing values
Vec	axis () const

qreal	angle () const

void	getAxisAngle (Vec &axis, qreal &angle) const

qreal	operator[] (int i) const

qreal &	operator[] (int i)

Rotation computations
Quaternion &	operator*= (const Quaternion &q)

Vec	rotate (const Vec &v) const

Vec	inverseRotate (const Vec &v) const

Quaternion	operator* (const Quaternion &a, const Quaternion &b)

Vec	operator* (const Quaternion &q, const Vec &v)

Inversion
Quaternion	inverse () const

void	invert ()

void	negate ()

qreal	normalize ()

Quaternion	normalized () const

Associated matrix
const GLdouble *	matrix () const

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

void	getMatrix (GLdouble m[16]) const

void	getRotationMatrix (qreal m[3][3]) const

const GLdouble *	inverseMatrix () const

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

void	getInverseMatrix (GLdouble m[16]) const

void	getInverseRotationMatrix (qreal m[3][3]) const

Slerp interpolation
Quaternion	log ()

Quaternion	exp ()

static Quaternion	slerp (const Quaternion &a, const Quaternion &b, qreal t, bool allowFlip=true)

static Quaternion	squad (const Quaternion &a, const Quaternion &tgA, const Quaternion &tgB, const Quaternion &b, qreal t)

static qreal	dot (const Quaternion &a, const Quaternion &b)

static Quaternion	lnDif (const Quaternion &a, const Quaternion &b)

static Quaternion	squadTangent (const Quaternion &before, const Quaternion &center, const Quaternion &after)

Random Quaternion
static Quaternion	randomQuaternion ()

XML representation
	Quaternion (const QDomElement &element)

QDomElement	domElement (const QString &name, QDomDocument &document) const

void	initFromDOMElement (const QDomElement &element)

Detailed Description

The Quaternion class represents 3D rotations and orientations.

The Quaternion is an appropriate (although not very intuitive) representation for 3D rotations and orientations. Many tools are provided to ease the definition of a Quaternion: see constructors, setAxisAngle(), setFromRotationMatrix(), setFromRotatedBasis().

You can apply the rotation represented by the Quaternion to 3D points using rotate() and inverseRotate(). See also the Frame class that represents a coordinate system and provides other conversion functions like Frame::coordinatesOf() and Frame::transformOf().

You can apply the Quaternion q rotation to the OpenGL matrices using:

glMultMatrixd(q.matrix());

// equvalent to glRotate(q.angle()*180.0/M_PI, q.axis().x, q.axis().y, q.axis().z);

Quaternion is part of the qglviewer namespace, specify qglviewer::Quaternion or use the qglviewer namespace:

using namespace qglviewer;

Internal representation

The internal representation of a Quaternion corresponding to a rotation around axis axis, with an angle alpha is made of four qreals (i.e. doubles) q[i]:

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

q[3] = cos(alpha/2)

Note that certain implementations place the cosine term in first position (instead of last here).

The Quaternion is always normalized, so that its inverse() is actually its conjugate.

See also the Vec and Frame classes' documentations.

Definition at line 66 of file quaternion.h.

Constructor & Destructor Documentation

qglviewer::Quaternion::Quaternion ( )

inline

Default constructor, builds an identity rotation.

Definition at line 72 of file quaternion.h.

qglviewer::Quaternion::Quaternion	(	const Vec &	axis,
		qreal	angle
	)

inline

Constructor from rotation axis (non null) and angle (in radians). See also setAxisAngle().

Definition at line 76 of file quaternion.h.

Quaternion::Quaternion	(	const Vec &	from,
		const Vec &	to
	)

Constructs a Quaternion that will rotate from the from direction to the to direction.

Note that this rotation is not uniquely defined. The selected axis is usually orthogonal to from and to, minimizing the rotation angle. This method is robust and can handle small or almost identical vectors.

Definition at line 35 of file quaternion.cpp.

qglviewer::Quaternion::Quaternion	(	qreal	q0,
		qreal	q1,
		qreal	q2,
		qreal	q3
	)

inline

Constructor from the four values of a Quaternion. First three values are axis*sin(angle/2) and last one is cos(angle/2).

Attention: The identity Quaternion is Quaternion(0,0,0,1) and not Quaternion(0,0,0,0) (which is not unitary). The default Quaternion() creates such identity Quaternion.

Definition at line 88 of file quaternion.h.

qglviewer::Quaternion::Quaternion ( const Quaternion & Q )

inline

Copy constructor.

Definition at line 92 of file quaternion.h.

Quaternion::Quaternion ( const QDomElement & element )

explicit

Constructs a Quaternion from a QDomElement representing an XML code of the form

< anyTagName q0=".." q1=".." q2=".." q3=".." />

If one of these attributes is missing or is not a number, a warning is displayed and the associated value is respectively set to 0, 0, 0 and 1 (identity Quaternion).

See also domElement() and initFromDOMElement().

Definition at line 286 of file quaternion.cpp.

Member Function Documentation

qreal Quaternion::angle ( ) const

Returns the angle (in radians) of the rotation represented by the Quaternion.

This value is always in the range [0-pi]. Larger rotational angles are obtained by inverting the axis() direction.

See also getInverseRotationMatrix().

Attention: m uses the European mathematical representation of the rotation matrix. Use matrix() and getMatrix() to retrieve the OpenGL transposed version.

Definition at line 371 of file quaternion.cpp.

void Quaternion::initFromDOMElement ( const QDomElement & element )

Restores the Quaternion state from a QDomElement created by domElement().

The QDomElement should contain the q0, q1 , q2 and q3 attributes. If one of these attributes is missing or is not a number, a warning is displayed and these fields are respectively set to 0.0, 0.0, 0.0 and 1.0 (identity Quaternion).

See also the Quaternion(const QDomElement&) constructor.

Definition at line 273 of file quaternion.cpp.

Quaternion qglviewer::Quaternion::inverse ( ) const

inline

Returns the inverse Quaternion (inverse rotation).

Result has a negated axis() direction and the same angle(). A composition (see operator*()) of a
Quaternion and its inverse() results in an identity function.

Use invert() to actually modify the Quaternion.

Definition at line 205 of file quaternion.h.

const GLdouble * Quaternion::inverseMatrix ( ) const

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

Attention: The result is only valid until the next call to inverseMatrix(). Use it immediately (as in glMultMatrixd(q.inverseMatrix())) or use getInverseMatrix() instead.; The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getInverseRotationMatrix() instead.

Definition at line 389 of file quaternion.cpp.

Vec Quaternion::inverseRotate ( const Vec & v ) const

Returns the image of v by the Quaternion inverse() rotation.

rotate() performs an inverse transformation. Same as inverse().rotate(v).

Definition at line 68 of file quaternion.cpp.

void qglviewer::Quaternion::invert ( )

inline

Inverses the Quaternion (same rotation angle(), but negated axis()).

See also inverse().

Definition at line 210 of file quaternion.h.

Quaternion Quaternion::lnDif	(	const Quaternion &	a,
		const Quaternion &	b
	)

static

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

Definition at line 503 of file quaternion.cpp.

Quaternion Quaternion::log ( )

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

Definition at line 475 of file quaternion.cpp.

const GLdouble * Quaternion::matrix ( ) const

Returns the Quaternion associated 4x4 OpenGL rotation matrix.

Use glMultMatrixd(q.matrix()) to apply the rotation represented by Quaternion q to the current OpenGL matrix.

Attention: The result is only valid until the next call to matrix(). Use it immediately (as shown above) or consider using getMatrix() instead.; The matrix is given in OpenGL format (row-major order) and is the transpose of the actual mathematical European representation. Consider using getRotationMatrix() instead.

Definition at line 306 of file quaternion.cpp.

void qglviewer::Quaternion::negate ( )

inline

Negates all the coefficients of the Quaternion.

This results in an other representation of the \e same rotation (opposite rotation angle, but with
a negated axis direction: the two cancel out). However, note that the results of axis() and
angle() are unchanged after a call to this method since angle() always returns a value in [0,pi].

This method is mainly useful for Quaternion interpolation, so that the spherical
interpolation takes the shortest path on the unit sphere. See slerp() for details.

Definition at line 220 of file quaternion.h.

qreal qglviewer::Quaternion::normalize ( )

inline

Normalizes the Quaternion coefficients.

This method should not need to be called since we only deal with unit Quaternions. This is however
useful to prevent numerical drifts, especially with small rotational increments. See also
normalized().

Definition at line 227 of file quaternion.h.

Quaternion qglviewer::Quaternion::normalized ( ) const

inline

Returns a normalized version of the Quaternion.

See also normalize().

Definition at line 238 of file quaternion.h.

Quaternion& qglviewer::Quaternion::operator*= ( const Quaternion & q )

inline

Quaternion rotation is composed with q.

See operator*(), since this is equivalent to \c this = \c this * \p q.

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

Definition at line 178 of file quaternion.h.

Quaternion& qglviewer::Quaternion::operator= ( const Quaternion & Q )

inline

Equal operator.

Definition at line 96 of file quaternion.h.

qreal qglviewer::Quaternion::operator[] ( int i ) const

inline

Bracket operator, with a constant return value. i must range in [0..3]. See the Quaternion(qreal, qreal, qreal, qreal) documentation.

Definition at line 144 of file quaternion.h.

qreal& qglviewer::Quaternion::operator[] ( int i )

inline

Bracket operator returning an l-value. i must range in [0..3]. See the Quaternion(qreal, qreal, qreal, qreal) documentation.

Definition at line 147 of file quaternion.h.

Quaternion Quaternion::randomQuaternion ( )

static

Returns a random unit Quaternion.

You can create a randomly directed unit vector using:

Vec randomDir = Quaternion::randomQuaternion() * 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().

Definition at line 542 of file quaternion.cpp.

Vec Quaternion::rotate ( const Vec & v ) const

Returns the image of v by the Quaternion rotation.

Definition at line 76 of file quaternion.cpp.

void qglviewer::Quaternion::setAxisAngle	(	const Vec &	axis,
		qreal	angle
	)

inline

Sets the Quaternion as a rotation of axis axis and angle angle (in radians).

\p axis does not need to be normalized. A null \p axis will result in an identity Quaternion.

Definition at line 106 of file quaternion.h.

void Quaternion::setFromRotatedBase	(	const Vec &	X,
		const Vec &	Y,
		const Vec &	Z
	)

Definition at line 163 of file quaternion.cpp.

void Quaternion::setFromRotatedBasis	(	const Vec &	X,
		const Vec &	Y,
		const Vec &	Z
	)

Sets the Quaternion from the three rotated vectors of an orthogonal basis.

The three vectors do not have to be normalized but must be orthogonal and direct (X^Y=k*Z, with k>0).

Quaternion q;
q.setFromRotatedBasis(X, Y, Z);
// Now q.rotate(Vec(1,0,0)) == X and q.inverseRotate(X) == Vec(1,0,0)
// Same goes for Y and Z with Vec(0,1,0) and Vec(0,0,1).

Definition at line 182 of file quaternion.cpp.

void Quaternion::setFromRotationMatrix ( const float m[3][3] )

Definition at line 151 of file quaternion.cpp.

void Quaternion::setFromRotationMatrix ( const qreal m[3][3] )

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

The matrix is expressed in European format: its three columns are the images by the rotation of the three vectors of an orthogonal basis. Note that OpenGL uses a symmetric representation for its matrices.

setFromRotatedBasis() sets a Quaternion from the three axis of a rotated frame. It actually fills the three columns of a matrix with these rotated basis vectors and calls this method.

Definition at line 104 of file quaternion.cpp.

void qglviewer::Quaternion::setValue	(	qreal	q0,
		qreal	q1,
		qreal	q2,
		qreal	q3
	)

inline

Sets the Quaternion value. See the Quaternion(qreal, qreal, qreal, qreal) constructor documentation.

Definition at line 125 of file quaternion.h.

Quaternion Quaternion::slerp	(	const Quaternion &	a,
		const Quaternion &	b,
		qreal	t,
		bool	allowFlip = `true`
	)

static

Returns the slerp interpolation of Quaternions a and b, at time t.

t should range in [0,1]. Result is a when t=0 and b 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 (see negate()).

Definition at line 433 of file quaternion.cpp.

Quaternion Quaternion::squad	(	const Quaternion &	a,
		const Quaternion &	tgA,
		const Quaternion &	tgB,
		const Quaternion &	b,
		qreal	t
	)

static

Returns the slerp interpolation of the two Quaternions a and b, at time t, using tangents tgA and tgB.

The resulting Quaternion is "between" a and b (result is a when t=0 and b for t=1).

Use squadTangent() to define the Quaternion tangents tgA and tgB.

Definition at line 467 of file quaternion.cpp.

Quaternion Quaternion::squadTangent	(	const Quaternion &	before,
		const Quaternion &	center,
		const Quaternion &	after
	)

static

Returns a tangent Quaternion for center, defined by before and after Quaternions.

Useful for smooth spline interpolation of Quaternion with squad() and slerp().

Definition at line 513 of file quaternion.cpp.

Friends And Related Function Documentation

Quaternion operator*	(	const Quaternion &	a,
		const Quaternion &	b
	)

friend

Returns the composition of the a and b rotations.

The order is important. When applied to a Vec \c v (see operator*(const Quaternion&, const Vec&)
and rotate()) the resulting Quaternion acts as if \p b was applied first and then \p a was
applied. This is obvious since the image \c v' of \p v by the composited rotation satisfies:@code 
v'= (a*b) * v = a * (b*v) \endcode

Note that a*b usually differs from b*a.

\attention For efficiency reasons, the resulting Quaternion is not normalized. Use normalize() in
case of numerical drift with small rotation composition.

Definition at line 164 of file quaternion.h.

Vec operator*	(	const Quaternion &	q,
		const Vec &	v
	)

friend

Returns the image of v by the rotation q.

Same as q.rotate(v). See rotate() and inverseRotate().

Definition at line 187 of file quaternion.h.

Member Data Documentation

qreal qglviewer::Quaternion::q[4]

private

The internal data representation is private, use operator[] to access values.

Definition at line 304 of file quaternion.h.

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

QDomElement Quaternion::domElement	(	const QString &	name,
		QDomDocument &	document
	)		const

void Quaternion::getAxisAngle	(	Vec &	axis,
		qreal &	angle
	)		const

Private Attributes

Defining a Quaternion

Accessing values

Rotation computations

Inversion

Associated matrix

Slerp interpolation

Random Quaternion

XML representation

Detailed Description

Internal representation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation

Member Data Documentation