

anim_orient [q  y  a  z  m] [vri] [q  y  a  z  m] [vriu] in.table out.table  
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 (xyz 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 xdirection, with the world yaxis pointing to the objects left and the zaxis 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 zdirection, with the world xaxis pointing to the objects right and the yaxis 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:
q:
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 xyzvector represents an axis of rotation and and w represents cos(omega/2), where omega is the angle to be rotated about the given axis.z:
xyz angles, in the order x, y, z. They represent a rotation of z degrees around the zaxis, followed by y degrees around the yaxis, followed by x degrees around the xaxis. If the code zr is used, then the angles will be read or written in radians rather than degrees.y:
yawpitchroll format, in that order. They represent a rotation of +roll degrees about the xaxis, pitch degrees about the yaxis, followed by +yaw degrees about the zaxis. If the code yr is used, angles are in radians rather than degrees.a:
azimuth, elevation, twist, in that order. They represent a rotation of twist degrees about the xaxis, +elevation degrees about the yaxis, and +azimuth + 180 degrees about the zaxis. Alternatively, they can be thought of as a 180degree rotation about the zaxis followed by a rotation of +twist degrees about the xaxis, elevation degrees about the yaxis, and +azimuth degrees about the zaxis.m:
premultiplication 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:
i
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 modeltoview 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.
v
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.u
This option forces the output orientation to be upright, or "rightside up," where the zaxis is the up direction. In terms of yaw, pitch, and roll, this means that the roll is forced to zero. Because this is a oneway operation, it can only be applied to the output orientation, not the input.
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 > yawpitchroll
anim_orient zr y < in.table > out.table
change radian xyz angles to yawpitchroll 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 xaxis, find the quaternion needed to turn the virtual camera in the same direction using rts orientation command
Example 7. Default Restoring yawpitchroll
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 "rightside "
anim_orient qv qvu < in.table > out.table
Force a table of view quaternions to represent "rightside up" orientations.
There are builtin trouble spots which occur, in ypr, xyz, or aet formats, when the pitch, yrotation, 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 xrotation is zero, depending on the format, and gives a warning to that effect on stderr.
Carl J. Nuzman
This software is Copyright (c) 19932013 by the United States Government as represented by U.S. Army Research Laboratory.
Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.
BRLCAD  ANIM_ORIENT (nged)  04/04/2016 
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.