# Animation Scripts

An animation table is a table of numbers in which every row corresponds to a moment in time, and each column corresponds to an animation parameter such as a position or angle. The curve editor, table editor, and view curve editor help the user create animation tables. Once this is done, the user must convert the animation table into a list of animation commands referred to as an animation script. These commands tell the application program which objects to move and exactly how to move them in each frame of the animation. The commands are in a standard format which is understood by the MGED display editor and the RT raytracer.

# Create Object Script

This section describes the object animation window which converts an animation table into an animation script controlling the position and orientation of an modeled object. See also the view animation window, which creates scripts to control the view, and the specialized track animation window, which assists in modeling and animating articulated tracks.

## Output File

The first entry box in the object animation window is labeled Output file. This box specifies the filename to be used when the animation script is created. If the file already exists, the user will be notified and given the option of overwriting the existing file or choosing a different filename.

## Source

The animation tables driving the output script may come from curves, view curves, table editors, or files. The type of source is selected using the option menu next to the Source label. An appropriate source name should then be entered into the associated entry box. The source name is simply the name of the curve, view curve, or file, or it is the integer identifier of the table editor.

Below the Source label, AnimMate provides a short description of the parameters that the columns of the source table should provide. This description changes depending which of the window's options are selected. For example, when the No Rotation checkbutton is active, AnimMate only needs to know the time of each frame and the position of the object. In this case, the source description reads:

4 input columns needed: t x y z

The following codes are used to describe the column contents:

    t               - time column
    x y z           - three columns: object's path through space
    y p r           - three columns: yaw, pitch, and roll
    qx qy qz qw     - four columns: quaternion coordinates
    lx ly lz        - three columns: path for object to look toward

If the number of columns in the source doesn't match the number of columns needed, an error message is displayed when the OK button is invoked. A curve always contains four columns, while the number of columns in a view curve, table editor, or file may vary.

## Object Name

The name of the modeled object being animated should be entered in this entry box, as it will appear in the output script. For a top level object, the name should be preceeded by a forward slash: /car.g. For an object being animated as part of another entity, the object name should be preceeded by the name of the parent object and a forward slash: suspension/wheel.0.

## Object Center and Orientation

Most objects being animated are rigid bodies taking up space in three dimensions. When the object's position and orientation are specified in an animation table, this raises a question: which part of the object should be placed at the given position? The user must supply the answer to this question in the entry box labeled Object Center. Although this point is refered to hereafter as the object center, it does not need to be the geometric center of the object. The object center is also the point about which all rotations occur. For example, when animating a vehicle such as an airplane, the most convenient object center is probably the airplane's center of mass. When animating a door, the most convenient object center would be a point along the hinge axis.

The object center can be keyboard-edited after clicking on the entry box with the mouse. As an alternative to keyboard entry, the user may center the MGED viewing display on the desired center point and then press the Object center button to automatically enter the correct values into the entry box.

In a similar vein, most objects being animated have a side which is considered their front, and similarly sides labeled left, right, top, bottom, and back. In this case, AnimMate needs to know how the object's orientation relates to the model axes. By default, a yaw, pitch, and roll of `0 0 0` is assumed; that is, AnimMate assumes that the front of the object faces the model x-axis, the left side faces the y-axis, and the top faces the z-axis. If this is not the case, the true yaw, pitch, and roll may be entered in the Object yaw,pitch,roll entry box. For example, if the object is a car which faces the y-axis, with the left side facing the negative x-axis and the top facing the z-axis, the user would enter a ypr of `90 0 0`.

The object yaw, pitch, and roll can be keyboard-edited after clicking on the entry box with the mouse. As an alternative to keyboard entry, the user may align the MGED viewing display in the same orientation as the object and then press the Object yaw,pitch,roll button to automatically enter the correct values into the entry box.

## First Frame

An animation script is made of a series of numbered frames. Each frame gives animation commands needed for one image in the final product. By default, the frames numbers for a given script begin at zero. If a different initial frame number is desired, it may be entered in the First Frame entry box. For example, the first frame number might be set to 300 when creating a script which will be appended onto the end of another script which is 300 frames long.

## Relative Displacement

