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

<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="anim_hardtrack1">
  <refmeta>
    <refentrytitle>ANIM_HARDTRACK</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_hardtrack</refname>
    <refpurpose>make an animation script for the links and/or wheels of a tracked vehicle with rigid axles.</refpurpose>
  </refnamediv>
  
  <!-- body begins here -->
  <refsynopsisdiv xml:id="synopsis">
    <cmdsynopsis sepchar=" ">
      <command>anim_hardtrack</command>
      <arg choice="opt" rep="norepeat">-l <replaceable>num_links</replaceable><replaceable>linkname</replaceable></arg>
      <arg choice="opt" rep="norepeat">-w <replaceable>wheelname</replaceable></arg>
      <arg choice="opt" rep="norepeat"><replaceable>options</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>wheelfile</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>in.table</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>out.script</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsection xml:id="description"><info><title>DESCRIPTION</title></info>
    
    <para>
      <emphasis remap="I">Anim_hardtrack</emphasis> is designed to produce an animation script for the
      animation of a track and/or the wheels defining a track, where the wheels
      are rigidly fixed in place with respect to the vehicle. The main
      difference between <command>anim_hardtrack</command> and <emphasis remap="I">anim_track</emphasis>
      is that <emphasis remap="I">anim_track</emphasis> handles vehicles with dynamic axles. Both are 
      designed to be use in conjunction with <emphasis remap="I">anim_script,</emphasis>
      to achieve the final result.
    </para>
    
    <para>
      <emphasis remap="B" role="B">in.table</emphasis> is the file that will be used to animate the
      vehicle itself. By default, it is assumed that it contains a time column,
      three columns of translation information, and three columns specifying the
      vehicle's yaw, pitch, and roll. If it is desired that the vehicle be steered
      automatically, then the table should contain only time and position, and the
      <option>-s</option> option should be used.
    </para>
    
    <para>
      The track's geometry is defined by <emphasis remap="B" role="B">wheelfile</emphasis>,
      a table which contains one row for each wheel defining the track. The
      first three columns of the table specify the x, y, and z coordinates of
      the wheel centers. The fourth column specifies the radius of each wheel.
    </para>
    
    <para>
      The order in which the wheels are listed should be the order in which a
      link of the track would move around the wheels when the vehicle is moving
      forward (clockwise, when looking from the right of the vehicle).
      The wheel centers should all lie in a plane perpendicular to the vehicle's
      left-right axis. If this is not the case, <command>anim_hardtrack</command>
      uses the first wheel as the standard and projects all the other wheels into
      the same plane as the first wheel. By default, it is assumed that the
      vehicle's left-right axis is the y-axis. If the modeled vehicle has some
      other orientation, this must be specified with the <option>-b</option> option.
    </para>
    
    <para>
      By default, it is assumed that all of the link objects are modeled at the model origin,
      with the wheel-contacting surface centered on the origin and the
      ground-contacting surface facing up. The sides of each link which
      connect to other links should face the positive and negative x-axes.
      <emphasis remap="I">Anim_hardtrack</emphasis> prints the appropriate
      commands to move the links from the origin to the correct place around the wheels.
    </para>
    
    <para>
      If the links are modeled in place around the wheels to begin with, the <option>-p</option>
      and <option>-i</option> options are needed.
    </para>
    
  </refsection>
  
  <refsection xml:id="options"><info><title>OPTIONS:</title></info>
    
    <para>
      One or both of the first two options should always be specified.
    </para>
    <variablelist remap="TP">
      <varlistentry>
	<term><option>-l num linkname</option></term>
	<listitem>
	  <para>
	    Print animation scripts to animate the links of the track. Animation
	    commands will be printed for <emphasis remap="I">num</emphasis>
	    different links named <emphasis remap="I">linkname</emphasis>.0,
	    <emphasis remap="I">linkname</emphasis>.1, up through
	    <emphasis remap="I">linkname</emphasis>.(<emphasis remap="I">num</emphasis>-1).
	    A typical example of a linkname might be "tank/righttrack/links/link." The full 
	    pathname must be specified, because <command>anim_hardtrack</command>'s method is 
	    to roll the links around within the vehicle's tree structure so that when the 
	    whole vehicle "tank" is animated, the complete combination of rolling around 
	    and translating is achieved.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-w wheelname</option></term>
	<listitem>
	  <para>
	    Print animation scripts to rotate each wheel. The wheels are named 
	    <emphasis remap="I">wheelname</emphasis>.0, <emphasis remap="I">wheelname</emphasis>.1,
	    and so on, where <emphasis remap="I">wheelname</emphasis>.0 is the first wheel listed in
	    <emphasis remap="B" role="B">wheelfile</emphasis>. As with the links, the full pathname 
	    for the wheels should be specified.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-b # # #</option></term>
	<listitem>
	  <para>
	    Specify the yaw, pitch, and roll of the vehicle's axes with respect to the world axes. 
	    By default, the vehicle is assumed to have a yaw, pitch, and roll of 0.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-d # # #</option></term>
	<listitem>
	  <para>
	    Specify (in world coordinates) the centroid of the vehicle of which the track is a part. 
	    By default, the vehicle is assumed centered at the origin.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>

    <para>
      When calling <emphasis remap="I">anim_script</emphasis> to handle the animation of the vehicle
      itself, the parameters following the <option>-b</option> and <option>-d</option>
      options should be identical to those used for <command>anim_hardtrack</command>.
    </para>

    <variablelist remap="TP">
      <varlistentry>
	<term><option>-r #</option></term>
	<listitem>
	  <para>
	    Specify the common radius of all wheels. In this case, the fourth column
	    should be omitted from the <emphasis remap="B" role="B">wheelfile</emphasis>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-s</option></term>
	<listitem>
	  <para>Automatic steering. In this case, <emphasis remap="B" role="B">in.table</emphasis>
	  specifies only the time and position of the vehicle. The orientation is calculated to always 
	  face the vehicle in the direction of motion. This should be used when the <option>-s</option>
	  option is used by <emphasis remap="I">anim_script</emphasis> to animate the vehicle.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-f#</option></term>
	<listitem>
	  <para>
	    Specify the integer with which to begin numbering frames. Default is zero.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-p</option></term>
	<listitem>
	  <para>
	    Animate placed links, rather than links stored at the origin.
	    In order for placed links to be animated, they must be equally spaced
	    around the wheels defining the track. The track must be formed of arcs
	    around the wheels and straight lines between the wheels, and the links
	    must be numbered clockwise as seen from the right.  By default, it is assumed 
	    that the center of the first link, linkname.0, is at the beginning of the
	    straight track segment between wheel.(n-1) and wheel.0. If this is
	    not the case, the position of the first link must be identified with the
	    <option>-i#</option> option.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-i#</option></term>
	<listitem>
	  <para>
	    Specify the initial offset of the first link. If this option is
	    not used, the initial position of linkname.0 is assumed to be the
	    beginning of the straight track segment between wheel.(n-1) and wheel.0.
	    If it is used, the argument specifies the distance clockwise around the
	    track from the default position to the actual desired offset. If the
	    links are modeled at the origin, the user can choose any offset. This
	    can be useful for lining up the links with gears of a drive wheel, for
	    example.  If the <option>-p</option> option is being used to animate preplaced 
	    links, then it is essential that the actual offset of the first preplaced link 
	    be specified.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-g#</option></term>
	<listitem>
	  <para>Return "arced" for mged instead of "anim" for rt.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-ml&lt;string&gt;</option></term>
	<listitem>
	  <para>
	    Use <emphasis remap="B" role="B">&lt;string&gt;</emphasis> for the link command. Defaults to "rarc."
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-mw&lt;string&gt;</option></term>
	<listitem>
	  <para>Use <emphasis remap="B" role="B">&lt;string&gt;</emphasis> for the wheel command. 
	  Defaults to "lmul."
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><option>-c</option></term>
	<listitem>
	  <para>Only output the circumference of the track.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    
    <refsection xml:id="output"><info><title>Output:</title></info>
      
      <para>
	The output is a script containing as many frames as there are positions in
	<emphasis remap="B" role="B">in.table</emphasis>. If there are <emphasis remap="I">n</emphasis>
	links and <emphasis remap="I">k</emphasis> wheels, each frame contains up to
	<emphasis remap="I">n</emphasis>+<emphasis remap="I">k</emphasis> anim commands, either:
      </para>
      <literallayout remap=".nf" class="normal">

