Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ANIM_ORIENT(nged)	     BRL-CAD User Commands	     ANIM_ORIENT(nged)

       anim_orient - convert between orientation formats

       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 (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

       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

       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

       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

	   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

	   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

	   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.

       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"

       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.

       Carl J. Nuzman

       This software is	Copyright (c) 1993-2019	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

BRL-CAD				  08/27/2021		     ANIM_ORIENT(nged)


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

home | help