If this checkbutton is selected, then positions in the source animation table are interpreted as relative displacements from the object's initial position, rather than absolute displacements from the model origin. For example, if an animation table contains the position `(0,0,0)`, then AnimMate normally creates a script which moves the center of the object (as specified in the Object center entry box) to the model origin. If relative displacement were enabled, then AnimMate would create a script which left the object in its initial position.

When relative displacement is enabled, it is still important to fill in the Object center entry box, because the center point also defines the point about which the object rotates.

## Relative Orientation

If this checkbutton is selected, then orientation parameters from the animation table are interpreted as being relative to the orientation specified in the Object yaw,pitch,roll entry box. For example, if an animation table contains a yaw,pitch,and roll of `(0,45,0)`, then AnimMate normally creates a script which pitches the object 45 degrees up from the x-axis. If relative orientation were enabled, however, then AnimMate would create a script which tilted the object 45 degrees up from whatever direction is considered its "front" (as specified in the Object yaw,pitch,roll entry box).

The relative orientation function also affects the way that AnimMate interprets positions. When relative orientation is enabled, positions and displacements are defined according to the object's own axes, as defined by the Object yaw,pitch,roll entry box. For example, the position `(1,0,0)` normally refers to a point on the positive x-axis, one millimeter from the origin. When relative orientation is enabled, the position `(1,0,0)` refers to a point one millimeter "in front of" the origin, that is, in the direction which the front of the object faces.

## No Translation

If this checkbutton is enabled, then AnimMate will only expect to read time and orientation information from the source animation table, and the animation script will only rotate the object. The No Translation button can only be enabled if either Rotation specified as ypr or Rotation specified as quat are enabled in the Orientation controls section. No Translation is commonly used with Relative Displacement for rotating an object about its center point.

## Orientation Control

The user may select one of the following six options when controlling the orientation of an object:

No Rotation
  The object will not change orientation during the animation. The source animation table only contains time and position columns, while the yaw, pitch, and roll are assumed to be zero in every frame. If relative orientation is active, then the object will always be in the same orientation it was modeled in. If relative orientation is inactive, then the object will be turned from its initial orientation (as specified with Object yaw,pitch,roll) to a zero yaw, pitch, and roll.

Automatic Steering
  Given an source animation table containing time and position columns, this option produces an animation script which always orients the object in the direction it is moving. The object is always oriented "right-side up", that is, with yaw and pitch but no roll. Relative orientation should not be used with this option.

Automatic steering and banking
  This option is similar to the previous option except that the animation script banks the object into turns, simulating the behavior of an aircraft. The severity of the bank depends directly on the sharpness of the turn, and is scaled so that the object reaches the maximum bank angle at the point in the animation table with the sharpest turn. The maximum bank angle, which defaults to 60 degrees, can be set to any value between -89 and 89 degrees by editing the corresponding entry box. Negative values cause the object to bank in the opposite direction, like a cart almost overturning as it rounds a corner. A maximum bank angle of zero causes no banking to occur. Relative orientation should not be used with this option.

Rotation specified as ypr
  The last three columns in the animation table give the object's yaw, pitch, and roll in each frame. If relative orientation is active, the yaw pitch, and roll are relative to the object's own axes; otherwise, they are with respect to the model axes.

Rotation specified as quat
  The last four columns of the animation table give the object's orientation as a quaternion, in the order x, y, z, w. The convention is the same as the quaternions returned by MGED's viewget quat command: the identity quaternion (0,0,0,1) puts an object in the default eye position, facing the negative z-direction with the x-axis to the right. This is equivalent to a yaw, pitch, and roll of (90,-90,0). The quaternion (0.5, -0.5, -0.5, 0.5) leaves an object in the default object position, corresponding to a yaw, pitch, and roll of (0,0,0). If relative orientation is active, the orientations are relative to the object's own axes; otherwise, they are with respect to the model axes.

Object path and look-at path
  This option requires that the animation table contain a path for the object to follow and a path for the object to look toward. The object will be oriented "right-side up" along the axis defined by the two points given in every frame. If relative orientation is active, the paths are interpreted in terms of the object's axes; otherwise, they are with respect to the model axes.

## Other Buttons

OK
  Create the animation script, leaving the object animation window in place for further work.

Show Script
  Display a window which can be used to run the animation script in the MGED display window.

Up
  Raise the object animation window's parent to the top of the stacking order.

Cancel
  Close the object animation window.

Next Section: Create View Script

Previous Section: View Curve Editor

Index