#include <QGLViewer/quaternion.h>

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

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 \c q rotation to the OpenGL matrices using:
 \code glMultMatrixd(q.matrix()); 
 // equivalent to glRotate(q.angle()*180.0/M_PI, q.axis().x, q.axis().y, q.axis().z); \endcode

 Quaternion is part of the \c qglviewer namespace, specify \c

qglviewer::Quaternion or use the qglviewer namespace:

using namespace qglviewer;

qglviewer

Definition: camera.h:30

  <h3>Internal representation</h3>

  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)

qglviewer::Quaternion::axis

Vec axis() const

Returns the normalized axis direction of the rotation represented by the Quaternion.

Definition: quaternion.cpp:192

 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.
 \nosubgrouping

Public Member Functions
Defining a Quaternion
	Quaternion ()
	Default constructor, builds an identity rotation. More...

	Quaternion (const Vec &axis, qreal angle)
	Constructor from rotation axis (non null) and angle (in radians). More...

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

	Quaternion (qreal q0, qreal q1, qreal q2, qreal q3)
	Constructor from the four values of a Quaternion. More...

	Quaternion (const Quaternion &Q)
	Copy constructor. More...

Quaternion &	operator= (const Quaternion &Q)
	Equal operator. More...

void	setAxisAngle (const Vec &axis, qreal angle)
	Sets the Quaternion as a rotation of axis `axis` and angle `angle` (in radians). More...

void	setValue (qreal q0, qreal q1, qreal q2, qreal q3)
	Sets the Quaternion value. More...

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

void	setFromRotationMatrix (const qreal m[3][3])
	Set the Quaternion from a (supposedly correct) 3x3 rotation matrix. More...

void	setFromRotatedBasis (const Vec &X, const Vec &Y, const Vec &Z)
	Sets the Quaternion from the three rotated vectors of an orthogonal basis. More...

Accessing values
Vec	axis () const
	Returns the normalized axis direction of the rotation represented by the Quaternion. More...

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

void	getAxisAngle (Vec &axis, qreal &angle) const
	Returns the axis vector and the angle (in radians) of the rotation represented by the Quaternion. More...

qreal	operator[] (int i) const
	Bracket operator, with a constant return value. More...

qreal &	operator[] (int i)
	Bracket operator returning an l-value. More...

Inversion
Quaternion	inverse () const
	Returns the inverse Quaternion (inverse rotation). More...

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

void	negate ()
	Negates all the coefficients of the Quaternion. More...

qreal	normalize ()
	Normalizes the Quaternion coefficients. More...

Quaternion	normalized () const
	Returns a normalized version of the Quaternion. More...

Associated matrix
const GLdouble *	matrix () const
	Returns the Quaternion associated 4x4 OpenGL rotation matrix. More...

void	getMatrix (GLdouble m[4][4]) const
	Fills `m` with the OpenGL representation of the Quaternion rotation. More...

void	getMatrix (GLdouble m[16]) const
	Same as getMatrix(), but with a `GLdouble`[16] parameter. More...

void	getRotationMatrix (qreal m[3][3]) const
	Fills `m` with the 3x3 rotation matrix associated with the Quaternion. More...

const GLdouble *	inverseMatrix () const
	Returns the associated 4x4 OpenGL inverse rotation matrix. More...

void	getInverseMatrix (GLdouble m[4][4]) const
	Fills `m` with the OpenGL matrix corresponding to the inverse() rotation. More...

void	getInverseMatrix (GLdouble m[16]) const
	Same as getInverseMatrix(), but with a `GLdouble`[16] parameter. More...

void	getInverseRotationMatrix (qreal m[3][3]) const
	`m` is set to the 3x3 inverse rotation matrix associated with the Quaternion. More...

Static Public Member Functions
Random Quaternion
static Quaternion	randomQuaternion ()
	Returns a random unit Quaternion. More...

