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

Defining a Quaternion
	Quaternion ()
	Default constructor, builds an identity rotation.

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

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

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

	Quaternion (const Quaternion &Q)
	Copy constructor.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

double	normalize ()
	Normalizes the Quaternion coefficients.

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

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

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

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

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

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

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

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

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

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

Quaternion	exp ()
	Returns the exponential of the Quaternion.

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

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

static double	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].

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

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

Random Quaternion
static Quaternion	randomQuaternion ()
	Returns a random unit Quaternion.

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

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

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

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

Quaternion ( )

inline

Default constructor, builds an identity rotation.

Definition at line 72 of file quaternion.h.

Quaternion	(	const Vec &	axis,
		double	angle
	)

inline

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

Member Function Documentation

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

Definition at line 238 of file quaternion.h.

Referenced by Frame::initFromDOMElement().

Quaternion& operator*= ( const Quaternion & q )

inline

Quaternion rotation is composed with q.

See operator*(), since this is equivalent to this = this * 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& operator= ( const Quaternion & Q )

inline

Equal operator.

Definition at line 96 of file quaternion.h.

double operator[] ( int i ) const

inline

Bracket operator, with a constant return value.

i must range in [0..3]. See the Quaternion(double, double, double, double) documentation.

Definition at line 144 of file quaternion.h.

double& operator[] ( int i )

inline

Bracket operator returning an l-value.

i must range in [0..3]. See the Quaternion(double, double, double, double) documentation.

Definition at line 147 of file quaternion.h.

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 546 of file quaternion.cpp.

Vec rotate ( const Vec & v ) const

Returns the image of v by the Quaternion rotation.

Definition at line 76 of file quaternion.cpp.

Referenced by LocalConstraint::constrainTranslation(), Frame::localInverseCoordinatesOf(), Frame::localInverseTransformOf(), ManipulatedFrame::mouseMoveEvent(), Camera::setFromModelViewMatrix(), and ManipulatedFrame::wheelEvent().

void setAxisAngle	(	const Vec &	axis,
		double	angle
	)

inline

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

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

Definition at line 106 of file quaternion.h.

References Vec::norm().

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

See also setFromRotationMatrix() and Quaternion(const Vec&, const Vec&).

Definition at line 182 of file quaternion.cpp.

References Vec::norm().

Referenced by Camera::setViewDirection().

void setFromRotationMatrix ( const double 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 setValue	(	double	q0,
		double	q1,
		double	q2,
		double	q3
	)

inline

Sets the Quaternion value.

See the Quaternion(double, double, double, double) constructor documentation.

Definition at line 125 of file quaternion.h.

Quaternion slerp	(	const Quaternion &	a,
		const Quaternion &	b,
		float	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 437 of file quaternion.cpp.

References Quaternion::dot().

Referenced by Quaternion::squad().

Quaternion squad	(	const Quaternion &	a,
		const Quaternion &	tgA,
		const Quaternion &	tgB,
		const Quaternion &	b,
		float	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 471 of file quaternion.cpp.

References Quaternion::slerp().

Referenced by KeyFrameInterpolator::drawPath(), and KeyFrameInterpolator::interpolateAtTime().

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 517 of file quaternion.cpp.

References Quaternion::exp(), and Quaternion::lnDif().

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

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.

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

worldsim/3rdParts/qglviewer/quaternion.h
worldsim/3rdParts/qglviewer/quaternion.cpp

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

WorldSim - 1.2.3

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