Christopher Steinbach

March 2002

User/programmer Documentation for the Key Frame Animator

--------------------------------------------------------------------------------

1.	Introduction
2.	Getting started
3.	How To Record a key frame file
4.	How To play a key frame file (without creating a video)
5.	How to record a video
6.	How to play back a video
7.	What information the displays convey
8.	What the inputs do
9.	How to make a rendering method work with the key frame animator.
10.	Conclusion.

--------------------------------------------------------------------------------

1.	Introduction.

	This file provides the documentation needed to start using the key
frame animator included with vuVolume as well as the documentation required
to make a method work with a key frame animator.

	The screen shots included in this file were captured from Windows,
however, everything described in this document is the done in the same
way with the same buttons in the other operating systems that this runs
under.

	This key frame animator was designed to be as minimally intrusive as
possible to the vuVolume framework.  This was designed so that by overriding
four methods from vuBasicUtility in the user interface of your volume rendering
method, the key framer will be able to record, playback, render videos and store
them in addition to any other task that would be expected of a key frame
animator.

	Provided by the animator are tools to record key frames at specific
times much like a cartoon animator will draw key frames of motion every so
often.  The user will then be able to instruct the animator to interpolate
across the key frames to create an animation.  The process will interpolate
across the cameras at regular time intervals, instruct the method to render
the image, and get the buffer from the vuImage and continue.  This will make it
easy to generate an animation.

	Also provided are tools to play back only the key frames, so that you
can record a benchmark with one type of camera, render each frame, and determine
how long it took to render the total set of images.  From there, you can load
another method using the same type of camera, and then render each key frame
with the new method so that you can compare the length of time that it took when
compared to the first.

	In the future, we hope to provide more tools to make it easier to edit
key frame files (such as a method to easily select a key frame and move it's
placement in time), as well as more efficient methods of storage which will
allow for better space usage and a better playback frame rate (since hard drive
accesses are terribly slow).

	This animator requires that your method uses a vuCamera class as the
camera (or a camera derived from vuCamera).  This animator also requires that
your method uses the vuImage as an Image buffer so that screen shots can be
taken and restored.  Should these not be possible, your method will still work
in vuVolume but will not work with the animator.

	Section 2 describes how to start with the animator and where all of
the files are for the animator.

	Section 3 describes how to record a key frame file with the animator
onces you've gotten started.

	Section 4 describes how to play back this key frame animation that you've
recorded (without creating a video).

	Section 5 describes how to create a video to be played back out of your
key frame file.

	Section 6 describes how to play back this newly created video.

	Section 7 lists each text area and what is displayed by that text area
so that you will have a complete description of what information the key
frame animator is providing to you.

	Section 8 lists each of the non-button user inputs and what effects
they will have on how the key frame animator runs.

	Section 9 describes how to make your rendering method compliant with
the key frame animator, so that it will work properely.

	Section 10 wraps things up, provides a todo list, and provides other
references.

---------------------------------

2.	Getting started

	<Insert image of Key frame animator here>

	To get started, you should double right click on the Gui of the
rendering method that you want to animate from/to.  This will pop up a dialog
box (the dialog box shown in the above image).  Now, you have an animator
that you can use to create key frames and generate video animations from.

	What you see may be a little confusing, so here is a brief description
of what you are looking at.

	This key frame animator is broken up into two distinct parts, key frame
handling section (the left half of the dialog box), and the video handling section
(the right half of the dialog box).

	This separation reflects that playing a prerecorded video from images is
different from generating images from key frame files, or interpolations of key
frames.  This separation also reflects that it is not obvious which animation
is associated with a key frame file - there could be no such animation or many
such animations generated by a variety of methods and at a variety of frame rates,
and possibly even with a variety of storage types.

	The two distinct parts were maintained in the same dialog box since they
are at least somewhat related - the animations are generated from key frame
files.  Since there does exist this relationship, and since I do not want to
consume any more events to start two dialogs when one will do (so that others
can use those events later for their own tasks).

	Functionality associated with key frame files will be accessed through
