This reference page is linked to from the following overview topics: Lesson 4: Animation Controllers, Rotation, Rotation Concepts, Object Offset Transformation, Controllers, Keyframe Data Access Classes and Methods.

Detailed Description

See also:: Class Point3, Class Matrix3, Class AngAxis.

Description:: This class provides a compact representation for orientation in three space and provides methods to perform Quaternion algebra.

Quaternions provide an alternative representation for orientation in three-space. To reduce computing, you can substitute quaternion multiplication for rotation-matrix composition.

A quaternion is made up of four terms: a real scalar part which specifies the amount of rotation and an imaginary vector part which defines the axis of rotation. If the quaternion is normalized, the scalar term equals the cosine of half the angle of rotation, the vector term is the axis of rotation, and the magnitude of the vector term equals the sine of half the angle of rotation.

Interpolation between two key frame orientations is much easier using quaternions and produces smooth and natural motion. Unlike Euler angles, no numerical integration is necessary; quaternions provide an analytic result (no approximations).

The rotation convention in the 3ds Max API is the left-hand-rule. Note that this is different from the right-hand-rule used in the 3ds Max user interface.

For additional information see: Quaternion operations:

From "Quaternion Calculus and Fast Animation",

by Ken Shoemake, in notes for SIGGRAPH 1987 Course # 10,

"Computer Animation: 3-D Motion Specification and Control".

All methods of this class are implemented by the system.

Data Members:: float x,y,z,w;

The x, y, z values make up the vector portion. w is the angle of rotation about the vector (see remarks above for details).

#include <quat.h>

Inheritance diagram for Quat:

[legend]

List of all members.

Public Member Functions
	Quat ()
	Quat (float X, float Y, float Z, float W)
	Quat (double X, double Y, double Z, double W)
	Quat (const Quat &a)
	Quat (float af[4])
GEOMEXPORT	Quat (const Matrix3 &mat)
GEOMEXPORT	Quat (const AngAxis &aa)
GEOMEXPORT	Quat (const Point3 &V, float W)
float &	operator[] (int i)
const float &	operator[] (int i) const
float	Scalar ()
Point3	Vector ()
	operator float * ()
Quat	operator- () const
Quat	operator+ () const
GEOMEXPORT Quat	Inverse () const
GEOMEXPORT Quat	Conjugate () const
GEOMEXPORT Quat	LogN () const
GEOMEXPORT Quat	Exp () const
GEOMEXPORT Quat &	operator-= (const Quat &)
GEOMEXPORT Quat &	operator+= (const Quat &)
GEOMEXPORT Quat &	operator*= (const Quat &)
GEOMEXPORT Quat &	operator*= (float)
GEOMEXPORT Quat &	operator/= (float)
Quat &	Set (float X, float Y, float Z, float W)
Quat &	Set (double X, double Y, double Z, double W)
GEOMEXPORT Quat &	Set (const Matrix3 &mat)
GEOMEXPORT Quat &	Set (const AngAxis &aa)
Quat &	Set (const Point3 &V, float W)
GEOMEXPORT Quat &	SetEuler (float X, float Y, float Z)
GEOMEXPORT Quat &	Invert ()
GEOMEXPORT Quat &	MakeClosest (const Quat &qto)
GEOMEXPORT int	operator== (const Quat &a) const
GEOMEXPORT int	Equals (const Quat &a, float epsilon=1E-6f) const
void	Identity ()
GEOMEXPORT int	IsIdentity () const
GEOMEXPORT void	Normalize ()
GEOMEXPORT void	MakeMatrix (Matrix3 &mat, bool flag=false) const
GEOMEXPORT void	GetEuler (float X, float Y, float *Z) const
GEOMEXPORT Quat	operator- (const Quat &) const
GEOMEXPORT Quat	operator+ (const Quat &) const
GEOMEXPORT Quat	operator* (const Quat &) const
GEOMEXPORT Quat	operator/ (const Quat &) const
GEOMEXPORT float	operator% (const Quat &) const
GEOMEXPORT Quat	Plus (const Quat &) const
GEOMEXPORT Quat	Minus (const Quat &) const
Public Attributes
float	x
float	y
float	z
float	w

Constructor & Destructor Documentation

Quat ( ) [inline]

Remarks:: Constructor. No initialization is performed.

: x(0.0f),y(0.0f),z(0.0f),w(1.0f) {}

Quat	(	float	X,
		float	Y,
		float	Z,
		float	W
	)		`[inline]`

Remarks:: Constructor. The data members are initialized to the values passed.

{ x = X; y = Y; z = Z; w = W; }

Quat	(	double	X,
		double	Y,
		double	Z,
		double	W
	)		`[inline]`

Remarks:: Constructor. The data members are initialized to the values passed (cast as floats).

                                                 { 
      x = (float)X; y = (float)Y; z = (float)Z; w = (float)W;  
      }

Quat ( const Quat & a ) [inline]

Remarks:: Constructor. The data members are initialized to the Quat passed.

{ x = a.x; y = a.y; z = a.z; w = a.w; }

Quat ( float af[4] ) [inline]

Remarks:: Constructor. The data members are initialized to the values passed.

x = af[0]; y = af[1]; z = af[2]; w = af[3];

{ x = af[0]; y = af[1]; z = af[2]; w = af[3]; }

GEOMEXPORT Quat ( const Matrix3 & mat )

Remarks:: Constructor. Convert the specified 3x3 rotation matrix to a unit quaternion.

GEOMEXPORT Quat ( const AngAxis & aa )

Remarks:: Constructor. The Quat is initialized to the AngAxis passed.

