Class Quat
See Also: Class Point3, Class Matrix3, Class AngAxis.
class Quat
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:
public:
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).
Methods:
Prototype:
Quat()
Remarks:
Constructor. No initialization is performed.
Prototype:
Quat(float X, float Y, float Z, float W)
Remarks:
Constructor. The data members are initialized to the values passed.
Prototype:
Quat(double X, double Y, double Z, double W)
Remarks:
Constructor. The data members are initialized to the values passed (cast as floats).
Prototype:
Quat(const Quat& a)
Remarks:
Constructor. The data members are initialized to the Quat passed.
Prototype:
Quat(float af[4])
Remarks:
Constructor. The data members are initialized to the values passed.
x = af[0]; y = af[1]; z = af[2]; w = af[3];
Prototype:
Quat(const Matrix3& mat);
Remarks:
Constructor. Convert the specified 3x3 rotation matrix to a unit quaternion.
Prototype:
Quat(const AngAxis& aa);
Remarks:
Constructor. The Quat is initialized to the AngAxis passed.
Prototype:
Quat(const Point3& V, float W);
Remarks:
This method is available in release 3.0 and later only.
Constructor. The quaternion is initialized from the vector V and angle W passed. The quaternion is then normalized.
Prototype:
Quat Inverse() const;
Remarks:
This method is available in release 3.0 and later only.
Returns the inverse of this quaternion (1/q).
Prototype:
Quat Conjugate() const;
Remarks:
This method is available in release 3.0 and later only.
Returns the conjugate of a quaternion.
Prototype:
Quat LogN() const;
Remarks:
This method is available in release 3.0 and later only.
Returns the natural logarithm of a UNIT quaternion.
Prototype:
Quat Exp() const;
Remarks:
This method is available in release 3.0 and later only.
Returns the exponentiate quaternion (where q.w==0).
Operators:
Prototype:
float& operator[](int i)
Remarks:
Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.
Prototype:
const float& operator[](int i) const
Remarks:
Array access operator. Valid i values: 0=x, 1=y, 2=z, 3=w.
Prototype:
operator float*()
Remarks:
Returns the address of the Quaternion.
Unary operators
Prototype:
Quat operator-() const
Remarks:
Unary negation. Returns Quat(-x,-y,-z,-w).
Prototype:
Quat operator+() const
Remarks:
Unary +. Returns the Quat unaltered.
Assignment operators
Prototype:
Quat& operator-=(const Quat&);
Remarks:
This operator is the same as the /= operator.
Prototype:
Quat& operator+=(const Quat&);
Remarks:
This operator is the same as the *= operator..
Prototype:
Quat& operator*=(const Quat&);
Remarks:
Multiplies this quaternion by a quaternion.
Prototype:
Quat& operator*=(float);
Remarks:
Multiplies this quaternion by a floating point value.
Prototype:
Quat& operator/=(float);
Remarks:
Divides this quaternion by a floating point value.
Prototype:
int operator==(const Quat& a) const;
Remarks:
Returns nonzero if the quaternions are equal; otherwise 0.
Prototype:
void Identity()
Remarks:
Sets this quaternion to the identity quaternion (x=y=z=0.0; w=1.0).
Prototype:
int IsIdentity() const;
Remarks:
Returns nonzero if the quaternion is the identity; otherwise 0.
Prototype:
void Normalize();
Remarks:
Normalizes this quaternion, dividing each term by a scale factor such that the resulting sum or the squares of all parts equals unity.
Prototype:
Quat& MakeClosest(const Quat& qto);
Remarks:
Modifies q so it is on same side of hypersphere as qto.
Prototype:
void MakeMatrix(Matrix3 &mat, bool b=FALSE) const;
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).
Prototype:
Quat operator+(const Quat&) const;
Remarks:
This operator is the same as the * operator.
Prototype:
Quat operator-(const Quat&) const;
Remarks:
This operator is the same as the / operator.
Prototype:
Quat operator*(const Quat&) const;
Remarks:
Returns the product of two quaternions.
Prototype:
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)
The following operators and functions are not part of class Quat but are available for use.
Prototype:
Quat operator*(float, const Quat&);
Remarks:
Multiplies the quaternion by a scalar.
Prototype:
Quat operator*(const Quat&, float);
Remarks:
Multiplies the quaternion by a scalar.
Prototype:
Quat operator/(const Quat&, float);
Remarks:
Divides the quaternion by a scalar.
Prototype:
Quat Inverse(const Quat& q);
Remarks:
Returns the inverse of the quaternion (1/q).
Prototype:
Quat Conjugate(const Quat& q);
Remarks:
Returns the conjugate of a quaternion.
Prototype:
Quat LogN(const Quat& q);
Remarks:
Returns the natural logarithm of UNIT quaternion.
Prototype:
Quat Exp(const Quat& q);
Remarks:
Exponentiate quaternion (where q.w==0).
Prototype:
Quat Slerp(const Quat& p, const Quat& q, float t);
Remarks:
Spherical linear interpolation of UNIT quaternions.
As t goes from 0 to 1, qt goes from p to q.
slerp(p,q,t) = (p*sin((1-t)*omega) + q*sin(t*omega)) / sin(omega)
Prototype:
Quat LnDif(const Quat& p, const Quat& q);
Remarks:
Computes the "log difference" of two quaternions, p and q, as ln(qinv(p)*q).
Prototype:
Quat QCompA(const Quat& qprev,const Quat& q, const Quat& qnext);
Remarks:
Compute a, the term used in Boehm-type interpolation.
a[n] = q[n]* qexp(-(1/4)*( ln(qinv(q[n])*q[n+1]) +ln( qinv(q[n])*q[n-1] )))
Prototype:
Quat Squad(const Quat& p, const Quat& a, const Quat &b,
const Quat& q, float t);
Remarks:
Squad(p,a,b,q; t) = Slerp(Slerp(p,q;t), Slerp(a,b;t); 2(1-t)t).
Prototype:
Quat qorthog(const Quat& p, const Point3& axis);
Remarks:
Rotate p by 90 degrees (quaternion space metric) about the specified axis.
Prototype:
Quat squadrev(float angle,const Point3& axis,const Quat& p,
const Quat& a,const Quat& b,const Quat& q,float t);
Remarks:
Quaternion interpolation for angles > 2PI.
Parameters:
float angle
Angle of rotation
const Point3& axis
The axis of rotation
const Quat& p
Start quaternion
const Quat& a
Start tangent quaternion
const Quat& b
End tangent quaternion
const Quat& q
End quaternion
float t
Parameter, in range [0.0,1.0]
Prototype:
void RotateMatrix(Matrix3& mat, const Quat& q);
Remarks:
Converts the quaternion to a matrix and multiples it by the specified matrix. The result is returned in mat.
Prototype:
void PreRotateMatrix(Matrix3& mat, const Quat& q);
Remarks:
Converts the quaternion to a matrix and multiples it on the left by the specified matrix. . The result is returned in mat.
Prototype:
Quat QFromAngAxis(float ang, const Point3& axis);
Remarks:
Converts the [angle,axis] representation to the equivalent quaternion.
Prototype:
void AngAxisFromQ(const Quat& q, float *ang, Point3& axis);
Remarks:
Converts the quaternion to the equivalent [angle,axis] representation.
Prototype:
float QangAxis(const Quat& p, const Quat& q, Point3& axis);
Remarks:
Compute the [angle,axis] corresponding to the rotation from p to q. Returns angle, sets axis.
Prototype:
void DecomposeMatrix(const Matrix3& mat, Point3& p,
Quat& q, Point3& s);
Remarks:
Decomposes a matrix into a rotation, scale, and translation (to be applied in that order). This only will work correctly for scaling which was applied in the rotated axis system. For more general decomposition see the function decomp_affine(). See Structure AffineParts.
Prototype:
Quat TransformQuat(const Matrix3 &m, const Quat&q );
Remarks:
Returns the transformation of the specified quaternion by the specified matrix.
Prototype:
inline Quat IdentQuat()
Remarks:
Returns the identity quaternion (Quat(0.0,0.0,0.0,1.0)).
Function:
void QuatToEuler(Quat &q, float *ang);
Remarks:
Converts the quaternion to Euler angles. When converting a quaternion to Euler angles using this method, the correct order of application of the resulting three rotations is X, then Y, then Z. The angles are returned as ang[0]=x, ang[1]=y, ang[2]=z.
Function:
void EulerToQuat(float *ang, Quat &q, int order);
Remarks:
Converts Euler angles to a quaternion. The angles are specified as ang[0]=x, ang[1]=y, ang[2]=z. This method is implemented as:
void EulerToQuat(float *ang, Quat &q, int order)
{
Matrix3 mat(1);
for (int i=0; i<3; i++) {
switch (orderings[order][i]) {
case 0: mat.RotateX(ang[i]); break;
case 1: mat.RotateY(ang[i]); break;
case 2: mat.RotateZ(ang[i]); break;
}
}
q = Quat(mat);
}
Prototype:
ostream &operator<<(ostream&, const Quat&);
Remarks:
Output on an ostream.