anim linkname.i matrix lmul
[... matrix ...] ;
				or
anim wheelname.j matrix lmul
[... matrix ...] ;

for 0&lt;=i&lt;n and 0&lt;=j&lt;k.

      </literallayout>
    </refsection>
  </refsection>

  <refsection xml:id="examples"><info><title>EXAMPLES</title></info>
    
    <para>
      Suppose you want to make an animation of a tank rolling across
      flat ground. A list of desired positions is created, perhaps by
      interpolating between a few key positions; this information is placed
      in a four-column animation table, in.table. The model of the tank is stored in
      model.g as a combination named "tank." Its centroid is at the
      point (0,0,1000) and it faces the y-axis. An animation script for the
      tank itself is created as follows:
    </para>
    <para>
    <userinput>anim_script -s -d 0 0 1000 -b 90 0 0 /tank &lt; in.table &gt; tank.script</userinput>
    </para>
    <para>
      Suppose that there are two roadwheels and a drivewheel (tank/rwheel/wheel.i, 0&lt;=i&lt;3) which define
      the shape of the right track. A file called <emphasis remap="B" role="B">rwheelfile</emphasis>
      is created:
    </para>
    <literallayout remap=".nf" class="normal">

1500   -2000    30      30
1500   0        1000    35
1500   2000     30      30

    </literallayout>
    <para>
      This <emphasis remap="B" role="B">rwheelfile</emphasis> lists the position and
      radius of each of the three wheels.
    </para>

    <para>
      There are eighty links which make up the right track (tank/rtrack/link.i, 0&lt;=i&lt;80).
      The links of the right track are all modeled at the origin with the outer, ground-contacting surface
      facing up and the inner, wheel-contacting surface centered at the
      origin.
    </para>

    <para>
      The appropriate call to <command>anim_hardtrack</command> is now:
    </para>
    
    <para>
      <userinput>
      anim_hardtrack -d 0 0 1000 -b 90 0 0 -w tank/rwheel -l 80 tank/rtrack/link
      rwheelfile &lt; in.table &gt; rtrack.script
      </userinput>
    </para>

    <para>
      Suppose that the left track is similar to the right track,
      except that all the wheels are of radius 30 units, and the links, rather
      than being stored at the origin, are actually placed in position around
      the left wheels to begin with. The <emphasis remap="B" role="B">lwheelfile</emphasis>
      would be:
    </para>
    <literallayout remap=".nf" class="normal">