XML representation
	Quaternion (const QDomElement &element)
	Constructs a Quaternion from a `QDomElement` representing an XML code of the form. More...

QDomElement	domElement (const QString &name, QDomDocument &document) const
	Returns an XML `QDomElement` that represents the Quaternion. More...

void	initFromDOMElement (const QDomElement &element)
	Restores the Quaternion state from a `QDomElement` created by domElement(). More...

Rotation computations
Quaternion &	operator*= (const Quaternion &q)
	Quaternion rotation is composed with `q`. More...

Vec	rotate (const Vec &v) const
	Returns the image of `v` by the Quaternion rotation. More...

Vec	inverseRotate (const Vec &v) const
	Returns the image of `v` by the Quaternion inverse() rotation. More...

Quaternion	operator* (const Quaternion &a, const Quaternion &b)
	Returns the composition of the `a` and `b` rotations. More...

Vec	operator* (const Quaternion &q, const Vec &v)
	Returns the image of `v` by the rotation `q`. More...

Slerp interpolation
Quaternion	log ()
	Returns the logarithm of the Quaternion. More...

Quaternion	exp ()
	Returns the exponential of the Quaternion. More...

static Quaternion	slerp (const Quaternion &a, const Quaternion &b, qreal t, bool allowFlip=true)
	Returns the slerp interpolation of Quaternions `a` and `b`, at time `t`. More...

static Quaternion	squad (const Quaternion &a, const Quaternion &tgA, const Quaternion &tgB, const Quaternion &b, qreal t)
	Returns the slerp interpolation of the two Quaternions `a` and `b`, at time `t`, using tangents `tgA` and `tgB`. More...

static qreal	dot (const Quaternion &a, const Quaternion &b)
	Returns the "dot" product of `a` and `b:` a[0]b[0] + a[1]b[1] + a[2]b[2] + a[3]b[3]. More...

