AnimaBob:
User Guide and Brief Tutorial

Table of Contents

Introduction

The following is a brief tutorial on using AnimaBob. to generate a movie from a set of dynamic volume data.

Installing AnimaBob

To install AnimaBob on your machine, uncompress and untar the archive. Read the "ReadMe" files within the directory structure and follow the procedure appropriate for your hardware system.

Getting Started: The Command Line

AnimaBob may then be launched from the command-line. A variety of options may be set by setting command-line switches, the order of which is important for several of them. Table 1 summarizes the options which may be set on the command line.

Usage: animabob [ options ] < data option(s) > datafile(s)
Option switch Description Default
General program options:
-cmap | -c fileInitial color map file.None
-amap | -a fileInitial alpha map file.None
-scale | -x XxYxZSpace the data set using a ratio of X:Y:Z.1x1x1
-default | -d fileDefault settings file.Bobfile
-singleForce AnimaBob to use single buffering.Not set
-savebgrSave images in BGR byte order.False
-savergbSave images in RGB byte order.True
-fastrate #Frames per second interactive.6
-fov #Field of view, in tenths of a degree.34
-eye #Eye separation for stereo viewing.0.07
-distance #Distance of the volume from the view point.3.0
-inter #Number of points in movie path. This is only valid for static data sets.100
-poffset #Offset of point data per record.
-pstride #Size of point data record.
-psize #Size of points.
-pnum #Number of points in file.
-pcolor nameColor of points.
-voxbg nameColor of voxel background.Black
-fog densityRendering fog.
-help | -hShow the information from this table.
Data file options:
-size | -s XxYxZData brick dimensions. This must be specified.
-number | -n #Number of bricks in data file.1
-offset | -o #Beginning of brick in file.0
-block | -b # Block size of device
-p Point files to follow.Not set
-v Voxel files to follow.Set

Table 1. Command-line usage and options for AnimaBob.

If you are using the demonstration data set, the command will look like:

user@machine% animabob -c color.map -number 151 -s 25x15x15 25x15x15n151.bob

The first command-line switch specifies the color map to use, the second the number of data frames in the file, the third specifies the size of the volumes, and the last is the volume data file.

Interface and Movie Generation

When the program has finished loading, the user is presented with the dimension window (Figure 1) and the main window (Fig. 2).

Figure 1. Volume dimension window in AnimaBob.

A sub-volume of the whole volume may be viewed by adjusting the sliders in the right region of the dimension window accordingly. However, most of the program interaction will be performed in the main program window.

Figure 2. Main program window in AnimaBob.

The main window consists of seven primary elements (clockwise from left to right): the volume view/manipulation window, menu bar, animation and interpolation controls, current frame slider, alpha attenuation slider, data file list, and volume view list.

(a)(b)

Figure 3. (a) Imaginary sphere surrounding volume in the view window.
(b) Mouse controls used for manipulating the volume.

To begin recording a movie, the user must first pick the desired point of view of the volume. This may be done through manipulation of the volume with the mouse. The volume may be manipulated in view window in either the main or dimension windows. An imaginary sphere surrounds the volume in the view window (Fig. 3a). Whenever the mouse pointer is on this imaginary sphere and moved, and one of the three mouse buttons is pressed (Fig. 3b), the volume is either rotated, panned, or zoomed.

Once the desired view is obtained, pressing the Record button (Table 2) will record the view. Each recorded view will appear in the volume view list. Next, advance the frame slider to a new data frame, and chose a new view if desired. Again, pressing the Record button will save the frame. At this point, the user may stop recording keyframes or may repeat the previous steps until the desired number of keyframes is obtained.

Button(s)Name and Function
Skip Reverse / Skip Forward. These buttons set the movie to the first and last frames, respectively. The buttons are active both during playback and while the movie is stopped.
Scan Reverse / Scan Forward. These buttons are multi-functional. A single click will decrement or increment the movie sequence by one frame. Holding the buttons will shuttle the movie backward or forward. The buttons are active both during playback and while the movie is stopped.
Play. The button initiates the movie playback after an animation path has been interpolated.
Stop. This button, depending on program state, either interpolates an animation path after all points have been recorded or stops movie playback.
Record. This button records the current frame as a keyframe to used for interpolation.
Start/Stop Animation. This button, labeled "Start" or "Stop" depending on program state, starts or stops interactive animation.
Save Coordinates. This button saves the interpolated animation path coordinates to a file.
Save Movie. This button initiates the movie playback after an animation path has been interpolated, saving each frame to a raw image file.
About AnimaBob. This displays the "All About AnimaBob" dialog box.

