The Keyframe Animator module is used to animate objects which
are displayed through the Geometry Viewer subsystem. It works
by supplying a transformation matrix to the Geometry Viewer
module for any object which has been loaded into the Geometry
Viewer or supplied to the Geometry Viewer module's geom input
by other modules. Generally, the Keyframe Animator's geometry
output (the transformation matrix) is supplied to the geometry
input of Geometry Viewer.
Adding Objects:
The name of the object to be animated is typed into the ">>>"
input. The Keyframe Animator will only allow you to enter
object names that exist in the current view. To get a list of
objects in the current view, go into the Geometry Viewer (under
the Data Viewer's pulldown menu of the Network Editor), and
click on the small square in the current object selector (the
bar above the small object window). To see the list of objects
for a different view, click in that view's window. These
object names should be preceded by a percent symbol (%) in the
Keyframe Animator (if you type them without the percent symbol,
one will be added automatically). Cameras and lights cannot be
animated. Use the "%top" object to animate all of the objects
in the window.
Using the Mouse:
Instead of typing in the name of the object, you can use the
mouse to pick the object you want to animate. To add the
object, click the "add obj" button and use the left mouse
button to click on the object in the display window. You will
then be asked if you want to add the object, replace the
current object, or abort. Press "REPLACE OBJ" to animate the
new object. See below for more details on the other options.
Clicking in the background of the display window with the left
mouse button will allow you to animate the "%top" object.
Controlling the Object:
The object can then be rotated, translated, and sized
interactively using various input devices supported by AVS
(mouse, dialbox, and/or spaceball). With the mouse, use the
middle and right mouse buttons to transform the object. The
middle mouse button rotates the object and the right mouse
button translates the object. Holding either SHIFT key while
pressing the right mouse button will translate the object in
the Z direction. Holding the SHIFT key while pressing the
middle mouse button will size the object. The "initialize
transformations" button will reset the transformations to their
default values.
Keyframe Animation Interpolation:
Keyframe animation is done by saving an object in certain key
positions called "keyframes" and allowing the Keyframe Animator
to interpolate the in-between frames. This is done by moving
the object to the desired key position, orientation, and size,
moving the "animation frame" slider to the frame at which you
want that object at that position, and pressing the "save
keyframe" button. Then, choose another keyframe position in
the same manner, by moving the object to the chosen position,
moving the animation frame to the desired frame, and pressing
the "save keyframe" button. Any number of keyframes can be set
at various frames. Pressing the "create linear interpolation"
button will fill in the empty frames based on straight lines
between the keyframe positions, thus creating an animation.
Pressing "create spline interpolation" will instead fill in the
empty frames based on a smooth curve which goes through all
keyframes. The "ease in" and "ease out" buttons are used to
make an object gradually speed up and slow down near the
beginning or end of it's path. If "ease in" is lit when doing
a linear or spline interpolation, the object will gradually
speed up between the first and second keyframes of the
animation window. Similarly, if "ease out" is lit, the object
will slow down between the next to last and last keyframes of
the animation window. The "create hold" button will copy the
object's currently saved position (the position which has been
saved for the object at the current frame) to all the other
frames in the animation window. This is used for objects which
remain in one place during the animation. Note that "create
hold" copies the current position to all other frames,
including keyframes, so previously stored frame information
will be overwritten! Use this button with caution.
The "Update Frame" Button:
When a keyframe is set using the "save keyframe" button, or
when in-between frames are calculated using "create linear
interpolation", "create spline interpolation", or "create hold"
the object's position, orientation, and size are stored into
memory at each frame. When an object is moved with the mouse,
spaceball, or dialbox it is no longer in its stored position
until the new position is stored. When the "update frame"
button is lit, the object will always move to the previously
stored position at the current frame. To see the saved
position of an object at any frame, move the "animation frame"
slider to the desired frame and make sure that the "update
frame" button is lit. The "update frame" button automatically
lights up during certain operations such as "create linear
interpolation", "create spline interpolation", and "create
hold" and automatically unlights when an object is moved, so
that you will see the object move rather than stay at the
stored position.
Moving Around Your Animation:
The "-->" and "<--" buttons can be used to step through frames
of the animation by increasing or decreasing the current
animation frame number. The "prev key" and "next key" buttons
can be used to jump to the previous or next keyframe. The
"animation speed" slider can be used to make the arrow buttons
increase (or decrease) by more than one frame. Negative values
will cause the animation to run backwards (it will in effect
switch the meanings of the two arrow buttons). The "animate"
button will cause the animation to run as if you pressed the
arrow buttons repeatedly. The "once," "loop," "swing," and
"off" buttons affect the behavior of the animation when the
current frame goes beyond the "anim end" or "anim start"
values. The "loop" button causes the current frame to "wrap
around" when it goes beyond the "anim end" value so that the
current frame will be the "anim start" value. Similarly, the
frames will wrap around the other direction if you are stepping
through the animation backwards. The "once" button causes the
current frame to remain on the last frame as you step forward
past the end of the animation window, or to remain on the first
frame as you step backwards past the start of the animation
window. The "swing button" causes the "animation speed" slider
to reverse directions when you step past the end of the
window. The "off" button is exactly the same as the "once"
button except that it turns off the "animate" button when the
current frame gets to the end of the animation window (or the
beginning if it's running backwards).
The "Trace Object Path" Button:
After interpolating, turning on the "trace object path" button
will display the path that the current object will take through
the animation. The keyframes are also displayed along the path
as frame numbers. Turning the button off will remove the path
trace from the screen. Note that tracing the path of the
"%top" object has strange results.
Clearing Keyframes and Frame Information:
It may be desirable to unmark certain frames so that they are
no longer thought of as keyframes for interpolation. Use the
"clear keyframe" button to mark the current frame as not being
a keyframe, and use the "clear all keyframes" to clear all
keyframes. The "clear keys and frame information" button is
used to wipe out all of the saved transformations in the
animation (set them to their default values), including the
keyframes, and remove all keyframes. Use the "clear keys and
frame information" button with caution!
Loading and Saving Your Animation:
To save an animation, press the "save anim" button to bring up
a filename browser. Press "New File" to save the file under a
new name or to type in the name of the file to replace, or
select a filename to replace from the browser. Pressing
"cancel save" or turning off the "save anim" button will close
the file browser window. If the file already exists, you will
be asked if you wish to replace it. To load the animation back
in, press the "load anim" button to bring up a filename
browser. Press "New File" to type in the filename to load or
select a filename from the browser. You will be given several
choices at this point. You can replace whatever animation
might currently be in memory by pressing the "LOAD" button
(this is usually what you will want to do). The "MERGE" and
"APPEND" buttons are discussed in the ADVANCED TOPICS below.
The "update frame" button will automatically light after the
load so that you can immediately see the new animation.
Pressing "cancel load" or turning off the "load anim" button
will close the file browser window. Animation filenames always
end with ".anim" as an extension. If you save a file without
the extension, it will be added to the end of the filename.
Only files with the correct extension appear in the load and
save browsers. The current animation file is shown in the
title area at the top of the Keyframe Animator panel. Note
that previous versions of the Keyframe Animator may use
different file formats.
The Settings Menu:
Clicking on "edit settings" will open a window with settings
options. Here you can change the way the trace object path
appears by choosing numeric keyframe markers (the default),
spherical keyframe markers, or turning off the keyframe
markers. You can also change the size of the keyframe
markers. Click "close settings" to close the settings window.
Exiting the Keyframe Animator:
In order to exit the Keyframe Animator properly, it is best to
use the "exit" button. You will be asked if you really want to
exit, at which time pressing "OK" will turn off the trace
object (if it is on), close any popup windows that you may have
left open, return all objects to their default transform and
picking status, and exit the Keyframe Animator. Press "Cancel"
if you don't wish to exit.
ADVANCED TOPICS:
More About the "Update Frame" Button:
The "update frame" button, when lit, forces the object to move
to the saved position. This can be used to move an object
relative to a saved position by turning "update frame" on,
moving the object relative to its current position, changing
the "animation frame" number, and saving the new position as a
keyframe.
The "Animation Window":
More frames can be added to an animation by increasing the
"anim end" value. The "anim end" and "anim start" inputs also
change the frames which are selectable with the "animation
frame" slider. The frames within the "anim start" and "anim
end" values comprise the current "animation window." Certain
operations such as "clear keys and frame information", "create
linear interpolation", "create spline interpolation", "create
hold", and "trace object path" will affect only the frames
within the current animation window for the current object (see
Handling Multiple Objects below). The current "start frame"
and "end frame" are automatically defined as keyframes before
interpolation. When you press "save anim" to save your
animation, if the current "animation window" is smaller than
the number of frames that have been defined for the animation,
you will be asked if you want to save ONLY the animation
window, or if you want to save the entire animation.
"Active" Transformation Buttons:
Note that when an object is transformed, it's corresponding
"active button" ("ROTATE", "TRANS", "SCALE") is automatically
lit depending on whether you have rotated, translated, or
scaled the object. The reason for this is that when you create
an interpolation by pressing "create linear interpolation",
"create spline interpolation, or "create hold" (and also "clear
keys and frame information") only those transformations which
are lit will be interpolated, making it possible to control
exactly which transformations will be interpolated by manually
turning on and off the "active buttons." Furthermore, many of
the other operations which affect the transformations will
affect only those which are currently active. For example,
"initialize transformations" will only initialize those
transformations which are active, and the "save keyframe"
button will save only the transformation values which are
active.
Handling Multiple Objects:
More than one object may be animated at a time. Use "new obj"
to create an "EMPTY" object. You should then change its name
by typing in a new name in the text area marked ">>>". Note
that the Keyframe Animator will automatically ignore objects
which begin with "EMPTY" in all caps, so the Geometry Viewer
will not complain that it doesn't know of an object called
"EMPTY-2". Use "del obj" to change the current object to an
"EMPTY" object. Use "next obj" to make another object the
current object. When dealing with more than one object, the
transformations only affect the current object, and the
positions of all non-current objects are always updated whether
or not "update frame" is on. After making a new object the
current object (by either pressing "next obj" or clicking on
the object with the left mouse button), the "update frame"
button will automatically light to show you the saved position
of the new object. You may then animate that object as usual.
When you press "save anim" to save your animation, if any of
the objects begin with "EMPTY" you will be asked if you want to
save ONLY objects which are NOT "empty," or if you want to save
ALL the objects (including ones whose names begin with
"EMPTY"). This allows you to, in effect, delete objects by
simply naming them "EMPTY" so they won't be saved with the rest
of the objects if you don't want them to be. If all of the
objects currently defined begin with "EMPTY" they will always
be saved, and you will not be given the choice. Most
operations such as creating interpolations, "trace object
path", and "clear frame information" affect only the current
object. Keyframes are marked globally so if you press "save
keyframe" at frame 30 while animating one object, frame 30 will
be thought of as a keyframe when animating all objects (until
the keyframe is cleared).
Picking:
Instead of using the "new obj" and "next obj" buttons, you can
use the mouse to make a particular object current, add a new
object, or change the name of the current object. To make an
object current, simply use the left mouse button to choose the
object in the display window. Clicking in the background of a
window will make the "%top" object the current object. To
control an object that is not currently under the control of
the animator, or to replace the current object with an object
not currently under control, press the "add obj" button, then
click on the object with the left mouse button. If the object
doesn't currently exist as one of the objects you are
animating, you will be asked if you want to add it or replace
the current object. Press "ADD OBJ" to add the object to the
other objects you are animating. Press "REPLACE OBJ" to change
the name of the current object to the new object. Press
"ABORT" to do nothing.
About Parenting:
Parenting is a powerful way of creating complex moves. An
object will always move in relation to it's parent's
transformations, so if object "%dodec.1" has a parent
"%harmonic.2", moving object "%harmonic.2" will affect both
objects while moving object "%dodec.1" will affect only
"%dodec.1". In other words, a "parent" will affect it's
"children" which will in turn affect their "children" and so on
(thus a parent will affect all of it's "offspring"). To change
an object's parent, simply click the "parent" button, and type
the new parent into the ">>>" input. When you press the "trace
object path" button, the "ANIM-Trace" object is automatically
parented to the current object's parent, so that the trace will
reflect the current object's true path. Unpredictable results
can occur if you create a "parenting loop" (by assigning an
object's "offsprings" as a parent of that object). Parenting
an object to itself is not advised. Objects that have been
parented to other objects will remain parented to those objects
even if you change the "name" attribute to control a different
object. You should probably change an object's parent back to
"%top" before assigning a new value for the "name" attribute.
Note that the "%top" object is always at the top of the "family
tree," so animating the "%top" object always animates all
objects in the scene.
About Quaternion Rotation:
There are two widely used methods used to interpolate
rotational positions of objects: matrix rotation and
quaternion rotation. Regular rotation uses the traditional X,
Y, and Z transformation dials which are accumulated before
combining them in a transformation matrix. This has two
unfortunate side effects. One, using absolute rotation values
can create a problem sometimes known as "gimbal lock," the loss
of a degree of rotational freedom when trying to rotate an
object to certain positions. The other unfortunate side effect
is that matrix interpolation chooses an unpredictable rotation
path between two positions, since it linearly interpolates the
X rotations, the Y rotations, and the Z rotations separately,
then concatenates the three matrices to create the final
rotation transformation. Quaternion rotation solves both of
these problems. One, objects can be rotated intuitively (an X
rotation always rotates around the horizontal, a Y rotation
around the vertical, and a Z rotation perpendicular to the
screen). Also, quaternion interpolation chooses the shortest
path between two positions by considering rotations as points
on the surface of a sphere and interpolating based on a "great
circle" on the sphere. The only drawback to using quaternion
rotation is that the object must be rotated less than 180
degrees or the shortest path will then be in the opposite
direction. The work around to this is to save intermediate
keyframes so that the rotations between keyframes are always
less than 180 degrees. Spline quaternion rotation will
correctly fit a spline curve through the keyframe rotation
positions on the surface of the rotational sphere.
More on the "Load Anim" Operation:
During a "load animation" operation, three options are
presented aside from replacing the animation currently in
memory. The "MERGE" button will allow you to merge the file
with the animation currently in memory, thus adding to the
objects in memory rather than overwriting them. "APPEND" will
add the frames stored in the file to the end of the frames
currently in memory, but will ignore the object names in the
saved file, appending the frames for the first object in the
file to the frames of the first object in memory, and so on.
Use "ABORT" to abort the loading process and return to the
Keyframe Animator. If the file you are loading was created
with an older version of the Keyframe Animator, a warning will
be given when the file is loaded. You can then abort the load,
or attempt to load the file anyway. There is no guarantee that
files created by different versions of the Keyframe Animator
will be the same format. You can examine the file and compare
it against the format described below in the ANIMATION FILE
FORMAT section at the end of this documentation.
Attaching a Driver Coroutine to the Keyframe Animator:
The invisible "animation pulse" input allows an integer to be
supplied by a "driver" coroutine module (such as "animated
integer"), causing the current animation frame to be increased
or decrease by the "animation speed" value every time the pulse
is received. See INPUTS and EXAMPLES below. The "wait for
sync" button and "sync frme" text input are only useful if the
Keyframe Animator's "animation pulse" input is connected to a
driver module or to a downstream record module. The "wait for
sync" will cause the Keyframe Animator to wait for a specific
integer at its "animation pulse" input before it will begin
incrementing the "animation frame". The integer which the
Keyframe Animator will wait for is specified with the "sync
frme" text input. When this integer is received, the "wait for
sync" button will automatically unlight, the current animation
frame will be incremented, and subsequent integers (reguardless
of their values) will be taken as pulses and will cause the
current animation frame to be incremented. The "loop," "once,"
and "swing" buttons have the same affect when driving the
module with a coroutine driver as they have when manually
pressing the arrow keys and when viewing the animation with the
"animate" button (see above). When a pulse is received through
the "animation pulse" input, the "update frame" button will be
turned on automatically so that the animation will be shown.
Driving an Output Module:
The invisible "animation pulse" output can be used to drive a
downstream module with the Keyframe Animator. This is
especially useful for saving images to disk or to a video
device. The output will only be changed when the current scene
is changed by the Keyframe Animator. The value of the output
is an integer corresponding to the current animation frame.