ANIM_SCRIPT(1)

NAME
anim_script - make an animation script for one object

SYNOPSIS
anim_script [-v #] [-r|t|s] [-q][-p] [-a|b # # #] [-c|d # # #] [-f #] [-m cmd] [objectname] < in.table > out.script

DESCRIPTION
Anim_script is designed to produce an animation script for the animation of the virtual camera or one brlcad object at a time. It is complementary to tabsub in that it performs a similar function, but with a different philosophy.

Both anim_script and tabsub use one row of an animation table to produce one frame of an animation script. With tabsub, the user supplies a template file which controls the form of the animation frames. This allows the maximum user control, but also requires a good understanding of the script format. With anim_script, the user supplies all the necessary information on the command line. The range of possible output scripts is limited, but the user does not have to deal directly with the details. Both routines have special features which make certain common situations easy to do. One of the most important special features of anim_script is the ability to specify a reference position and orientation, as explained below.

The objectname is the name of the object which is to be animated, as it will appear in the ouput script. For example, if "hatch1" is a member of "turret" which is a member of "tank" which is one of the objects specified on the command line of the call to rt, then the objectname "tank/turret/hatch1" or simply "turret/hatch1" would be used to animate the hatch. The tank itself would be referred to by the name, "/tank". Note that toplevel objects should be preceeded by a slash. If view animation is being performed, no objectname should be included.

in.table should be a seven-column animation table, specifying the time, 3d position, yaw, pitch and roll of the object (or camera), although this changes if the -r, -t, -s, or -v# options are used.

OPTIONS

-r  in.table is a four-column file including time and rotation information only. No translation will occur.

-t  in.table is a four-column file including time and translation information only. No rotation will occur.

-s  in.table is a four-column file including time and translation information only. The vehicle will be rotated (steered) to face the direction of motion.

-q  Quaternion orientation. Any orientation information in in.table will be in quaternion form, in the order x,y,z,w. The identity quaternion representing no orientation change is (0,0,0,1).

-p  Permuted orientation. This option indicates that transformations defined by the quaternions should be applied to an object which has first been placed in rt's default eye orientation. Thus, the identity quaternion represents yawing the object 90 degrees to the left and then pitching it 90 degrees downward. The quaternions produced by mged's saveview command and used by rt's orientation command are quaternions of this type. See anim_orient for more information.

-v# The desired output is a view animation script, rather than an object animation script. No object should be specified. The argument can be any floating point number. If the argument is positive, the command:

    viewsize #;

    will be placed at the beginning of the ouput file. If it is zero, the `viewsize' command is omitted from the output script. If it is negative, then the viewsize for each frame is expected to be in the first column after the time in in.table. A `viewsize' command would then be included immediately after the `start' command of each frame.

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

The remaining options give information about the object which is to be animated.

-a # # #
    or

-b # # #
    These options take three arguments, which are the yaw, pitch, and roll of the object's axes with respect to the world axes. With -a, rotations specified in the infile will be applied with respect to the object's axes. With the -b option, the object is rotated so that its axes coincide with the world axes, and then all rotations and translations are carried out with respect to the world axes. The -b option is particularly useful in conjunction with the -s option, because it tells anim_script which way the front of the vehicle faces. See the examples below.

-c # # #
    or

-d # # #
    These options take three arguments, which are the x, y, and z coordinates of the point which is to be considered the "centroid" of the object. All rotations will occur about this point. If -c is used, translations from the input table will be considered to be relative displacements from this point. If -d is used, the translations in the input table will be interpreted as absolute displacement from the world origin. The direction of translation in both cases is along the world axes, unless the -a option has been used, in which case the translations are with respect to the object's axes. See the examples below.

When the -v option is used, the virtual camera is the object being animated, and so the meaning of the preceeding four options changes somewhat. The -c and -a options are not useful in this context. The -d option can be thought of as specifying the position and orientation of a virtual tripod with respect to the camera lens. The translations and rotations specified in the input table will be applied to the tripod, to which the camera is rigidly attached. For example, the option -d 10 0 -2 in conjunction with the -v# option means that the virtual tripod is 10 units in front of the camera and 2 units below the camera's line of sight. The option -b -90 0 0 in this context would mean that the front of the virtual tripod faces 90 degrees to the right of the virtual camera. As translation and rotation information are read in from in.table, they are applied to the virtual tripod, with the virtual camera rigidly attached. See below for examples of how this might be used.

-m cmd
    Specify a matrix command to use in, object animation. The default value is "lmul", which means that matrices in the output script are multiplied onto the left of the matrix between the object being animated and its parent. The matrix residing between the object and its parent is referred to as the current arc. The possible matrix commands are the following:
         lmul   - left-multiply the matrix onto the current arc
         rmul   - right-multiply the matrix onto the current arc
         rarc   - replace the current arc with the matrix
         rstack - replace the stack of ancestor matrices with the matrix
         rboth  - replace the current arc with the matrix and replace the
    		 stack of ancestor matrices with the identity matrix.
    This option is intended primarily to give expert users additional flexibility, and shouldn't be needed by most animators.

EXAMPLES
To animate a truck which is modeled with the front facing the positive x-direction, the position of the center of the truck and its orientation at each time should be in truck.table. If the center of the modeled truck is at the point (234,0,1200) then the following command could be used:

anim_script -d 234 0 1200 /truck < truck.table > truck.script.

If the front of the model truck faces (for some reason) halfway between the x and y axes, a -b option is added, to show the relationship between world and truck axes:

anim_script -b 45 0 0 -d 234 0 1200 /truck < truck.table > truck.script.

To steer the truck automatically to face the direction of motion, the -s option is added, and the orientation columns should be removed from truck.table.

anim_script -s -b 45 0 0 -d 234 0 1200 /truck < truck.table > truck.script.

Animating a steering wheel: Suppose the steering wheel is stored in the database so that the axis it turns on is at an yaw of -135 degrees and an pitch of 30 degrees. It passes through the point (700,800,2400). Then we select "rotation only" with -r and specify the relationship between the steering wheels axes and the world with the -a and -c options. In roll.table we put the time, two zero columns, and a column specifying the roll of the wheel (How much it is to be twisted).

anim_script -r -a -135 30 0 -c 700 800 2400 truck/steering_column/wheel < roll.table > steer.table

Alternativly, if the turning of the wheel was stored in the yaw (second) column of a file, turn.table, a different set of axes would be used to achieve the same effect:

anim_script -r -a 45 60 0 -c 700 800 2400 truck/steering_column/wheel < turn.table > steer.table

To animate seven little men doing simultaneous backflips in different places, you would want to use relative motion. That is, a translation vector of (0,0,1) means move one unit upward, instead of move to the point (0,0,1). For each little man, we specify his position in the model using the -c option. Then we can use the same backflip instuctions for each of the little men.

anim_script -c 12 34 5 /little.man.one < generic.backflip.table > little.man.one.script

anim_script -c -3 13 5 /little.man.two < generic.backflip.table > little.man.two.script

and so on.

  Camera examples
If we know the desired postion of the camera and its orientation at each time, it's very simple. The -v# option indicates that the view is being animated; no object is specified.

anim_script -v0 < view.table > view.script

To follow a truck, so that the camera is always ten units behind and 4 units above it, we specify a virtual tripod in front of and below the camera:

anim_script -v0 -d 10 0 -4 < truck.table > view.script

To do the same thing but with the camera turned to look at the right side of the truck, we specify that the virtual tripod originally faces to the right, so that the camera faces its right side. Thus when the virtual tripod is placed in the same position and orientation as the truck, the camera will be looking at the right side of the truck.

anim_script -v0 -d 10 0 -4 -b -90 0 0 < truck.table > view.script

BUGS
The reading of command line options which take more than one argument are somewhat finicky. For example, it understands the option "-d 1 1 1" but not "-d1 1 1".

AUTHOR
Carl J. Nuzman

COPYRIGHT
    This software is Copyright (c) 1993-2010 by the United States Government as represented by U.S. Army Research Laboratory.

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