Quat Values

Values and Collections - Quick Navigation

The Quat class provides a compact representation for orientation in three space and provides methods to perform Quaternion algebra.

Quaternions are used to store object rotations in 3ds Max.

A quaternion is made up of four terms: a real scalar part that specifies the amount of rotation and an imaginary vector part that 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).

Rotations in MAXScript follow the right-hand-rule, namely positive angles rotate counter-clockwise about positive axes, consistent with the convention in the 3ds Max UI.

Constructors

quat <x_float> <y_float> <z_float> <w_float>

The x, y, z values make up the vector portion. w is the angle of rotation about the vector.

quat <degrees_float> <axis_point3>
<angleaxis> as quat
<eulerangle> as quat
<matrix3> as quat --extracts the rotation component as a quat

Properties

<quat>.w: Float
<quat>.x: Float
<quat>.y: Float
<quat>.z: Float

Access quaternion complex components as Floats.

<quat>.angle: Float
<quat>.axis: Point3

Access derived properties (an angle in degrees and a rotation axis).

Operators

<quat> + <quat>
<quat> - <quat>
<quat> * <quat_or_number>
<quat> / <number>
- <quat>

Quaternion algebra.

NOTE:The + operator is the same as the * operator (product) and the - operator is the same as the / operator (ratio).

<quat> * <matrix3>

Quaternion algebra using rotation portion of the matrix3.

<quat> == <quat>
<quat> != <quat>
<quat> as <class>

Quats can convert to Matrix3's, Angleaxis's, and Eulerangle's.

Methods

copy <quat>

Creates a new copy of the quat value.

FOR EXAMPLE:

newQuat = copy oldQuat

The new value contains a copy of the input quat value, and is independent of the input quat value.

isIdentity <quat>

Returns true if the quaternion is equal to the identity quaternion (x=y=z=0.0; w=1.0).

normalize <quat>

Returns a normalized quat, dividing each term of the input quat by a scale factor such that the resulting sum of the squares of all parts equals unity.

inverse <quat>

Returns the inverse of the quaternion (1/q).

conjugate <quat>

Returns the conjugate of the quaternion.

logN <quat>

Returns the natural logarithm of UNIT quaternion.

exp <quat>

Returns the exponentiated quaternion (where q.w=0).

slerp <start_quat> <end_quat> <number>

Returns a spherical linear interpolation of UNIT quaternions.

As <number> goes from 0 to 1, the returned value goes from <start_quat> to <end_quat>.

LnDif <p_quat> <q_quat>

Returns the "log difference" of two quaternions as:

logN ((inverse p_quat)*q_quat)

qCompA<prev_quat> <now_quat> <next_quat>

Computes a , the term used in Boehm-type interpolation:

a = now_quat * exp(-(1/4)*(logN((inverse now_quat)*next_quat)+logN((inverse now_quat)*prev_quat)))

squad<p_quat> <a_quat> <b_quat> <q_quat> <number>

slerp (slerp p_quatq_quatnumber) (slerp a_quatb_quatnumber) (2*(1-number)*number)

qorthog <quat> <axis_point3>

Returns quat rotated by 180 degrees (quaternion space metric) about the specified axis axis_point3 .

transform <quat> <matrix3>

Returns the transformation of the specified quaternion by the specified matrix.

squadrev <angle_number> <axis_point3> <start_quat> <start_tangent_quat> <end_tangent_quat> <end_quat> <number>

Returns quaternion interpolation for angles > 2PI, where angle_number is the angle of rotation, and axis_point3 is the axis of rotation. As number goes from 0 to 1, the returned value goes from start_quat to end_quat .

random <quat> <quat>

Returns a random rotation between the two quats, using Slerp.

Related Methods

quatToEuler<quat> order:<eulertype_integer>
eulerToQuat<eulerAngle> order:<eulertype_integer>

Converts between quat and euler angle values. The optional order parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ

quatToEuler2 <quat>

Returns the same Euler value for the given Quaternion as shown in the Transform Type-In dialog. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions .

quatArrayToEulerArray <quat array>

Returns an array of smooth Euler values from the Quat array. Available in 3ds Max 2008 and higher. Previously, available in the Avguard Extensions.

getEulerQuatAngleRatio <quat1> <quat2> <eulerAngles1> <eulerAngles2> [angle:<eulertype_integer>]

When converting a series of quat values to eulerAngles values, it is possible for sign flips to occur in the eulerAngles values. This is due to the fact that one single quat value can be expressed through many different eulerAngles values. This flip can be detected based on the eulerAngles/quat ratio. The eulerAngles/quat ratio is the relation of the angle difference in eulerAngles space to the angle difference in quat space. If this ratio is bigger than PI, the rotation between the two quat to eulerAngles conversions. This method returns the eulerAngles/quat angle ratio between the two quat to eulerAngles conversions as a float value. The actual detection of the flip is dependent on the amount of rotation in between conversions. The smaller the amount of rotation, the more accurate the detection is. The parameters to this method are:

quat1 and quat2 are the previous and current rotation values.

eulerAngles1 and eulerAngles2 are the previous and current converted rotation angles.

The optional eulertype_integer parameter specifies the order of application of the angles. If not specified, XYZ ordering is used. Its value can be any of the following:

1 - XYZ
2 - XZY
3 - YZX
4 - YXZ
5 - ZXY
6 - ZYX
7 - XYX
8 - YZY
9 - ZXZ

Quat Values

See Also