class MQuaternion

Jump to documentation

public members:

	MQuaternion ()
	MQuaternion (const MQuaternion &src)
	MQuaternion (double xx, double yy, double zz, double ww)
	MQuaternion (const double[4])
	MQuaternion (const MVector &a, const MVector &b)
	MQuaternion (const MVector &a, const MVector &b, double angleFactor)
	MQuaternion (double angle, const MVector &axisb)
	~MQuaternion ()
MQuaternion &	operator= (const MQuaternion & src)
MQuaternion &	operator= (const MMatrix &matrix)
MQuaternion &	operator= (const MEulerRotation &matrix)
MMatrix	asMatrix () const
MEulerRotation	asEulerRotation () const
MQuaternion &	setAxisAngle (const MVector &axis, double theta)
bool	getAxisAngle ( MVector &axis, double &theta) const
MQuaternion &	setToXAxis (double theta)
MQuaternion &	setToYAxis (double theta)
MQuaternion &	setToZAxis (double theta)
MStatus	get (double dest[4]) const
double	operator[] (unsigned int i) const
MQuaternion	operator+ (const MQuaternion &other) const
MQuaternion	operator* (const MQuaternion &other) const
MQuaternion &	operator*= (const MQuaternion &rhs)
MQuaternion	operator- (const MQuaternion &other) const
MQuaternion	operator- () const
MQuaternion &	negateIt ()
bool	operator== (const MQuaternion &other) const
bool	operator!= (const MQuaternion &other) const
bool	isEquivalent (const MQuaternion &other, double tolerance = kQuaternionEpsilon) const
MQuaternion &	scaleIt (double scale)
MQuaternion	normal () const
MQuaternion &	normalizeIt ()
MQuaternion	conjugate () const
MQuaternion &	conjugateIt ()
MQuaternion	inverse () const
MQuaternion &	invertIt ()
MQuaternion	log () const
MQuaternion	exp () const
static const MQuaternion	identity The multiplicative identity.
double &	operator[] (unsigned int i) NO SCRIPT SUPPORT
friend MQuaternion	operator* (double scale, const MQuaternion &other) NO SCRIPT SUPPORT
friend MQuaternion	slerp (const MQuaternion &p, const MQuaternion &q, double t)
friend MQuaternion	slerp (const MQuaternion &p, const MQuaternion &q, double t, short spin) NO SCRIPT SUPPORT
friend MQuaternion	squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t) NO SCRIPT SUPPORT
friend MQuaternion	squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t, short spin) NO SCRIPT SUPPORT
friend MQuaternion	squadPt (const MQuaternion &q0, const MQuaternion &q1, const MQuaternion &q2) NO SCRIPT SUPPORT
friend std::ostream &	operator<< (std::ostream &os, const MQuaternion &q) NO SCRIPT SUPPORT
operator	MMatrix () const NO SCRIPT SUPPORT
double	x The quaternion's imaginary x component.
double	y The quaternion's imaginary y component.
double	z The quaternion's imaginary z component.
double	w The quaternion's real component.

Documentation

Description

This class provides methods for working with Quaternions. Quaternions can be used to specify orientations and rotations of 3-D objects relative to a starting reference, similar to the way that cartesian vectors can be used to specify positions and translations of 3-D objects relative to an origin. Quaternions represent orientations as a single rotation, just as rectangular co-ordinates represent position as a single vector.

Functions

MQuaternion:: MQuaternion ()

Description

The default class constructor. Initializes the quaternion to the multiplicative identity.

MQuaternion:: MQuaternion (const MQuaternion & src)

Description

The copy constructor. Creates a new quaternion and initializes it to the same values as the given quaternion.

Arguments

• src the quaternion object to copy

MQuaternion:: MQuaternion (double xx, double yy, double zz, double ww)

Description

Class constructor. Initializes the quaternion with the explicit x, y, z, and w values provided as arguments.

Arguments

• xx the x component of the quaternion
• yy the y component of the quaternion
• zz the z component of the quaternion.
• ww the w component of the quaternion.

MQuaternion:: MQuaternion (const double q[4])

Description

Class constructor. Initializes the quaternion with the explicit x, y, z, and w values provided in the given double array.

Arguments

• q the 4 element array containing the initial x, y, z, and w values

MQuaternion:: MQuaternion (const MVector &a, const MVector &b)

Description

Class constructor. Creates a new quaternion that will rotate vector a into vector b about their mutually perpendicular axis.

Arguments

• a vector to rotate from
• b vector to rotate to

MQuaternion:: MQuaternion (const MVector &a, const MVector &b, double angleFactor)

Description

Class constructor. Creates a new quaternion that will rotate vector a into vector b about their mutually perpendicular axis by a given factor.

