#include <cugl.h>

Collaboration diagram for cugl::Quaternion:

Public Member Functions
	Quaternion ()

	Quaternion (GLfloat s, GLfloat x, GLfloat y, GLfloat z)

	Quaternion (const Vector &v)

	Quaternion (GLfloat s, const Vector &v)

	Quaternion (Vector axis, double angle)

	Quaternion (Matrix m)

	Quaternion (double xr, double yr, double zr)

	Quaternion (const Point &p)

	Quaternion (const Vector &u, const Vector &v)

Quaternion	operator+= (const Quaternion &q)

Quaternion	operator-= (const Quaternion &q)

Quaternion &	operator*= (const Quaternion &q)

Quaternion &	operator/= (const Quaternion &q)

Quaternion &	operator*= (GLfloat s)

Quaternion &	operator/= (GLfloat s)

Quaternion	operator/ (GLfloat scale) const

void	normalize ()

Quaternion	unit () const

Quaternion	conj () const

Quaternion	inv () const

Quaternion	operator~ () const

Vector	apply (const Vector &w) const

Vector	vector () const

GLfloat	scalar () const

GLfloat	norm () const

GLfloat	magnitude () const

void	matrix (Matrix &m) const

void	matrix (GL_Matrix m) const

void	apply () const

Vector	axis () const

double	angle () const

void	integrate (const Vector &omega, double dt)

void	euler (double &xr, double &yr, double &zr) const

void	trackball (GLfloat x1, GLfloat y1, GLfloat x2, GLfloat y2)

Private Attributes
GLfloat	s

Vector	v

Friends
class	Vector

class	Matrix

Quaternion	operator+ (const Quaternion &q, const Quaternion &r)

Quaternion	operator- (const Quaternion &q, const Quaternion &r)

Quaternion	operator* (const Quaternion &q, const Quaternion &r)

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

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

Quaternion	operator* (const Quaternion &q, GLfloat a)

Quaternion	operator* (GLfloat a, const Quaternion &q)

Quaternion	log (const Quaternion &q)

Quaternion	exp (const Quaternion &q)

Quaternion	exp (const Vector &v)

GLfloat	dot (const Quaternion &q, const Quaternion &r)

bool	operator== (const Quaternion &x, const Quaternion &y)

bool	operator!= (const Quaternion &x, const Quaternion &y)

std::ostream &	operator<< (std::ostream &os, const Quaternion &q)

Detailed Description

An instance is a quaternion represented as a (scalar, vector) pair. We use the notation (s,v) for a quaternion with scalar component s and vector component v. Although arbitrary quaternions can be constructed, all of the applications of quaternions provided by the class assume that the quaternion is a unit quaternion representing a rotation.

Definition at line 1134 of file cugl.h.

Constructor & Destructor Documentation

cugl::Quaternion::Quaternion ( )

inline

Construct the quaternion (1,(0,0,0)) (the null rotation).

Definition at line 1144 of file cugl.h.

Referenced by conj().

cugl::Quaternion::Quaternion	(	GLfloat	s,
		GLfloat	x,
		GLfloat	y,
		GLfloat	z
	)

inline

Construct the quaternion (s, (x,y,z)).

Definition at line 1150 of file cugl.h.

cugl::Quaternion::Quaternion ( const Vector & v )

inline

Construct the quaternion (0,v). The result will be a unit quaternion if v is a unit vector, in which case the quaternion represents a rotation through 90 degrees about the axis v.

Definition at line 1160 of file cugl.h.

cugl::Quaternion::Quaternion	(	GLfloat	s,
		const Vector &	v
	)

inline

Construct the quaternion (s,v).

Note: Don't confuse this constructor with Quaternion(axis,angle).

Parameters

s	is the scalar component of the quaternion.
v	is the vector component of the quaternion.

Definition at line 1169 of file cugl.h.

cugl::Quaternion::Quaternion	(	Vector	axis,
		double	angle
	)

inline

Construct a quaternion with the given axis of rotation and angle.

Note: Don't confuse this constructor with Quaternion(s,v).

Precondition: The axis must be a unit vector.

