NAME

anim_keyread - prepares key frames from the mged savekey command for interpolation

SYNOPSIS

anim_keyread [-y|z] key.file key.table

DESCRIPTION

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.

OPTIONS

-y

Specify the orientation in terms of yaw, pitch, and roll.

-z

Specify the orientation as a rotation about the z-axis, y-axis, and then x-axis, where the columns are in the order: x,y,z.

EXAMPLES

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 model's z-axis, then 30 degrees about the model's y-axis, and finally -35.2 degrees about the model x-axis.

DIAGNOSTICS

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 don't run into such problems.

AUTHOR

Carl J. Nuzman

COPYRIGHT

BUG REPORTS

Reports of bugs or problems should be submitted via electronic mail to devs@brlcad.org