the controls on the left half of the dialog, while functionality associated with
video files will be accessed through buttons on the right half of the screen.

	On each half, the buttons roughly correspond to the meaning of a similar
button on a VCR.  This was done to make this as simple to use as possible.

	<Insert Annotated image of key frame animator here>

	This above image is provided as a map, so if you are refered to a
specific control below, this control will be identified by the number on the
map.  This will help you be certain that you are doing the correct thing and
will prevent ambiguities later.

---------------------------------

3.	How To Record a key frame file

	In order to record to a key frame file, you will have to execute the
following steps in order:

3.1	Starting to record - select the file
3.2.	Take Snap Shots of the current camera
3.3.	Save the recording or close it

	The idea is simple, you should start recording, then every so often
record the camera position so that you will have key frames, then you save
the file once you are done so that you can play it back later.

-------------

3.1	Starting to record - select the file

	To get started, you first need a key frame file.  Without this, you
have nothing to animate and will not be able to generate videos or play test
files or anything like that.

	To start recording to a new key frame file, you should click on button
"R.".  This will pop up a file menu.  If you wish to overwrite an existing file
with a new animation, then select that file.  Otherwise, type in a new file name,
and select okay.

	If you select cancel from this dialog, the record operation will stop
there.  If you select a file, or select okay, you will open that file for
recording.

	Be warned that recording to a file will overwrite the contents of that
file without saving them.

-------------