Parameters

axis	gives the axis of rotation.
angle	gives the amount of the rotation.

Definition at line 1179 of file cugl.h.

cugl::Quaternion::Quaternion ( Matrix m )

Construct the quaternion corresponding to an OpenGL rotation matrix. The result may be imprecise if the rotation angle is close to 180 degrees. This function may report BAD_ROTATION_MATRIX.

Precondition: The matrix must be a rotation matrix.

cugl::Quaternion::Quaternion	(	double	xr,
		double	yr,
		double	zr
	)

Construct a quaternion from Euler angles.

cugl::Quaternion::Quaternion ( const Point & p )

Construct a Quaternion from a Point. The quaternion consists of the vector (p[0],p[1],p[2]) and the scalar p[3].

Note: This is a unusual operation and should not normally be used. It is intended for experiments with non-linear transformations.

cugl::Quaternion::Quaternion	(	const Vector &	u,
		const Vector &	v
	)

Construct the quaternion that rotates one vector to another.

Parameters

u	is a vector representing an initial orientation.
v	is a vector representing the final orientation. The quaternion, applied to u, will yield v.

Precondition: The vectors u and v must be unit vectors.

Member Function Documentation

double cugl::Quaternion::angle ( ) const

inline

Return the amount of rotation of this quaternion.

Precondition: The quaternon must be a unit quaternion.

Returns: the amount of rotation provided by this quaternion in radians.

Definition at line 3195 of file cugl.h.

References s.

Vector cugl::Quaternion::apply ( const Vector & w ) const

inline

Apply this quaternion to the vector w. The vector w is not changed.

Returns: the rotated vector q.inv()*w*q.

Definition at line 3152 of file cugl.h.

References s, and v.

void cugl::Quaternion::apply ( ) const

Apply the current quaternion to the current OpenGL matrix.

Vector cugl::Quaternion::axis ( ) const

inline

Return the axis of rotation of this quaternion.

Precondition: The quaternon must be a unit quaternion.

Returns: a unit vector giving the axis of rotation of the quaternion.

Definition at line 3190 of file cugl.h.

References cugl::Vector::unit(), and v.

Quaternion cugl::Quaternion::conj ( ) const

inline

Return the conjugate of this quaternion. The conjugate of (s,v) is (s,-v). The inverse and conjugate of a unit quaternion are equal.

Returns: the conjugate of this quaternion.

Definition at line 3185 of file cugl.h.

References Quaternion(), s, and v.

void cugl::Quaternion::euler	(	double &	xr,
		double &	yr,
		double &	zr
	)		const

Return Euler angles for this quaternion. The quaternion gives the rotation that would be obtained by calling glRotatef three times, with arguments (xr,1,0,0), (yr,0,1,0), and (zr,0,0,1).

Precondition: The angle transformations are applied in x, y, z order.

Returns: the Euler angles corresponding to this quaternion.

void cugl::Quaternion::integrate	(	const Vector &	omega,
		double	dt
	)

Integrate an angular velocity vector. The rotation represented by this quaternion will be updated by applying the angular velocity omega for a short interval of time dt.

Parameters

omega	is an angular velocity vector.
dt	is the time increment for integration.

Quaternion cugl::Quaternion::inv ( ) const

Return Inverse of this quaternion. q.inv() = q.conj()/q.norm(). The inverse and conjugate of a unit quaternion are equal. Report error ZERO_DIVISOR if q.norm() = 0. If q represents a rotation then q.inv() represents the opposite, or inverse, rotation. The prefix operator ~ has the same effect.

Returns: the inverse of this quaternion.

Referenced by operator~().

GLfloat cugl::Quaternion::magnitude ( ) const

inline

Return the magnitude of this quaternion. The magnitude is the square root of the norm.

Returns: the magnitude of this quaternion.

Definition at line 3180 of file cugl.h.

References norm().

void cugl::Quaternion::matrix ( Matrix & m ) const

Compute the rotation matrix corresponding to this quaternion and store it in the Matrix m.

Referenced by cugl::Interpolator::getMatrix().