Arguments

• a vector to rotate from
• b vector to rotate to
• angleFactor the factor by which the rotation should be multiplied; a factor of 1.0 is equivalent to a rotation of vector a into vector b

MQuaternion:: MQuaternion (double angle, const MVector &axis)

Description

This constructor creates a new quaternion whose rotation is expressed by a pivot axis and a rotation (in radians) about that axis. If the length of the axis is too small the quaternion returned will be the identity quaternion.

Arguments

• angle the amount of rotation around the axis
• axis the axis about which the rotation occurs

MQuaternion:: ~MQuaternion ()

Description

Class destructor.

MQuaternion &MQuaternion:: operator= (const MQuaternion &src)

Description

The assignment operator.

Arguments

• src the source quaternion

Return Value

• a reference to the quaternion that has been assigned to the source quaternion

MQuaternion &MQuaternion:: operator= (const MMatrix &matrix)

Description

Convert the given 4X4 homogeneous rotation matrix to a quaternion of unit length.

This methods always returns a quaternion of unit length if it is given a proper orthogonal matrix. A proper othogonal matrix is one such that the determinant of the matrix is one. (If the determinant were -1, this would imply that the orthogonal matrix is also producing a reflection, in addition to a rotation.)

Arguments

• matrix the matrix to be converted to a quaternion

Return Value

• a reference to the quaternion that has been converted from the rotation matrix

MQuaternion &MQuaternion:: operator= (const MEulerRotation &euler)

Description

Convert the given euler rotation to a quaternion.

Arguments

• eulerRotation the euler rotation to be converted to a quaternion

Return Value

• a reference to the quaternion that has been converted from the euler rotation

MQuaternion::operator MMatrix () const

Description

Casts a quaternion to a matrix.

Return Value

• a matrix that is casted from a quaternion

MMatrix MQuaternion:: asMatrix () const

Description

Converts a quaternion to a 4X4 homogeneous rotation matrix. The construction of the matrix assumes that the vectors are going to be multiplied on the left side of the matrix. If the quaternion's length has degenerated, this method will still produce a well behaved matrix.

ReturnValue

• the matrix converted from a quaternion

MEulerRotation MQuaternion:: asEulerRotation () const

Description

Converts a quaternion to an euler rotation.

ReturnValue

• the euler rotation converted from a quaternion

MQuaternion &MQuaternion:: setAxisAngle (const MVector &axis, double theta)

Description

Sets this quaternion to be the rotation as expressed by a pivot axis and a rotation theta (in radians) about that axis. If the axis is too small the quaternion returned will be the identity quaternion.

Arguments

• axis the axis about which to rotate
• theta the angle of rotation about the axis in radians

Return Value

• a reference to the quaternion that has had its axis and angle set

bool MQuaternion:: getAxisAngle ( MVector &axis, double &theta) const

Description

Converts this quaternion into a user understandable representation. That is, the quaternion is represented as a pivot vector 'axis' and a rotation 'theta' (in radians) about that pivot vector.

If the identity unit quaternion is attempted to be converted to the pivot axis and angle representation it will be set to a zero degree rotation about the axis that was passed in. (Note that any axis will do, since an infinity of axis with rotation of zero satisfy the identity rotation.) If the axis is zero length, then an arbitrary axis will be chosen (z-axis).

Arguments

• axis the axis about which the rotation occurs
• theta the angle of rotation about the axis in radians

Return Value

• true angle != 0
• false angle == 0 (uses arbitrary axis, if given axis not valid)

MQuaternion &MQuaternion:: setToXAxis (double theta)

Description

Sets this quaternion to be the rotation about the X axis of theta (in radians). If the length of the axis is too small the quaternion returned will be the identity quaternion.

Arguments

• theta the angle of rotation about the X axis in radians

Return Value

• a reference to the quaternion that has been set to rotate about the X axis by the given amount

MQuaternion &MQuaternion:: setToYAxis (double theta)

Description

Sets this quaternion to be the rotation about the Y axis of theta (in radians). If the length of the axis is too small the quaternion returned will be the identity quaternion.

Arguments

• theta the angle of rotation about the Y axis in radians

Return Value

• a reference to the quaternion that has been set to rotate about the Y axis by the given amount

MQuaternion &MQuaternion:: setToZAxis (double theta)

Description

Sets this quaternion to be the rotation about the Z axis of theta (in radians). If the length of the axis is too small the quaternion returned will be the identity quaternion.

Arguments

• theta the angle of rotation about the Z axis in radians

Return Value

• a reference to the quaternion that has been set to rotate about the Z axis by the given amount

MStatus MQuaternion:: get (double dest[4]) const

Description

