NAME

anim_orient - convert between orientation formats

SYNOPSIS

anim_orient [q | y | a | z | m] [vri] [q | y | a | z | m] [vriu] in.table out.table

DESCRIPTION

Anim_orient is a filter which translates a table of orientation information from one format to another. The method used is to convert the input format to a matrix, then convert the matrix to the desired output format. The input format is specified in the first argument, and the output format is specified in the second. The orientation formats must be one of the following: q (quaternion), y (yaw,pitch, and roll), a (azimuth, elevation, and twist), z (x-y-z angles), or m (rotation matrix). In addition, the output format may be modified by the u option, and the input and output formats may be modified by the r, i, and v options. The r option specifies that angles are read or written in radians, rather than degrees. The i,v, and u options are explained below.

To clearly understand the operation of anim_orient, it is important to examine the difference between orientation and rotation. The matrices, quaternions, and angles used by anim_orient specify rotations. These are transformations which, when applied to an object, preserve its shape but change its orientation with respect to a fixed set of axes. Given the initial orientation of an object, a rotation defines the final orientation, but different initial orientations will yield different final orientations. In order to represent orientations with rotations, we must define a default initial orientation for the object. Then a given matrix, quaternion, or set of angles represents the orientation resulting from applying the rotation to the initial object orientation.

If no modifying codes are specified, anim_orient assumes that the default orientation of the object in question faces the positive x-direction, with the world y-axis pointing to the object's left and the z-axis pointing up. This is the orientation in which many brlcad objects are modeled, and the default assumed by other animation routines such as anim_script. If the v code is specified, then the default orientation is taken to be facing the negative z-direction, with the world x-axis pointing to the object's right and the y-axis pointing up. This is the default orientation of the eye in mged and rt. Some common uses of the v option are demonstrated in the examples section.

The input and output format codes are:

Quaternions, in the order x,y,z,w. This is the default input and output format. The output will always be unit quaternions. For a unit quaternion, the xyz-vector represents an axis of rotation and and w represents cos(omega/2), where omega is the angle to be rotated about the given axis.

x-y-z angles, in the order x, y, z. They represent a rotation of z degrees around the z-axis, followed by y degrees around the y-axis, followed by x degrees around the x-axis. If the code zr is used, then the angles will be read or written in radians rather than degrees.

yaw-pitch-roll format, in that order. They represent a rotation of +roll degrees about the x-axis, -pitch degrees about the y-axis, followed by +yaw degrees about the z-axis. If the code yr is used, angles are in radians rather than degrees.

azimuth, elevation, twist, in that order. They represent a rotation of -twist degrees about the x-axis, +elevation degrees about the y-axis, and +azimuth + 180 degrees about the z-axis. Alternatively, they can be thought of as a 180-degree rotation about the z-axis followed by a rotation of +twist degrees about the x-axis, -elevation degrees about the y-axis, and +azimuth degrees about the z-axis.

pre-multiplication rotation matrix. Sixteen numbers form a 4x4 matrix, although only the nine elements in the upper left corner are actually used. This is the format used at the interior of the conversion routine. It is a transformation from initial orientation to a new orientation.

The input and output modification codes are:

This code is used in conjunction with any of the format codes to represent the inverse transformation. Under the i code, a matrix, quaternion, or set of angles represents the inverse of the rotation that it normally represents. For example, normally, the orientation corresponding to a given matrix is the orientation that the default object ends up in after the matrix is applied to it. With the i code, a given matrix represents the orientation an object should be placed in so that applying the matrix puts it back in the default orientation.

One common use of the i option is for handling "Viewrot" matrices used by mged and rt. The viewrot matrix is a model-to-view matrix, which is the transpose (inverse) of the matrix which would conceptually be applied to an eye object to put it in the desired place in the model.

When this option is specified, the corresponding rotation is considered applied to the default view orientation, rather than the default object orientation, as explained above.

This option forces the output orientation to be upright, or "right-side up," where the z-axis is the up direction. In terms of yaw, pitch, and roll, this means that the roll is forced to zero. Because this is a one-way operation, it can only be applied to the output orientation, not the input.

EXAMPLES

Example 1. Normalize Quaternions to Unit Magnitude

anim_orient < in.table > out.table

Normalize a table of quaternions to unit magnitude. (Quaternions are the default format).

Example 2. XYZ Angles -> Rotation Matrix

anim_orient z m < in.table > out.table

change xyz angles to a rotation matrix

Example 3. az/el/tw -> viewrot

anim_orient a miv < in.table > out.table

Change azimuth,elevation, and twist to a matrix suitable for the rt viewrot command.

Example 4. Transpose Matrices

anim_orient m mi < in.table > out.table

Example 5. xyz angles -> yaw-pitch-roll

anim_orient zr y < in.table > out.table

change radian xyz angles to yaw-pitch-roll in degrees

Example 6. Camera Turning Quaternion

anim_orient q qv < in.table > out.table

given a quaternion being applied to an object facing the x-axis, find the quaternion needed to turn the virtual camera in the same direction using rt's orientation command

Example 7. Default Restoring yaw-pitch-roll

anim_orient y yi < in.table > out.table

Given the yaw, pitch, and roll of an object, find the yaw, pitch, and roll which would bring it back to the default position.

Example 8. Orient "right-side "

anim_orient qv qvu < in.table > out.table

Force a table of view quaternions to represent "right-side up" orientations.

BUGS

There are built-in trouble spots which occur, in ypr, xyz, or aet formats, when the pitch, y-rotation, or elevation is an odd multiple of 90 degrees, because at this point the other two angles become indistinguishable. The program makes the arbitrary assumption that the roll is zero or that the x-rotation is zero, depending on the format, and gives a warning to that effect on stderr.

AUTHOR

Carl J. Nuzman

COPYRIGHT

BUG REPORTS

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