<!-- Converted by db4-upgrade version 1.0 -->

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anim_orient1">
  <refmeta>
    <refentrytitle>ANIM_ORIENT</refentrytitle>
    <manvolnum>nged</manvolnum>
    <refmiscinfo class="source">BRL-CAD</refmiscinfo>
    <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
  </refmeta>
  <refnamediv xml:id="name">
    <refname>anim_orient</refname>
    <refpurpose>convert between orientation formats</refpurpose>
  </refnamediv>
  
  <!-- body begins here -->
  <refsynopsisdiv xml:id="synopsis">
    <cmdsynopsis sepchar=" ">
      <command>anim_orient</command>
      <group choice="opt" rep="norepeat">
	<arg choice="plain" rep="norepeat">q</arg>
	<arg choice="plain" rep="norepeat">y</arg>
	<arg choice="plain" rep="norepeat">a</arg>
	<arg choice="plain" rep="norepeat">z</arg>
	<arg choice="plain" rep="norepeat">m</arg>
      </group>
      <arg choice="opt" rep="norepeat"><replaceable>vri</replaceable></arg>
      <group choice="opt" rep="norepeat">
	<arg choice="plain" rep="norepeat">q</arg>
	<arg choice="plain" rep="norepeat">y</arg>
	<arg choice="plain" rep="norepeat">a</arg>
	<arg choice="plain" rep="norepeat">z</arg>
	<arg choice="plain" rep="norepeat">m</arg>
      </group>
      <arg choice="opt" rep="norepeat"><replaceable>vriu</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>in.table</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>out.table</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>


  <refsection xml:id="description"><info><title>DESCRIPTION</title></info>
    
    <para>
      <emphasis remap="I">Anim_orient</emphasis> 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:
      <emphasis remap="B" role="bold">q</emphasis> (quaternion), <emphasis remap="B" role="bold">y</emphasis>
      (yaw,pitch, and roll), <emphasis remap="B" role="bold">a</emphasis> (azimuth, elevation, and twist),
      <emphasis remap="B" role="bold">z</emphasis> (x-y-z angles), or <emphasis remap="B" role="bold">m</emphasis>
      (rotation matrix).  In addition, the output format may be modified by the 
      <emphasis remap="B" role="bold">u</emphasis> option, and the input and output formats may be modified by the
      <emphasis remap="B" role="bold">r</emphasis>, <emphasis remap="B" role="bold">i</emphasis>,
      and <emphasis remap="B" role="bold">v</emphasis> options. The <emphasis remap="B" role="bold">r</emphasis>
      option specifies that angles are read or written in radians, rather than degrees. The
      <emphasis remap="B" role="bold">i</emphasis>,<emphasis remap="B" role="bold">v</emphasis>,
      and <emphasis remap="B" role="bold">u</emphasis> options are explained below.
    </para>

    <para>
      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.
    </para>

    <para>
      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 <emphasis remap="I">brlcad</emphasis>
      objects are modeled, and the default assumed by other animation routines such as
      anim_script. If the <emphasis remap="B" role="bold">v</emphasis> 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
      <emphasis remap="I">mged</emphasis> and <emphasis remap="I">rt</emphasis>. Some common uses of the v
      option are demonstrated in the examples section.
    </para>

    <para>The input and output format codes are:</para>
    
    <variablelist remap="TP">
      <varlistentry>
	<term><emphasis remap="B" role="bold">q:</emphasis></term>
	<listitem>
	  <para>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.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">z</emphasis>:</term>
	<listitem>
	  <para>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
	  <emphasis remap="B" role="bold">zr</emphasis>
	  is used,
	  then the angles will be read or written in radians
	  rather than degrees.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">y</emphasis>:</term>
	<listitem>
	  <para>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
	  <emphasis remap="B" role="bold">yr</emphasis>
	  is used, angles are in radians rather than degrees.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">a</emphasis>:</term>
	<listitem>
	  <para>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.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">m</emphasis>:</term>
	<listitem>
	  <para>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.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <para>The input and ouput modification codes are:</para>
    <variablelist remap="TP">
      <varlistentry>
	<term><emphasis remap="B" role="bold">i</emphasis></term>
	<listitem>
	  <para>This code is used in conjunction with any of the format codes to represent
	  the inverse transformation. Under the
	  <emphasis remap="B" role="bold">i</emphasis>
	  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
	  <emphasis remap="B" role="bold">i</emphasis>
	  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.</para>
	  
	  <para>One common use of the
	  <emphasis remap="B" role="bold">i</emphasis>
	  option is for handling "Viewrot" matrices used
	  by
	  <emphasis remap="I">mged</emphasis>
	  and
	  <emphasis remap="I">rt</emphasis>.
	  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.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">v</emphasis></term>
	<listitem>
	  <para>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.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><emphasis remap="B" role="bold">u</emphasis></term>
	<listitem>
	  <para>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.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsection>
  
  <refsection xml:id="examples"><info><title>EXAMPLES</title></info>
    
  
    <example><info><title>Normalize Quaternions to Unit Magnitude</title></info>
      
      <para>
	<userinput>anim_orient &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	Normalize a table of quaternions to unit magnitude. (Quaternions are the
	default format).
      </para>
    </example>

    <example><info><title>XYZ Angles -&gt; Rotation Matrix</title></info>
      
      <para>
	<userinput>anim_orient z m &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	change xyz angles to a rotation matrix
      </para>
    </example>
  
    <example><info><title>az/el/tw -&gt; viewrot</title></info>
      
      <para>
	<userinput>anim_orient a miv &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	Change azimuth,elevation, and twist to a matrix suitable for the
	<emphasis remap="I">rt</emphasis> viewrot command.
      </para>
    </example>
    
    <example><info><title>Transpose Matricies</title></info>
      
      <para>
	<userinput>anim_orient m mi &lt; in.table &gt; out.table</userinput>
      </para>
    </example>

    
    <example><info><title>xyz angles -&gt; yaw-pitch-roll</title></info>
      
      <para>
	<userinput>anim_orient zr y &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	change radian xyz angles to yaw-pitch-roll in degrees
      </para>
    </example>
    
    <example><info><title>Camera Turning Quaternion</title></info>
      
      <para>
	<userinput>anim_orient q qv &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	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
	<emphasis remap="I">rt</emphasis>'s orientation command
      </para>
    </example>
    
    <example><info><title>Default Restoring yaw-pitch-roll</title></info>
      
      <para>
	<userinput>anim_orient y yi &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	Given the yaw, pitch, and roll of an object, find the yaw, pitch, and
	roll which would bring it back to the default position.
      </para>
    </example>
    
    <example><info><title>Orient "right-side "</title></info>
      
      <para>
	<userinput>anim_orient qv qvu &lt; in.table &gt; out.table</userinput>
      </para>
      <para>
	Force a table of view quaternions to represent "right-side up"
	orientations.
      </para>
    </example>
  </refsection>

  <refsection xml:id="bugs"><info><title>BUGS</title></info>
    
    <para>
      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.
    </para>
  </refsection>
 
  <info>
    <author>
      <personname>Carl J. Nuzman</personname>
      <contrib></contrib>
    </author>
  </info>
 
  <refsection xml:id="copyright"><info><title>COPYRIGHT</title></info>
    
    <para>This software is Copyright (c) 1993-2012 by the United States
    Government as represented by U.S. Army Research Laboratory.</para>
  </refsection>
  
  <refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
  <para>Reports of bugs or problems should be submitted via electronic
  mail to &lt;devs@brlcad.org&gt;.</para>
  </refsection>
</refentry>