static Quaternion	lnDif (const Quaternion &a, const Quaternion &b)
	Returns log(a. More...

static Quaternion	squadTangent (const Quaternion &before, const Quaternion &center, const Quaternion &after)
	Returns a tangent Quaternion for `center`, defined by `before` and `after` Quaternions. More...

Constructor details

◆ Quaternion() [1/6]

qglviewer::Quaternion::Quaternion ( )

inline

Default constructor, builds an identity rotation.

◆ Quaternion() [2/6]

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

inline

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

◆ Quaternion() [3/6]

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.

◆ Quaternion() [4/6]

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 \e not

Quaternion(0,0,0,0) (which is not unitary). The default Quaternion() creates such identity Quaternion.

◆ Quaternion() [5/6]

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

inline

Copy constructor.

◆ Quaternion() [6/6]

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().

Function details

◆ angle()

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.

◆ axis()

Vec Quaternion::axis ( ) const

Returns the normalized axis direction of the rotation represented by the Quaternion.

It is null for an identity Quaternion. See also angle() and getAxisAngle().

◆ domElement()

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

Returns an XML QDomElement that represents the Quaternion.

name is the name of the QDomElement tag. doc is the QDomDocument factory used to create QDomElement.

When output to a file, the resulting QDomElement will look like:

Use initFromDOMElement() to restore the Quaternion state from the resulting QDomElement. See also the Quaternion(const QDomElement&) constructor.

See the Vec::domElement() documentation for a complete QDomDocument creation and saving example.

◆ dot()

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

inlinestatic

Returns the "dot" product of a and b: a[0]*b[0] + a[1]*b[1] + a[2]*b[2] + a[3]*b[3].

◆ exp()

Quaternion Quaternion::exp ( )

Returns the exponential of the Quaternion.

◆ getAxisAngle()

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

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

See the axis() and angle() documentations.

◆ getInverseMatrix() [1/2]

void Quaternion::getInverseMatrix ( GLdouble m[16] ) const

Same as getInverseMatrix(), but with a GLdouble[16] parameter.

◆ getInverseMatrix() [2/2]

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

Fills m with the OpenGL matrix corresponding to the inverse() rotation.

Use inverseMatrix() if you do not need to store this matrix and simply want to alter the current OpenGL matrix. See also getMatrix().

◆ getInverseRotationMatrix()

void Quaternion::getInverseRotationMatrix ( qreal 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().

◆ getMatrix() [1/2]

void Quaternion::getMatrix ( GLdouble m[16] ) const

Same as getMatrix(), but with a GLdouble[16] parameter.

◆ getMatrix() [2/2]

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

Fills m with the OpenGL representation of the Quaternion rotation.

Use matrix() if you do not need to store this matrix and simply want to alter the current OpenGL matrix. See also getInverseMatrix() and Frame::getMatrix().

◆ getRotationMatrix()

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

Fills m with the 3x3 rotation matrix associated with the Quaternion.

◆ initFromDOMElement()

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.

◆ inverse()

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.

◆ inverseMatrix()

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.

◆ inverseRotate()

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

◆ invert()

void qglviewer::Quaternion::invert ( )

inline

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

See also inverse().

◆ lnDif()

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

static

Returns log(a.

inverse() * b). Useful for squadTangent().

◆ log()

Quaternion Quaternion::log ( )

Returns the logarithm of the Quaternion.

◆ matrix()

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.

◆ negate()

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.

◆ normalize()

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().

◆ normalized()

Quaternion qglviewer::Quaternion::normalized ( ) const

inline

Returns a normalized version of the Quaternion.

See also normalize().

◆ operator*=()

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.

◆ operator=()

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

inline

Equal operator.

◆ operator[]() [1/2]

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.

◆ operator[]() [2/2]

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.

◆ randomQuaternion()

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

qglviewer::Quaternion::randomQuaternion

static Quaternion randomQuaternion()

Returns a random unit Quaternion.

Definition: quaternion.cpp:515

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

◆ rotate()

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

Returns the image of v by the Quaternion rotation.

◆ setAxisAngle()

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.

◆ setFromRotatedBase()

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

◆ setFromRotatedBasis()

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

◆ setFromRotationMatrix()

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.

◆ setValue()

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.

◆ slerp()

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()).

◆ squad()

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.

◆ squadTangent()

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().

Related details

◆ operator* [1/2]

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 b was applied first and then a was applied. This is obvious since the image v' of v by the composited rotation satisfies:

v'= (a*b) * v = a * (b*v)

 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.

◆ operator* [2/2]

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().

Detailed Description

Public Member Functions

Static Public Member Functions

XML representation

Rotation computations

Slerp interpolation

Constructor details

◆ Quaternion() [1/6]

◆ Quaternion() [2/6]

◆ Quaternion() [3/6]

◆ Quaternion() [4/6]

◆ Quaternion() [5/6]

◆ Quaternion() [6/6]

Function details

◆ angle()

◆ axis()

◆ domElement()

◆ dot()

◆ exp()

◆ getAxisAngle()

◆ getInverseMatrix() [1/2]

◆ getInverseMatrix() [2/2]

◆ getInverseRotationMatrix()

◆ getMatrix() [1/2]

◆ getMatrix() [2/2]

◆ getRotationMatrix()

◆ initFromDOMElement()

◆ inverse()

◆ inverseMatrix()

◆ inverseRotate()

◆ invert()

◆ lnDif()

◆ log()

◆ matrix()

◆ negate()

◆ normalize()

◆ normalized()

◆ operator*=()

◆ operator=()

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ randomQuaternion()

◆ rotate()

◆ setAxisAngle()

◆ setFromRotatedBase()

◆ setFromRotatedBasis()

◆ setFromRotationMatrix()

◆ setValue()

◆ slerp()

◆ squad()

◆ squadTangent()

Related details

◆ operator* [1/2]

◆ operator* [2/2]