ANIM_KEYREAD(1)

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
The following is an example of a typical keyframe generated by the `savekey' command. The time is 0, the viewsize is ten, 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 Eulers angles, because certain orientations do not have a uniqe 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.

SEE ALSO
mged(1), tabsub(1), anim_script(1), tabinterp(1)

AUTHOR
Carl J. Nuzman

COPYRIGHT
    This software is Copyright (c) 1993-2006 by the United States Government as represented by U.S. Army Research Laboratory.

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