Extracts the x, y, z, and w components of the quaternion and places them in elements 0, 1, 2, and 3 of the double array passed.

Arguments

• dest the array of 4 doubles into which the results are placed.

Return Value

• MS::kSuccess if dest is a non-zero pointer and MS::kFailure otherwise

double &MQuaternion:: operator[] (unsigned int i)

Description

The index operator. If its argument is 0 it will return the x component of the quaternion. If its argument is 1 it will return the y component of the quaternion. If its argument is 2 it will return the z component of the quaternion. If its argument is 3 it will return the w component of the quaternion.

Arguments

• i value indicating which component to return

Return Value

• a reference to the component of the quaternion corresponding to the index

double MQuaternion:: operator[] (unsigned int i) const

Description

The index operator. If its argument is 0 it will return the x component of the quaternion. If its argument is 1 it will return the y component of the quaternion. If its argument is 2 it will return the z component of the quaternion. If its argument is 3 it will return the w component of the quaternion.

Arguments

• i value indicating which component to return

Return Value

• the component of the quaternion corresponding to the index

MQuaternion MQuaternion:: operator+ (const MQuaternion &other) const

Description

The quaternion addition operator.

Arguments

• other the quaternion to be added to this quaternion

Return Value

• the sum of the two quaternions

MQuaternion MQuaternion:: operator* (const MQuaternion &other) const

Description

This quaternion multiplication operator.

Quaternions in Maya multiply on the right (post-multiply) the same as matrices. Many popular quaternion papers (Shoemake) use pre-multiplication where quaternions pre-multiply on the left so you must be aware of this when using quaternions.

In general, if p and q are quaternions, pq != qp, i.e., multiplication does not commute!

Arguments

• other the quaternion to be multiplied with this quaternion

Return Value

• the product of the two quaternions

MQuaternion &MQuaternion:: operator*= (const MQuaternion &other)

Description

The in place quaternion multiplication operator.

Quaternions in Maya multiply on the right (post-multiply) the same as matrices.

Arguments

• other the quaternion to be multiplied with this quaternion

Return Value

• a reference to this quaternion which has been multiplied with the other quaternion

MQuaternion operator* (double scale, const MQuaternion &other)

Description

The multiplication operator that allows the scale to preceed the quaternion.

Arguments

• scale the amount by which the quaternion should be scaled
• other the quaternion to which the scale should be applied

Return Value

• quaternion that is the result of scaling the other quaternion

MQuaternion MQuaternion:: operator- (const MQuaternion & other) const

Description

The quaternion subtraction operator.

Arguments

• other the quaternion to be subtracted from this quaternion

Return Value

• the quaternion that results from the subtraction

MQuaternion MQuaternion:: operator- () const

Description

The unary minus operator. Negates the value of each of the x, y, z, and w components of the quaternion.

Return Value

• quaternion that results from the negation

MQuaternion &MQuaternion:: negateIt ()

Description

Performs an in place negation of the quaternion. The result is a quaternion whose x, y, z, and w values have been negated.

Return Value

• a reference to the quaternion that has been negated

bool MQuaternion:: operator== (const MQuaternion &other) const

Description

The quaternion equality operator. This returns true if all four of the x, y, z, and w components are identical.

Arguments

• other the quaternion to be compared with this quaternion

Return Value

• true the quaternions are identical
• false the quaternions are not identical

bool MQuaternion:: operator!= (const MQuaternion &other) const

Description

The quaternion inequality operator. This returns false if all four of the x, y, z, and w components are identical.

Arguments

• other the quaternion to be compared with this quaternion

Return Value

• true the quaternions are not identical
• false the quaternions are identical

bool MQuaternion:: isEquivalent (const MQuaternion &other, double tolerance) const

Description

This method returns true if this quaternion is equal, within some given tolerance, to the other quaternion.

'tolerance' defaults to kQuaternionEpsilon which is 1.0e-10

Arguments

• other the quaternion to be compared with this quaternion
• tolerance the amount of variation allowed for equivalency

Return Value

• true the quaternions are equivalent
• false the quaternions are not equivalent

MQuaternion &MQuaternion:: scaleIt (double scale)

Description

Performs an in place scaling of the quaternion. The result is a quaternion whose x, y, z, and w values have been scaled by the specified amount.

Arguments

• scale the amount by which the quaternion should be scaled

Return Value

• a reference to the quaternion that has been scaled

MQuaternion MQuaternion:: normal () const

Description

Returns the normal of this quaternion. The result is a quaternion of unit length.

If the quaternion is zero or has a very small length it will instead be set to the multiplicative identity.

Return Value

• quaternion that is the normal of this quaternion

MQuaternion &MQuaternion:: normalizeIt ()

Description

