cugl::Quaternion Class Reference

#include <cugl.h>

Collaboration diagram for cugl::Quaternion:

Collaboration graph
[legend]
List of all members.

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/ (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 (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, const Quaternion &r)
Quaternion operator * (const Quaternion &q, GLfloat a)
Quaternion operator * (GLfloat a, const Quaternion &q)
Vector ln (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, 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 1044 of file cugl.h.


Constructor & Destructor Documentation

cugl::Quaternion::Quaternion (  )  [inline]

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

Definition at line 1054 of file cugl.h.

Referenced by conj(), cugl::operator *(), cugl::operator+(), cugl::operator-(), and cugl::operator/().

cugl::Quaternion::Quaternion ( GLfloat  s,
GLfloat  x,
GLfloat  y,
GLfloat  z 
) [inline]

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

Definition at line 1060 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 1070 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 1079 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 1089 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

Quaternion cugl::Quaternion::operator *= ( const Quaternion q  )  [inline]

Multiply this quaternion by q and return the result.

Definition at line 2864 of file cugl.h.

References s, v, and Vector.

Quaternion cugl::Quaternion::operator/= ( const Quaternion q  )  [inline]

Divide this quaternion by q and return the result.

Definition at line 2938 of file cugl.h.

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

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.

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

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 2844 of file cugl.h.

References Quaternion(), s, and v.

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

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 2859 of file cugl.h.

References inv().

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 2811 of file cugl.h.

References s, v, and Vector.

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 2824 of file cugl.h.

References v.

GLfloat cugl::Quaternion::scalar (  )  const [inline]

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

Definition at line 2829 of file cugl.h.

References s.

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 2834 of file cugl.h.

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

Referenced by magnitude(), cugl::operator/(), and 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 2839 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.

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 2849 of file cugl.h.

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

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 2854 of file cugl.h.

References s.

void cugl::Quaternion::integrate ( 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.

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


Friends And Related Function Documentation

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 2883 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 2888 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 2893 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 2904 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 2915 of file cugl.h.

Quaternion operator/ ( const Quaternion q,
const Quaternion r 
) [friend]

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.

Definition at line 2926 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 2952 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 2957 of file cugl.h.

Vector ln ( const Quaternion q  )  [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.

Quaternion exp ( const Vector v  )  [friend]

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.

GLfloat dot ( const Quaternion q,
const Quaternion r 
) [friend]

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 2878 of file cugl.h.

Referenced by cugl::dot().

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 2962 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 2967 of file cugl.h.

std::ostream& operator<< ( std::ostream &  os,
Quaternion q 
) [friend]

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


Member Data Documentation

GLfloat cugl::Quaternion::s [private]

Scalar component of quaternion.

Definition at line 1395 of file cugl.h.

Referenced by angle(), apply(), conj(), cugl::dot(), norm(), cugl::operator *(), operator *=(), cugl::operator+(), cugl::operator-(), cugl::operator/(), operator/=(), cugl::operator==(), and scalar().

Vector cugl::Quaternion::v [private]

Vector component of quaternion.

Definition at line 1398 of file cugl.h.

Referenced by apply(), axis(), conj(), cugl::dot(), norm(), cugl::operator *(), operator *=(), cugl::operator+(), cugl::operator-(), cugl::operator/(), operator/=(), cugl::operator==(), vector(), and cugl::Vector::Vector().


The documentation for this class was generated from the following file:
Generated on Wed Sep 12 14:31:42 2007 for CUGL by  doxygen 1.5.2