3.2.	Take Snap Shots of the current camera

	Manuever the camera (through the rendering utility's user interface)
until you have it pointing at the desired place.

	Once you have the desired scene, you should then hit button "V.".
When you press this button, the information of the camera as well as the time
will be recorded to the file that you are recording to.  The time will be the
time that has elapsed since you started recording.

	This button will have no effect if you are not recording.

-------------

3.3.	Save the recording or close it

	If you wish to save the recording, then you should hit the button
"W." (the save button).  This will save the recording to the file and will
stop recording.

	If you wish to stop recording without saving it, then hit the button
"U." (the close button).

	In both cases, you will be warned that by proceeding, you will
not be able to continue recording to the current file by a message box. You
will also be given the opportunity to cancel the recording.

---------------------------------

4.	How To play a key frame file

	In order to play back a key frame file, you must do one of the
following:

4.1.	Play the key frames in real time.
4.2.	FastForward the key frames in real time.
4.3.	Rewind the key frames in real time.
4.4.	Play every key frame as fast as possible, in order.

	You will also have the option of controlling the play with the
following controls:

4.5.	Stop the animation you are playing
4.6.	Pause the animation that you are playing
4.7.	Fast Forward the animation that you are playing
4.8.	Rewind the animation that you are playing

	This interface was designed so that it would be similar to a VCR's
interface so that it would be simple to understand what you are doing.  So
each button has pretty much followed the priniciple of the corresponding
VCR button.

-------------

4.1.	Play the key frames in real time.

	In order to play an animation in real time from the key frames,
simply hit the play button (button "B.".).

	If you have already loaded a key frame file (through button "P.")
then it will play that file.  Otherwise, a dialog box will pop up asking
you which file should be played from, and that file will be loaded.

	This method will play the animation in real time using the
renderer to generate each image, and if the current image that it is
generating is between frames, it will interpolate between the two frames
in order to create a camera that the renderer should render the image
from.

-------------

4.2.	FastForward the key frames in real time.

	When you hit the fast forward button (button "E."), this will
start playing at double speed.  Other than the speed, this is
exactly the same as how 4.1. is described.

-------------

4.3.	Rewind the key frames in real time.

	When you hit the rewind button (button "A."), the animator will
start playing in reverse at double speed (since you are starting at time
zero, it will merely play time zero over and over again).

	Other than the direction of play, this is the same as is described
in section 4.2..

-------------

4.4.	Play every key frame as fast as possible, in order.

	If before hitting play, you select the "Max Speed/Key Frames only"
checkbox (labelled "L."), when you play, this will play every key frame in order,
not in real time, and as fast as it can (once it is finished a frame, it will
immediately polay the next frame).

	You play by hitting the "play" button (button "B.").

	So, the process is:  check checkbox "L." and hit button "B.".

	Please note that once this is started, you will not be able to interrupt
this process until it has completed.  Fast forward and rewind would have no sensible
meaning in this context, so they are not needed, and rest of the controls that you
may wish to use would require time to process, and the screen may have to be updated
to redraw the buttons, which would require more time.  The time taken by allowing
these things to happen would add to the length of time it takes to play these images.

	This is intended as a way to compare between two different methods, the time
needs to be exact and only include things essential to rendering an image.

	Therefore, the screen will not update until after the the process is
complete and the total length of time can be reported.

-------------

4.5.	Stop the animation you are playing

	If you wish to stop the animation, simply press the "stop" button
(button "D.").  This will stop the animator when it has finished the current frame
that it is drawing.

-------------

4.6.	Pause the animation that you are playing

	If you wish to pause the animation, simply press the "pause" button
(button "C.").  If you wish to unpause it, press "rewind", "play", "pause",
"stop" or "fast forward" (buttons A. B. C. D. E. respectively).

	If you hit the "pause" button while it is already paused, it will
continue playing as it was before, otherwise it will pause.

	If you hit the other buttons ("rewind", "play" or "fast forward")
while it is paused, it will resume playing in the appropriate direction and
at the appropriate speed as the button that you press (ie, play is normal
direction, normal speed, etc...).

-------------

4.7.	Fast Forward the animation that you are playing

	If you wish to speed through the animation at double speed, simply
press the "fast forward" button, button "E.".  To stop this hit the "fast forward"
button once more and it will return to normal speed.

	The other buttons "A.", "B.", "C.", and "D." will still have their normal
effects while the animation is fast fastwording, and will stop the animation from
fast forwarding.

-------------

4.8.	Rewind the animation that you are playing

	If you wish to speed through the animation at double speed and in reverse,
simply press the "fast forward" button, button "E.".  To stop this hit the "rewind"
button once more and it will return to normal speed.

	The other buttons "B.", "C.", "D.", and "E." will still have their normal
effects while the animation is rewinding, and will stop the animation from rewinding.

---------------------------------

5.	How to record a video

	In order to record a video from a key frame file, you have to perform
3 simple steps:

	1. - select checkbox "K." (the "Save Animation" check box).
	2. - set the frame rate in text box "T." (the "frame rate" text box).
	3. - hit the "play" button (button "B.").

	The rest will be explained to you in various dialogue boxes that will
pop up.

	This will create a video file with frames every (frame rate) seconds,
and store it to the location specified you specified in one of the dialogues
that will pop up during the process.

---------------------------------

6.	How to play back a video

	To play back a video, you must do one of the following:

6.1.	Play the video in real time.
6.2.	FastForward the video in real time.
6.3.	Rewind the video in real time.
6.4.	Play every video as fast as possible, in order.

	You will also have the option of controlling the play with the
following controls:

6.5.	Stop the animation you are playing
6.6.	Pause the animation that you are playing
6.7.	Fast Forward the animation that you are playing
6.8.	Rewind the animation that you are playing

-------------
6.1.	Play the video in real time.

	To do this, simply

-------------
6.2.	FastForward the video in real time.

-------------
6.3.	Rewind the video in real time.

-------------
6.4.	Play every video as fast as possible, in order.

-------------
6.5.	Stop the animation you are playing

-------------
6.6.	Pause the animation that you are playing

-------------
6.7.	Fast Forward the animation that you are playing

-------------
6.8.	Rewind the animation that you are playing


---------------------------------

7.	What information the displays convey

---------------------------------

8.	What the inputs do

---------------------------------

9.	How to make a rendering method work with the key frame animator.

---------------------------------

10.	Conclusion.