Performs an in place normalization of this quaternion. The result is a quaternion of unit length.

If the quaternion is zero or has a very small length it will instead be set to the multiplicative identity.

Return Value

• a reference to the quaternion that has been normalized

MQuaternion MQuaternion:: conjugate () const

Description

Returns the conjugate of this quaternion. The result is a quaternion whose x, y, and z values have been negated.

Return Value

• quaternion that is the conjugate of this quaternion

MQuaternion &MQuaternion:: conjugateIt ()

Description

Performs an in place conjugation of this quaternion. The result is a quaternion whose x, y, and z values have been negated.

Return Value

• a reference to the quaternion that has been conjugated

MQuaternion MQuaternion:: inverse () const

Description

Returns the inverse of this quaternion.

Return Value

• quaternion that is the inverse of this quaternion

MQuaternion &MQuaternion:: invertIt ()

Description

Performs an in place inversion of this quaternion.

Return Value

• a reference to the quaternion that has been inverted

MQuaternion MQuaternion:: log () const

Description

Returns the natural log of a quaternion. The precondition for using this method is that the quaternion must be normalized.

Note that the log of a unit quaternion is not necessarily a unit quaternion.

Return Value

• quaternion that is the log of this quaternion

MQuaternion MQuaternion:: exp () const

Description

Exponentiates a quaternion that has a scalar part of zero. The precondition for using this method is that w is zero.

Return Value

• quaternion that is the result of exponentiating this quaternion

MQuaternion slerp (const MQuaternion &p, const MQuaternion &q, double t)

Description

Spherical linear interpolation (abbreviated as slerp) of unit quaternions. As t goes from 0 to 1, the quaternion returned goes from p to q. The interpolation always takes shortest path (in quaternion space) from p to q.

Arguments

• p quaternion to rotate from
• q quaternion to rotate to
• t interpolation value

Return Value

• quaternion that has been interpolated from p to q

MQuaternion slerp (const MQuaternion &p, const MQuaternion &q, double t, short spin)

Description

Spherical linear interpolation (abbreviated as slerp) of unit quaternions. As t goes from 0 to 1, the quaternion returned goes from p to q. The spin parameter determines how many complete revolutions around the axis will occur as p goes to q. Negative spins will take the "long way" around the great sphere when rotating. (-1 can be used to interpolate using the "long" path on the quaternion sphere without any extra spins.)

Arguments

• p quaternion to rotate from
• q quaternion to rotate to
• t interpolation value
• spin the number of complete revolutions around the axis

Return Value

• quaternion that has been interpolated from p to q

MQuaternion squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t)

Description

Compute a point on a cubic curve segment that interpolates p and q and is C1 continuous. Need to use squadPoint or some other suitable method for finding a and b

Arguments

• p quaternion to rotate from
• a intermediate squad point
• b intermediate squad point
• q quaternion to rotate to
• t interpolation value

Return Value

• quaternion that has been interpolated from p to q

MQuaternion squad (const MQuaternion &p, const MQuaternion &a, const MQuaternion &b, const MQuaternion &q, double t, short spin)

Description

Compute a point on a cubic curve segment that interpolates p and q and is C1 continuous. Need to use squadPoint or some other suitable method for finding a and b

Arguments

• p quaternion to rotate from
• a intermediate squad point
• b intermediate squad point
• q quaternion to rotate to
• t interpolation value

Return Value

• quaternion that has been interpolated from p to q

MQuaternion squadPt (const MQuaternion &q0, const MQuaternion &q1, const MQuaternion &q2)

Description

Generate an intermediate squad point used to produce a C1 continuous spline (using squad). This method uses the average of the tangents of arcs to adjacent points. Therefore, to squad from p to q we need to find a and b in the following manner:

Given: unit quaternion control points we wish to interpolate (q0, q1,..., p-1, p, q, q+1,..., qN)

Want: a, b such that squad(p, a, b, q, t) generates a C1 continuous cubic curve from p to q as we vary t from 0 to 1.

Calculation: a = squadPoint(p-1, p, q); b = squadPoint(p, q, q+1);

Notes: We only need to compute one squadPoint for each segment (except at endpoints) since the next 'a' value is simply our current 'b' value (ie. a(i) = b(i-1) or b(i) = a(i+1)).

Arguments

• q0 quaternion from which the squad is computed
• q1 quaternion from which the squad is computed
• q2 quaternion from which the squad is computed

Return Value

• unit quaternion resulting from the squad computation

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

Description

Print the contents of the given quaternion on the given ostream. The format used is [x: <x>, y: <y>, z: <z>, w: <w>].

Arguments

• os the ostream to print to
• q the quaternion to be printed

Return Value

The ostream reference, os, provided as the first parameter.

This class has no child classes.