# NAME

anim_track - make an script to model or animate the pads and wheels of a tracked vehicle.

# SYNOPSIS

anim_track [options] wheelfile < in.table > out.script

# DESCRIPTION

anim_track is designed to produce an animation script for the track pads and/or wheels of an articulated track. In addition, anim_track can produce an MGED source file for positioning the track pads during the construction on the vehicle model.

A track consists of a number of identical pads which are wrapped in a chain around two or more ordered wheels. Normally, the track is linear between the wheels. The exception is that between the first and last wheels, any extra track length is taken up in a hanging catenary arc.

Anim_track requires two input files. The first, referred to above as wheelfile, is a table which defines the initial track geometry by describing the wheels around which the track is to be wrapped. The first three columns of the table give the center point of the wheels, and the fourth column gives the radius of each wheel. The table contains one line for each wheel; the wheels should be listed in clockwise order as viewed from the right of the vehicle. This is the direction that the track pads move around the wheels when the vehicle is moving forward.

The track is part of a vehicle which has a front, back, left, right, top, and bottom. By default these directions are +x, -x, +y, -y, +z, and -z, respectively, but any orientation can be specified by the user with the -b option. The track is always confined to a plane which has no left to right variation; that is, the wheels can be in front of, behind, above, and below each other, but may not be to the left or right of each other. If the wheel positions specified in wheelfile do not lie in such a plane, then the first wheel defines the plane into which all of the other wheels are projected.

The track pads are spread evenly along the entire length of the track. The track segments between wheels are always linear, except for the segment between the first and last wheels. If there is any extra track length, it is taken up in a catenary arc which hangs down between the first and last wheels. Thus the first wheel in wheelfile should be the top front wheel of the vehicle, and the last wheel in wheelfile should be the top back wheel of the vehicle. Depending on the track length mode specified with the -l option, the catenary segment may or may not appear.

The second input file required by anim_track, referred to above as in.table, describes the state of the track in every frame of the animation. The format of this second file varies according to the command-line options. The first column of the file is ignored, but is expected to contain the time values corresponding to each frame. Next come one or more columns which specify, directly or indirectly, the distance that the track has rolled around the wheels in each frame (see the -u, -y, and -s options). Finally, the file may specify new wheel position for every frame (see the -v option).

# MODEL REQUIREMENTS

Certain model conventions are needed in order for the animation to work properly. First of all, if the wheels are to be animated, they must all be named wheelname i, where i ranges from 0 to one less than the number of wheels. wheelname is an arbitrary string. wheelname0 must be the top front wheel in a given track and wheelname(n-1) must be the top back wheel. The central axes of all the wheels should be parallel to each other and perpendicular to a plane containing all of the wheel centers.

The pads of the track should be identical instances or copies of a prototype pad object, and they all should be named padname i, where i ranges from 0 to one less than the number of pads. The prototype pad should be centered on the origin in the x and y directions. In the z direction, the inner, wheel-contacting surface of the pad should lie on the z=0 plane. The outer, ground-contacting surface should face the positive z-direction. The side of the pad which would connect with the pad in front of it should face the positive x direction, and the side which would connect with the pad behind it should face the negative x direction. If the pads are a part of a higher level combination, as they typically are, then the matrix between each pad and the higher combination may be modified at will as long as the prototype pad is not disturbed.

# OPTIONS

-p num_pads parent/basename
  Animate the track pads. This option takes two arguments; the number of pads in the track and a slash-separated path to the pad basename. For example, if there is a combination named "lpads" containing 80 track pads with names ranging from "pad.0" to "pad.79", then the correct arguments would be:

  -p 79 lpads/pad.

  Each frame of the output animation script will contain an animation command for each of the track pads.

-w parent/basename
  Animate the track wheels. This option takes one argument: a slash-separated path to the wheel basename. The number of wheels is obtained from the number of lines in the wheelfile. If there is, for example, a combination named "rwheels" containing 4 wheels named wheel_0, wheel_1, wheel_2, and wheel_3, then the correct argument is:

  -w rwheels/wheel_

  Each frame of the output animation script will contain an animation command for each of the wheels.

-b # # #
  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, and the track is therefore put into a xz plane.

-d # # #
  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.

-u
  User-specified track distance. The user should provide, in the second column of in.table, the distance that the track should be rolled around the wheels in each frame. This is the default.

-y
  Derive the track distance from a table of position, yaw, pitch, and roll. The second column through the seventh columns of the in.table should contain the position and orientation of the vehicle in every frame. The distance that the track should be rolled around the wheels is automatically calculated in every frame. If anim_script is being used with the same table to create the animation script for the vehicle itself, the -b and -d options to anim_script and anim_track should be the same.

-s
  Derive the track distance from a table of positions, using automatic steering. The second column through the fourth column of the in.table should contain the position of the vehicle in every frame. The distance that the track should be rolled around the wheels is automatically calculated in every frame, based on the assumption that the vehicle is always steered to face the direction of motion. If anim_script is being used with the same table to create the animation script for the vehicle itself, the -b and -d options to anim_script and anim_track should be the same.

-a
  Enable anti-strobing measures. When the track is rolling fast enough, track animations exhibit a strobing effect which may make the track appear to slow down or rotate backwards. This is an artifact of the discrete-time nature of the animations, and occurs when the distance traveled by the track in one frame is close to the pad length. If the -a option is selected, anim_track adds random jitter to the track's motion when the track speed is high enough to cause strobing. This causes a motion blur effect rather than strobing.

-v
  Specify new wheel positions in every frame. This option allows dynamic suspensions to be animated. If there are n wheels, then the last 2n columns of in.table should contain the front-back and up-down coordinates of each wheel, relative to the vehicle center and orientation specified with -d and -b. The columns should be in pairs: The front-back coordinate of the first wheel, followed by its up-down coordinate, followed by the front-back coordinate of the second wheel, and so on.

  If this option is not specified, then the wheel positions are fixed throughout the animation.