void cugl::Quaternion::matrix ( GL_Matrix m ) const

Compute the rotation matrix corresponding to this quaternion and store it in the OpenGL matrix m.

GLfloat cugl::Quaternion::norm ( ) const

inline

Return the norm of this quaternion. The norm is the sum of the squared components and is also the square of the magnitude.

Returns: the norm of this quaternion.

Definition at line 3175 of file cugl.h.

References cugl::Vector::norm(), s, and v.

Referenced by magnitude(), and operator/=().

void cugl::Quaternion::normalize ( )

Normalize this quaternion. See also Quaternion::unit(). Report error ZERO_DIVISOR if q = (0,(0,0,0)).

Note: The value of this quaternion is changed by this operation.

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

inline

REMOVED: ambiguous operattion - need left and right quotients. Return the quaternion ratio q/r. If q and r represent rotations, then q/r represents the rotation q followed by the rotation that is the inverse of r.

Returns: the Quaternion ratio q/r. Multiply this quaternion by q and return the result.

Definition at line 3205 of file cugl.h.

References s, and v.

Quaternion & cugl::Quaternion::operator*= ( GLfloat s )

inline

Multiply by scalar and assign.

Definition at line 3138 of file cugl.h.

References s, and v.

Quaternion cugl::Quaternion::operator+= ( const Quaternion & q )

inline

Add the quaternion q to this quaternion.

Definition at line 3124 of file cugl.h.

References s, and v.

Quaternion cugl::Quaternion::operator-= ( const Quaternion & q )

inline

Subtract the quaternion q from this quaternion.

Definition at line 3131 of file cugl.h.

References s, and v.

Quaternion cugl::Quaternion::operator/ ( GLfloat scale ) const

Return the quaternion q/a, where a is a scalar. a is a scalar and (s,v)/a = (s/a, v/a). Report error ZERO_DIVISOR if a = 0.

Returns: the Quaternion q/a.

Quaternion & cugl::Quaternion::operator/= ( const Quaternion & q )

inline

Divide this quaternion by q and return the result.

Definition at line 3267 of file cugl.h.

References norm(), s, and v.

Quaternion & cugl::Quaternion::operator/= ( GLfloat s )

inline

Divide by scalar and assign.

Definition at line 3145 of file cugl.h.

References s, and v.

Quaternion cugl::Quaternion::operator~ ( ) const

inline

Return Inverse of this quaternion. This provides alternative syntax for inv().

Returns: the inverse of this quaternion.

Definition at line 3200 of file cugl.h.

References inv().

GLfloat cugl::Quaternion::scalar ( ) const

inline

Return Scalar component s of the quaternion q = (s,v).

Definition at line 3170 of file cugl.h.

References s.

void cugl::Quaternion::trackball	(	GLfloat	x1,
		GLfloat	y1,
		GLfloat	x2,
		GLfloat	y2
	)

Use this quaternion to simulate a trackball. To use this function in an OpenGL program, use the default constructor to construct the quaternion q = (1,(0,0,0)). In the display function, use q.rotate() to modify the OpenGL model view matrix.

Call trackball(x1,y1,x2,y2) to record a small mouse movement from (x1,y1) to (x2,y2). The coordinates should be normalized so that both x and y are in [-1,1].

This function will compute a rotation will apply this rotation to the current quaternion. The rotation simulates a trackball.

Quaternion cugl::Quaternion::unit ( ) const

Return a unit quaternion corresponding to this quaternion. See also Quaternion::normalize(). Report error ZERO_DIVISOR if q = (0,(0,0,0)).

Note: The value of this quaternion is not changed by this operation.

Vector cugl::Quaternion::vector ( ) const

inline

Return Vector component v of the quaternion q = (s,v). The same effect can be achieved with the constructor Vector::Vector(q).

Definition at line 3165 of file cugl.h.

References v.

Friends And Related Function Documentation

GLfloat dot	(	const Quaternion &	q,
		const Quaternion &	r
	)

friend

