# NAME

anim_cascade - evaluate movement of an object relative to a moving frame of reference

# SYNOPSIS

anim_cascade [-s][-o(f|r|a)] [-(f|r|a)(c|y) # # #] < input.table > output.table

# DESCRIPTION

Anim_cascade is designed to enable the user to control the movement of objects relative to other objects. In the normal mode of operation, the user supplies the position and orientation of a (possibly moving) frame of reference and the position and orientation of an object relative to the frame of reference, and anim_cascade produces the absolute position and orientation of the object at each point in time. All orientations are specified as yaw, pitch, and roll. The columns of the input table are:

time fx fy fz fyaw fpitch froll rx ry rz ryaw rpitch rroll

and the columns of the output table are:

time ax ay az ayaw apitch aroll

Here "f" refers to the frame of reference, "r" refers to the position and orientation of the object relative to the frame, and "a" refers to the absolute position and orientation of the object.

# OPTIONS

-or
  Output the relative position and orientation. If this option is specified, anim_cascade will expect the absolute position and orientation of the frame of reference and the object as input, and will produce the position and orientation or the object relative to the frame as output. The input columns should be:

  time fx fy fz fyaw fpitch froll ax ay az ayaw apitch aroll

  and the output columns will be:

  time rx ry rz ryaw rpitch rroll

-of
  Output the frame of reference. If this option is specified, anim_cascade will expect the absolute and relative positions and orientations of the object as input, and will produce the corresponding frame of reference as output. The input columns should be:

  time ax ay az ayaw apitch aroll rx ry rz ryaw rpitch rroll

  and the output columns will be:

  time fx fy fz fyaw fpitch froll

-fc # # #
  Specify a constant position for the frame of reference. The columns fx, fy, and fz should be omitted from the input table, and the command-line arguments will be used instead. This has no effect if used in conjunction with -of
-fy # # #
  Specify a constant orientation for the frame of reference. The columns fyaw, fpitch, and froll should be omitted from the input table, and the command-line arguments will be used instead. This has no effect if used in conjunction with -of.
-rc # # #
  Specify a constant position of the object relative to the frame of reference. The columns rx, ry, and rz should be omitted from the input table, and the command-line arguments will be used instead. This has no effect if used in conjunction with -or.
-ry # # #
  Specify a constant orientation of the object relative to the frame of reference. The columns ryaw, rpitch, and rroll should be omitted from the input table, and the command-line arguments will be used instead. This has no effect if used in conjunction with -or.
-ac # # #
  Specify a constant absolute position for the object. The columns ax, ay, and az should be omitted from the input table, and the command-line arguments will be used instead. This has no effect unless used in conjunction with -or or -of.
-ay # # #
  Specify a constant absolute orientation for the object. The columns ayaw, apitch, and aroll should be omitted from the input table, and the command-line arguments will be used instead. This has no effect unless used in conjunction with -or or -of.
-s
  Suppress time column. No time column is read or written.

  Note: When all of the input columns are specified with command-line arguments, then standard input is not read and only one line of output is produced. The time value will be set to zero, unless it is suppressed.

# EXAMPLES

1. Suppose that you want the virtual camera to pan in a circle around a moving vehicle, always staying a fixed distance from the vehicle. You should already have an animation table with the time, position, and orientation of the vehicle in each frame. This will be the moving frame of reference. Next, you should create an animation table which describes how the camera should move relative to the vehicle; in other words, how the camera would need to move if the vehicle were standing still at the origin. The columns of the second animation table should be appended to the columns of the first table (using paste, for example), to create the input table. Anim_cascade will produce an absolute animation table for the camera, suitable to use as input to anim_script:

anim_cascade < input.table | anim_script -v500 > view.script

2. Suppose that you have an animation path for an object and you want to know when it crosses a given oblique plane. You can use the -or option to find out what the position of the object is relative to the frame of reference of the plane. Suppose that the plane is defined by the equation:

x + z = 0

Imagine taking the usual x,y, and z axes and pitching them by -45 degrees. The new z-axis would be perpendicular to the plane, and the new x and y axes would lie in the plane. Relative to this frame of reference, the plane is simply given by the equation z=0.

To find out where the given animation path lies relative to this new (fixed) frame of reference, you could execute the following command:

anim_cascade -or -fc 0 0 0 -fy 0 -45 0 < absolute.table > relative.table

Whenever the z coordinate of the output table is positive, the object lies above the plane; whenever the z-coordinate is negative, the object lies below the plane.

3. Suppose that one object is situated at the point (1,2,3) with a yaw, pitch, and roll of (45, 25, 10). Suppose further that you want to position a camera so that the object is 10 units in front of the camera, facing to the camera's right. In other words, you know the absolute position and orientation of the object. You know how you want the object to look from the viewpoint (frame of reference) of the camera. What you are trying to find is the frame of reference which satisfies these two constraints. The appropriate command is:

anim_cascade -s -of -ac 1 2 3 -ay 45 25 10 -rc 10 0 0 -ry -90 0 0

# AUTHOR

Carl J. Nuzman

# "BUG REPORTS"

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