*Anim_keyread*
takes as input a file containing a series of keyframes generated by the
*mged*
command
**savekey**, and produces a table containing the same information, except that the view orientation matrix is changed to a form that can be interpolated. The default form for the orientation information is the quaternion. For each such keyframe in the input file,
**anim_keyread**
will produce a row in the output file containing the time, the viewsize, the position of the camera, and the orientation of the camera, specified as a unit quaternion in the order x, y, z, and w.

**Example 1. Typical savekey keyframe**

The following is an example of a typical keyframe generated by the
**savekey**
command. The time is 0, the viewsize is 10, the camera is at the point (2.5,2.5,3.53), and the camera orientation is specified by a matrix.

0.000000
1.000000000e+01
2.500000000e+00 2.500000000e+00 3.535533906e+00
-7.071067812e-01 7.071067812e-01 0.000000000e+00 0.000000000e+00
-5.000000000e-01 -5.000000000e-01 7.071067812e-01 0.000000000e+00
5.000000000e-01 5.000000000e-01 7.071067812e-01 0.000000000e+00
0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00

For the key frame shown above, the output would be:

0.000000 10.000000 2.500000 2.500000 3.535534 0.146447 0.353553 0.853553 0.353553

The last four numbers define the desired orientation as a quaternion.

With the
**-y**
option, the output would be:

0.000000 10.000000 2.500000 2.500000 3.535534 -135.000000 -45.000000 0.000000

Here, the last three numbers are the yaw, pitch, and roll, which can be interpreted as follows: Imagine a camera at the origin originally facing the positive x-direction, with the z-axis going up and the y-axis positive to the left. The camera should be rotated +roll degrees about the x-axis, -pitch degrees about the y-axis, and +yaw degrees about the z-axis. In this case, the camera ends up pointing down and to the right of its original position.

With the -z option, the output would be:

0.000000 10.000000 2.500000 2.500000 3.535534 -35.264390 30.000000 144.735610

The last three numbers are x, y, and z rotation angles. The camera is considered to be originally on the z-axis, looking toward the origin with the x-axis to the right and the y-axis going up. The camera is rotated 144.7 degrees about the models z-axis, then 30 degrees about the models y-axis, and finally -35.2 degrees about the model x-axis.

Problems arise when using Euler angles, because certain orientations do not have a unique representation, and the program must arbitrarily select among an infinite number of possibilities. For example, when using yaw, pitch, and roll, the yaw and roll become indistinguishable when the pitch is 90 degrees.

When this happens, the roll is set to 0, and the following messages appear on standard error:

Warning: roll arbitrarily set to 0.0; yaw set to -0.585334 radians.
Warning: yaw and roll arbitrarily defined at time = 1.000000.

A similar effect occurs in xyz format when the rotation about the y-axis is 90 degrees.

Warning: x arbitrarily set to 0.0; z set to 0.000000.
Warning: x and z rotations arbitrarily defined at time = 9.000000.

One nice thing about quaternions is that you dont run into such problems.