GEOMEXPORT Quat	(	const Point3 &	V,
		float	W
	)

Remarks:: Constructor. The quaternion is initialized from the vector V and angle W passed. The quaternion is then normalized.

Member Function Documentation

float& operator[] ( int i ) [inline]

Remarks:: Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.

{ return (&x)[i]; }

const float& operator[] ( int i ) const [inline]

Remarks:: Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.

{ return (&x)[i]; }

float Scalar ( ) [inline]

Search for all occurrences

{ return w; }

Point3 Vector ( ) [inline]

Search for all occurrences

{ return Point3(x, y, z); }

operator float * ( ) [inline]

Remarks:: Returns the address of the Quaternion.

Unary operators

{ return(&x); }

Quat operator- ( ) const [inline]

Remarks:: Unary negation. Returns Quat(-x,-y,-z,-w).

{ return(Quat(-x,-y,-z,-w)); }

Quat operator+ ( ) const [inline]

Remarks:: Unary +. Returns the Quat unaltered.

Assignment operators

{ return *this; }

GEOMEXPORT Quat Inverse ( ) const

Search for all occurrences

Remarks:: Returns the inverse of this quaternion (1/q).

GEOMEXPORT Quat Conjugate ( ) const

Search for all occurrences

Remarks:: Returns the conjugate of a quaternion.

GEOMEXPORT Quat LogN ( ) const

Search for all occurrences

Remarks:: Returns the natural logarithm of a UNIT quaternion.

GEOMEXPORT Quat Exp ( ) const

Search for all occurrences

Remarks:: Returns the exponentiate quaternion (where q.w==0).

Operators:

GEOMEXPORT Quat& operator-= ( const Quat & )

Remarks:: This operator is the same as the /= operator.

GEOMEXPORT Quat& operator+= ( const Quat & )

Remarks:: This operator is the same as the *= operator..

GEOMEXPORT Quat& operator*= ( const Quat & )

Remarks:: Multiplies this quaternion by a quaternion.

GEOMEXPORT Quat& operator*= ( float )

Remarks:: Multiplies this quaternion by a floating point value.

GEOMEXPORT Quat& operator/= ( float )

Remarks:: Divides this quaternion by a floating point value.

Quat& Set	(	float	X,
		float	Y,
		float	Z,
		float	W
	)		`[inline]`

Search for all occurrences

      { x = X; y = Y; z = Z; w = W; return *this; }

Quat& Set	(	double	X,
		double	Y,
		double	Z,
		double	W
	)		`[inline]`

Search for all occurrences

      { x = (float)X; y = (float)Y; z = (float)Z; w = (float)W;
        return *this; }

GEOMEXPORT Quat& Set ( const Matrix3 & mat )

Search for all occurrences

GEOMEXPORT Quat& Set ( const AngAxis & aa )

Search for all occurrences

Quat& Set	(	const Point3 &	V,
		float	W
	)		`[inline]`

Search for all occurrences

      { x = V.x; y = V.y; z = V.z; w = W; return *this; }

GEOMEXPORT Quat& SetEuler	(	float	X,
		float	Y,
		float	Z
	)

Search for all occurrences

GEOMEXPORT Quat& Invert ( )

Search for all occurrences

GEOMEXPORT Quat& MakeClosest ( const Quat & qto )

Search for all occurrences

Remarks:: Modifies q so it is on same side of hypersphere as qto.

GEOMEXPORT int operator== ( const Quat & a ) const

Remarks:: Returns nonzero if the quaternions are equal; otherwise 0.

GEOMEXPORT int Equals	(	const Quat &	a,
		float	epsilon = `1E-6f`
	)		const

Search for all occurrences

void Identity ( ) [inline]

Search for all occurrences

Remarks:: Sets this quaternion to the identity quaternion (x=y=z=0.0; w=1.0).

{ x = y = z = 0.0f; w = 1.0f; }

GEOMEXPORT int IsIdentity ( ) const

Search for all occurrences

Remarks:: Returns nonzero if the quaternion is the identity; otherwise 0.

GEOMEXPORT void Normalize ( )

Search for all occurrences

Remarks:: Normalizes this quaternion, dividing each term by a scale factor such that the resulting sum or the squares of all parts equals unity.

GEOMEXPORT void MakeMatrix	(	Matrix3 &	mat,
		bool	flag = `false`
	)		const

Search for all occurrences

Remarks:: Converts the quaternion to a 3x3 rotation matrix. The quaternion need not be unit magnitude.

Parameters:: Matrix3 &mat

The matrix.

BOOL b=FALSE

This parameter is available in release 4.0 and later only.

When this argument is set to false (or omitted), each function performs as it did before version 4.0. When the boolean is TRUE, the matrix is made with its terms transposed. When this transposition is specified, EulerToQuat() and QuatToEuler() are consistent with one another. (In 3ds Max 3, they have opposite handedness).

GEOMEXPORT void GetEuler	(	float *	X,
		float *	Y,
		float *	Z
	)		const

Search for all occurrences

GEOMEXPORT Quat operator- ( const Quat & ) const

Remarks:: This operator is the same as the / operator.

GEOMEXPORT Quat operator+ ( const Quat & ) const

Remarks:: This operator is the same as the * operator.

GEOMEXPORT Quat operator* ( const Quat & ) const

Remarks:: Returns the product of two quaternions.

GEOMEXPORT Quat operator/ ( const Quat & ) const

Remarks:: Returns the ratio of two quaternions: This creates a result quaternion r = p/q, such that q*r = p. (Order of multiplication is important)

GEOMEXPORT float operator% ( const Quat & ) const