Table 2. Animation and interpolation controls and their associated functions in the AnimaBob user interface.

Once the desired number of keyframes is recorded, the Stop button must be pressed to interpolate and generate the animation path. The user may now press Play to begin the movie playback. If the user wants to save the movie frames as raw image files, the Save Movie button should be pressed instead. In either case, movie playback may be stopped at any time by pressing the Stop button. The name of the data files saved can be changed through the animation dialog box (Fig. 4).

Figure 4. Animation dialog box in AnimaBob.

If the user would like to save the coordinates for the animation path, the Save Coordinates button must be pressed. Please see the following section, Working with Coordinates for more information.

Summary of Movie Path Generation

  1. Set desired volume view by manipulating volume with the mouse.

  2. Record keyframe by clicking the Record button.

  3. Advance frame slider to a new data frame.

  4. Repeat steps 1 through 3 at least one more time, such that no less than two keyframes are recorded.

  5. Press the Stop button to interpolate and generate an animation path.

  6. Press the Play or Save Movie buttons to playback the movie, saving image files in the latter case. The Save Coordinates button can be pressed to save the animation path coordinates to a file. The shuttle controls may also be used at anytime after interpolation.

  7. Press the Stop button to stop movie playback at any time.

Working with Coordinates

While AnimaBob provides the facilities necessary to interactively generate animations paths and movies, it may often be desireable to render the movie images off-line when machine loads are lower or when a higher-quality renderer is to be used.

AnimaBob provides the ability to do this through its coordinates dialog box (Fig. 5) and the Save Coordinates button (Table 2). Currently, through the coordinates dialog box, a name for the coordinates file can be chosen. This file will be save in the current working directory, from which AnimaBob was launched. The name defaults to "coordinates.txt" for ASCII files and to "coordinates" for binary files. Currently only ASCII output is supported.

In addition, future provisions will be made for the disabled fields shown in Fig. 5. These include: binary output files, image size field, data frame number with a data file field, data frame file name field, global alpha field, overall volume dimensions field, and a sub-volume dimensions field (useful for tracking sub-volumes through a data progression).

Figure 5. Coordinates dialog box in AnimaBob used for configuring options for the animation path output file.

Coordinates File

Currently, AnimaBob supports only ASCII output for coordinates files. The file consists of a header line followed by a line for each movie frame with the coordinates for that frame. A sample of such a file is shown below.

KF Quat[0] ... Quat[3] Trans[0] ... Trans[2] Eye[0] .... Eye[2] CDir[0] ... CDir[2] Up[0] ... Up[2] FrameNum
1 0.000000 ... 1.000000 0.000000 ... 0.000000 0.000000 ... 3.000000  0.000000 ... -1.000000 0.000000 ... 0.000000 0
0 0.003343 ... 0.999950 0.000000 ... 0.000000 0.045322 ... 2.999589 -0.015107 ... -0.999863 0.011183 ... 0.006602 1
0 0.006686 ... 0.999801 0.000000 ... 0.000000 0.090402 ... 2.998356 -0.030134 ... -0.999452 0.022464 ... 0.013033 2
0 0.010029 ... 0.999552 0.000000 ... 0.000000 0.135223 ... 2.996301 -0.045074 ... -0.998767 0.033836 ... 0.019290 3
0 0.013370 ... 0.999204 0.000000 ... 0.000000 0.179767 ... 2.993425 -0.059922 ... -0.997808 0.045296 ... 0.025371 4
...
1 -0.351003 ... 0.400930 0.000000 ... 0.531250 1.243897 ... -1.443386 -0.503857 ... 0.584663 -0.747940 ... 0.072933 150

The first field, labeled "KF" in the header, indicates whether (1) or not (0) this frame was a key frame recorded by the user. The following seven fields, labeled "Quat[0]" through "Quat[3]" and "Trans[0]" through "Trans[2]" are the quaternion and translations vector components which AnimaBob uses internally to represent the view of each frame.

The following nine fields are another representation of each frame in the movie sequence. They are labeled "Eye[0]" through "Up[2]". A graphical depiction of their relation to the viewer and the rendered object is shown in Fig. 6.

Figure 6. Orthogonal coordinates output by AnimaBob in addition to the quaternion and translation vector.

The final field, labeled "FrameNum", is the frame number in the movie sequence for that particular entry. The first frame number will always be zero (0).

Last modified: Sat Oct 30 19:17:24 PDT 1999
grant@borg.umn.edu