# FreeBSD Manual Pages

ANIM_ORIENT(nged) BRL-CAD User Commands ANIM_ORIENT(nged)NAMEanim_orient - convert between orientation formatsSYNOPSISanim_orient[q | y | a | z | m] [vri] [q | y | a | z | m] [vriu]in.tableout.tableDESCRIPTIONAnim_orientis 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), orm(rotation matrix). In addition, the output format may be modified by theuoption, and the input and output formats may be modified by ther,i, andvoptions. Theroption specifies that angles are read or written in radians, rather than degrees. Thei,v, anduoptions 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 manybrlcadobjects are modeled, and the default assumed by other animation routines such as anim_script. If thevcode 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 inmgedandrt. 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 codezris 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 codeyris 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 output modification codes are:iThis code is used in conjunction with any of the format codes to represent the inverse transformation. Under theicode, 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 theicode, 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 theioption is for handling "Viewrot" matrices used bymgedandrt. 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.vWhen this option is specified, the corresponding rotation is considered applied to the default view orientation, rather than the default object orientation, as explained above.uThis 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.EXAMPLESExample1.NormalizeQuaternionstoUnitMagnitudeanim_orient<in.table>out.tableNormalize a table of quaternions to unit magnitude. (Quaternions are the default format).Example2.XYZAngles->RotationMatrixanim_orientzm<in.table>out.tablechange xyz angles to a rotation matrixExample3.az/el/tw->viewrotanim_orientamiv<in.table>out.tableChange azimuth,elevation, and twist to a matrix suitable for thertviewrot command.Example4.TransposeMatricesanim_orientmmi<in.table>out.tableExample5.xyzangles->yaw-pitch-rollanim_orientzry<in.table>out.tablechange radian xyz angles to yaw-pitch-roll in degreesExample6.CameraTurningQuaternionanim_orientqqv<in.table>out.tablegiven a quaternion being applied to an object facing the x-axis, find the quaternion needed to turn the virtual camera in the same direction usingrt's orientation commandExample7.DefaultRestoringyaw-pitch-rollanim_orientyyi<in.table>out.tableGiven the yaw, pitch, and roll of an object, find the yaw, pitch, and roll which would bring it back to the default position.Example8.Orient"right-side"anim_orientqvqvu<in.table>out.tableForce a table of view quaternions to represent "right-side up" orientations.BUGSThere 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.AUTHORCarl J. NuzmanCOPYRIGHTThis software is Copyright (c) 1993-2019 by the United States Government as represented by U.S. Army Research Laboratory.BUG REPORTSReports of bugs or problems should be submitted via electronic mail to devs@brlcad.org BRL-CAD 08/27/2021 ANIM_ORIENT(nged)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | BUGS | AUTHOR | COPYRIGHT | BUG REPORTS

Want to link to this manual page? Use this URL:

<https://www.freebsd.org/cgi/man.cgi?query=anim_orient&manpath=FreeBSD+13.0-RELEASE+and+Ports>