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
BRL-CAD
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:
-
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
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.
-
z:
-
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.
-
y:
-
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.
-
a:
-
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.
-
m:
-
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 ouput 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 the 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.
-
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 "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 not
an invertible
operation, it can only be applied to the output orientation, not
the input.
EXAMPLES
- Normalize a table of quaternions to unit magnitude. (quaternions are the
default format).
anim_orient < in.table > out.table
- change xyz angles to a rotation matrix
anim_orient z m < in.table > out.table
- change azimuth,elevation, and twist to a matrix suitable for the
rt
viewrot command
anim_orient a miv < in.table > out.table
- transpose matrices
anim_orient m mi < in.table > out.table
- change radian xyz angles to yaw-pitch-roll in degrees
anim_orient zr y < 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
anim_orient q qv < 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.
anim_orient y yi < in.table > out.table
- Force a table of view quaternions to represent "right-side up"
orientations.
anim_orient qv qvu < in.table > out.table
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 standard error.
AUTHOR
Carl J. Nuzman
"BUG REPORTS"
Reports of bugs or problems should be submitted via electronic
mail to <CAD@BRL.MIL>.