-c
  Calculate the track circumference, that is, the length of the shortest track that can wrap around a given set of wheels. When this option is used, no script is produced, and anim_track returns a single value representing the track circumference. If this option is used in conjunction with the -v option, then the output is a table giving the track circumference in every frame of the animation.

-lm
  Minimize the track length. With this option the length of the track is set to the track circumference in every frame, i.e. the track shrinks to fit the wheels.

-lf #
  Specify a fixed track length. The argument specifies the track length, which remains constant throughout the animation. If at any time the track circumference exceeds the track length, the program is aborted and a message is printed on standard error.

-ls #
  Specify a stretchable track. The argument specifies the initial track length. If at any time the track circumference exceeds the track length, the track length is increased to meet the need. The track length never decreases once it has been increased.

-le #
  Specify an elastic track. The argument specifies the initial track length. If at any time the track circumference exceeds the track length, the track length is increased to meet the need. When the track circumference decreases again, the track length also decreases, but it never gets shorter than its original length.

-i #
  Specify the initial offset of the track. By default, the first track pad is initially placed at the point where the catenary arc meets the first wheel. If an offset is specified, it represents the distance clockwise around the track to from this point to the desired initial point of the first pad. This option is typically used to align the track pads with drive wheel teeth.

-f #
  Specify the integer with which to begin numbering the frames of the animation script. The default is zero.

-r #
  Specify the common radius of all the wheels. In this case, the fourth column should be omitted from the wheelfile.

-g #
  Instead of an animation script, create a file which can be sourced by MGED to edit the track geometry. This will actually wrap the modeled pad instances around the wheels. The argument is the number of the frame which is to be emulated. For example, to model the pads in the positions they will have in the first frame of an animation, the specified frame number would be zero.

-mp command
  Specify the animation matrix command to apply to the pads. The default value is "rarc", meaning that the matrix between the pad and its parent is replaced by a new matrix. See the anim_script man page for more information.

-mw command
  Specify the animation matrix command to apply to the wheels. The default value is "lmul", meaning that the new matrix is multiplied onto the left of the old matrix between the pad and its parent combination. See the anim_script man page for more information.

# EXAMPLES

A typical use of anim_track would be to make an animation of a tank rolling across bumpy ground. By some method (such as physical simulation) you obtain the position of the center of the tank and its orientation at each time. You also need to obtain the position of the each wheel relative to the vehicle center at each time. All of this information is placed in 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,1005) and it faces the y-axis. An animation script for the tank itself is created as follows:

anim_script -d 0 0 1005 -b 90 0 0 /tank < tank.table > tank.script

Here tank.table specifies the position and orientation of the tank in each frame; the -d and -b options specify the original position and orientation of the tank in the database.

To create the model of the track, a prototype track pad is created, centered on the origin in the x and y directions, with the wheel-contacting surface face-down on the origin. The pad is 100mm long and 5mm thick. Ninety-six instances of the pad are created, with names "rpad.0" through "rpad.95", and grouped together in a combination called "rtrack".

Now, a file called rwheelfile is created, describing the positions and radii of the four wheels in the right track:

       1300  2000  1005     60
       1300  1500    55     50
       1300 -1500    55     50
       1300 -2000  1005     60

Two roadwheels both have radius 50mm, while the idler and drivewheels have a 60mm radius, and the wheels are named wh.0, wh.1, wh.2, and wh.3.

The following call checks the circumference of the track:

    %> anim_track -c  rwheelfile
    9502.448956

The 96 100mm-long pads should be sufficient to wrap around the wheels, leaving a shallow catenary arc between the idler and driver wheels.

The following call creates a file which can be used by MGED to wrap the pads around the wheels in the model.

    %> anim_track -g 0 -b 90 0 0 -d 0 0 1005 -lf 9600 -p 96 rtrack/rpad.
    rwheelfile <<EOF > rtrack.src
    ? 0 0
    ? EOF

In this case, in.table consisted of only one row and two columns. The two columns represented time and the distance the track should be rolled from its initial position. The -g option was set to 0 since frame zero was the only frame in the input table. The changes are applied to the geometry in MGED with the following command:

    mged> source rtrack.src

The pads are now permanently modeled in their new positions.

In order to animate the pads and wheels, the following command would be appropriate:

anim_track -p 96 rtrack/rpad. -w rwheel/wh. -d 0 0 1005 -b 90 0 0 -y -v -lf 9600 rwheelfile < in.table > rtrack.script

The in.table contains 15 columns specifying the time, the 3D position and yaw, pitch, and roll of the vehicle, and the front-back and up-down coordinates of each of the four wheels relative to the vehicle center. For example, one row of in.table could be:

0.5 234.0 1415.6 1005 45 0 0 2000 0 1500 -950 -1500 -950 -2000 -10

This would specify the new position of the vehicle half of a second into the animation, and indicate that the first three wheels remained in their original positions while the fourth wheel had dropped 10mm.

rtrack.script by itself causes the wheels to move and rotate and the pads to roll around them. When the entire tank, including the track, is moved along across the ground by track.script, the full effect is achieved. The two scripts can be combined with a script for the left track, using script_sort, to make the complete script.

# BUGS

Tracks must have at least two wheels. The front edge of wheel.(n-1) must stay behind the back edge of wheel.0, or the results are unpredictable. (Usually a lot of NaN's on the output).

# SEE ALSO

anim_script(1)

# AUTHOR

Carl J. Nuzman

# "BUG REPORTS"

Reports of bugs or problems should be submitted via electronic mail to <devs@brlcad.org>.