The 'logarithm' of a unit quaternion is a vector. This function is defined because it appears in descriptions of quaternions. Although the name 'ln' is appropriate in some ways, this function must be used with caution because it may not have the properties you expect of a logarithm. For example, ln(q1)+ln(q2) makes sense only if q1 and q2 have the same axis.

Precondition: The quaternion must be a unit quaternion. The 'exponent' of a vector is a unit quaternion. Although the name 'exp' is appropriate in some ways, this function must be used with caution because it may not have the properties you expect of an exponent. For example, exp(v1+v2)=exp(v1)*exp(v2) only if v1 and v2 have the same direction. Return the dot product of quaternions q and r. The dot product of (s,u) and (t,v) is st+dot(u,v) where dot(u,v) denotes the vector dot product of u and v.

Returns: the dot product of quaternions q and r.

Definition at line 3219 of file cugl.h.

Quaternion exp ( const Quaternion & q )

friend

exp(q) is defined for pure quaternions (scalar part zero) only. (that is, members of the Lie algebra of the quaternion group). This function ignores the scalar part - it does not check for zero.

Definition at line 1470 of file cugl.h.

Quaternion exp ( const Vector & v )

friend

exp(v) is a quaternion. The vector is treated as a "pure" quaternion (that is, as a member of the Lie algebra of the quaternion group).

Definition at line 1483 of file cugl.h.

Quaternion log ( const Quaternion & q )

friend

log(q) of a quaternion is a pure quaternion (scalar part 0). log(q) is an element of the Lie algebra of the quaternion group. log(1;0) = (0;0).

Definition at line 1458 of file cugl.h.

bool operator!=	(	const Quaternion &	x,
		const Quaternion &	y
	)

friend

Compare two quaternions. This function returns false only if corresponding components are exactly equal. Values that are theoretically equal but computed in different ways are likely to be unequal according to this function.

Definition at line 3296 of file cugl.h.

Quaternion operator*	(	const Quaternion &	q,
		const Quaternion &	r
	)

friend

Return the quaternion product q*r. If q and r represent rotations, then q*r represents the rotation q followed by the rotation r.

Note: Quaternion multiplication is not commutative: q*r is not equal to r*q.

Returns: the Quaternion product q*r.

Definition at line 3234 of file cugl.h.

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

friend

Promote the vector v to a quaternion qv and return the quaternion product qv*q.

Definition at line 3245 of file cugl.h.

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

friend

Promote the vector v to a quaternion qv and return the quaternion product q*qv.

Definition at line 3256 of file cugl.h.

Quaternion operator*	(	const Quaternion &	q,
		GLfloat	a
	)

friend

Return the quaternion a*q, where a is a scalar. a is a scalar and a*(s,v) = (a*s, a*v).

Returns: the Quaternion a*q.

Definition at line 3281 of file cugl.h.

Quaternion operator*	(	GLfloat	a,
		const Quaternion &	q
	)

friend

Return the quaternion a*q, where a is a scalar. a is a scalar and a*(s,v) = (a*s, a*v).

Returns: the Quaternion a*q.

Definition at line 3286 of file cugl.h.

Quaternion operator+	(	const Quaternion &	q,
		const Quaternion &	r
	)

friend

Return the quaternion q+r.

Note: The sum of two unit quaternions is not in general a unit quaternion. However, it occasionally appears in expressions such as k q1 + (1 - k) q2, which does yield a unit quaternion.

Returns: the Quaternion q+r.

Definition at line 3224 of file cugl.h.

Quaternion operator-	(	const Quaternion &	q,
		const Quaternion &	r
	)

friend

Return the quaternion q-r.

Note: The difference of two unit quaternions is not in general a unit quaternion.

Returns: the Quaternion q-r.

Definition at line 3229 of file cugl.h.

std::ostream& operator<<	(	std::ostream &	os,
		const Quaternion &	q
	)

friend

Write the quaternion to the output stream as s (x,y,z).

bool operator==	(	const Quaternion &	x,
		const Quaternion &	y
	)

friend

Compare two quaternions. This function returns true only if corresponding components are exactly equal. Values that are theoretically equal but computed in different ways are likely to be unequal according to this function.

Definition at line 3291 of file cugl.h.