-1500   -2000   30
-1500   0       1000
-1500   2000    30

    </literallayout>
    <para>and the call would be:</para>

    <para>
      <userinput>
      anim_hardtrack -p -r 30 -d 0 0 1000 -b 90 0 0 -w tank/lwheel
	-l 80 tank/ltrack/link lwheelfile &lt; in.table &gt; ltrack.script
      </userinput>
    </para>

    <para>
      Here, it is assumed that tank/ltrack/link.0 is initially at the
      beginning of the straight track segment between lwheel.2 and lwheel.0,
      that is, at the point (2000,1500,-1000) in the vehicle's coordinates.
      If, instead, the first link is initially centered halfway between the
      two roadwheels, this must be specified with the <option>-i#</option>
      option. If the link's actual position is 2000 units farther around the 
      track than expected:
    </para>

    <para>
      <userinput>
      anim_hardtrack -i 2000 -p -r 30 -d 0 0 1000 -b 90 0 0 -w tank/lwheel
    -l 80 tank/ltrack/link lwheelfile &lt; in.table &gt; ltrack.script
      </userinput>
    </para>

    <para>One final step may remain. The above procedure produces a script with rigid
    naming conventions, in order to make input simple. This may mean that
    the names in the script do not match the names in model.g. An editor
    should then be used at the end to replace all instances of the
    conventional name with the real name; for example, in this case it may
    be necessary to replace "rwheel.1" with "r_drivewheel".</para>
    
    <para><emphasis remap="B" role="B">Tank.script</emphasis>,
    <emphasis remap="B" role="B">rtrack.script</emphasis>, and <emphasis remap="B" role="B">ltrack.script</emphasis>
    can be combined with <emphasis remap="I">anim_sort</emphasis> to make the complete script.</para>

  </refsection>
  
  <refsection xml:id="bugs"><info><title>BUGS</title></info>
    
    <para>Tracks must have at least two wheels, and they must be listed in clockwise
    order, or the results are unpredictable.</para>
  </refsection>

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