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

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anim_keyread1">
  <refmeta>
    <refentrytitle>ANIM_KEYREAD</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_keyread</refname>
    <refpurpose>prepares key frames from the mged <command>savekey</command> command for interpolation</refpurpose>
  </refnamediv>

  <!-- body begins here -->
  <refsynopsisdiv xml:id="synopsis">
    <cmdsynopsis sepchar=" ">
      <command>anim_keyread</command>    
      <arg choice="opt" rep="norepeat">-<replaceable>y</replaceable>|<replaceable>z</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>key.file</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>key.table</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsection xml:id="description"><info><title>DESCRIPTION</title></info>
    
    <para>
      <emphasis remap="I">Anim_keyread</emphasis> takes as input a file containing a 
      series of keyframes generated by the <emphasis remap="I">mged</emphasis>
      command <command>savekey</command>,  and produces a table containing
      the same information, except that the view orientation matrix is
      changed to a form that can be interpolated. The default form for the
      orientation information is the quaternion.  For each such keyframe in the input 
      file, <command>anim_keyread</command> will produce a row in the output file 
      containing the time, the viewsize, the position of the camera, and the 
      orientation of the camera, specified as a unit quaternion in the order 
      x, y, z, and w.
    </para>
  </refsection>

  <refsection xml:id="options"><info><title>OPTIONS</title></info>
    
    <variablelist remap="TP">
      <varlistentry>
	<term><option>-y</option></term>
	<listitem>
	  <para>Specify the orientation in terms of yaw, pitch, and roll.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-z</option></term>
	<listitem>
	  <para>Specify the orientation as a rotation about the z-axis, y-axis,
	  and then x-axis, where the columns are in the order: x,y,z.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection xml:id="examples"><info><title>EXAMPLES</title></info>
    
    <example><info><title>Typical <command>savekey</command> keyframe</title></info>
      
      <para>
	The following is an example of a typical keyframe generated by the
	<command>savekey</command> command. The time is 0, the viewsize is 10, the camera is at the
	point (2.5,2.5,3.53), and the camera orientation is specified by a
	matrix.
      </para>
      <literallayout remap=".nf" class="normal">

0.000000
1.000000000e+01
2.500000000e+00 2.500000000e+00 3.535533906e+00
-7.071067812e-01 7.071067812e-01 0.000000000e+00 0.000000000e+00
-5.000000000e-01 -5.000000000e-01 7.071067812e-01 0.000000000e+00
5.000000000e-01 5.000000000e-01 7.071067812e-01 0.000000000e+00
0.000000000e+00 0.000000000e+00 0.000000000e+00 1.000000000e+00

      </literallayout>
      <para>
	For the key frame shown above, the output would be:
      </para>
      
      <para>0.000000        10.000000       2.500000        2.500000        3.535534        0.146447        0.353553        0.853553        0.353553</para>

      <para>
	The last four numbers define the desired orientation as a
	quaternion.
      </para>
      
      <para>With the <option>-y</option> option, the output would be:</para>

      <para>0.000000        10.000000       2.500000        2.500000        3.535534        -135.000000      -45.000000      0.000000</para>

      <para>
	Here, the last three numbers are the yaw, pitch, and roll,
	which can be interpreted as follows: Imagine a camera at the origin
	originally facing the positive x-direction, with the z-axis going up
	and the y-axis positive to the left. The camera should  be rotated
	+roll degrees about the x-axis, -pitch degrees about the y-axis,
	and +yaw degrees about the z-axis. In this case, the camera ends up
	pointing down and to the right of its original position.
      </para>
      
      <para>With the -z option, the output would be:</para>
      
      <para>0.000000        10.000000       2.500000        2.500000        3.535534         -35.264390       30.000000       144.735610</para>
      
      <para>
	The last three numbers are x, y, and z rotation angles.
	The camera is considered to be originally on the z-axis, looking toward
	the origin with the x-axis to the right and the y-axis going up. The
	camera is rotated 144.7 degrees about the model's z-axis, then 30
	degrees about the model's y-axis, and finally -35.2 degrees about the
	model x-axis.
      </para>
    </example>
  </refsection>
  
  <refsection xml:id="diagnostics"><info><title>DIAGNOSTICS</title></info>
    
    <para>
      Problems arise when using Eulers angles, because
      certain orientations do not have a uniqe representation, and the program
      must arbitrarily select among an infinite number of possibilities. For
      example, when using yaw, pitch, and roll, the yaw and roll
      become indistinguishable when the pitch is 90 degrees.
    </para>
    
    <para>
      When this happens, the roll is set to 0, and the following
      messages appear on standard error:
    </para>
    <literallayout remap=".nf" class="normal">

Warning: roll arbitrarily set to 0.0; yaw set to -0.585334 radians.
Warning: yaw and roll arbitrarily defined at time = 1.000000.

    </literallayout>
    <para>A similar effect occurs in xyz format when the rotation about
    the y-axis is 90 degrees.</para>
    <literallayout remap=".nf" class="normal">

Warning: x arbitrarily set to 0.0; z set to 0.000000.
Warning: x and z rotations arbitrarily defined at time = 9.000000.

    </literallayout>
    <para>One nice thing about quaternions is that you don't run into such
    problems.</para>
  </refsection>

  <refsection xml:id="see_also"><info><title>SEE ALSO</title></info>
    
    <para><citerefentry><refentrytitle>mged</refentrytitle><manvolnum>nged</manvolnum></citerefentry>, <citerefentry><refentrytitle>tabsub</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>anim_script</refentrytitle><manvolnum>nged</manvolnum></citerefentry>, <citerefentry><refentrytitle>tabinterp</refentrytitle><manvolnum>1</manvolnum></citerefentry></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>
