Animay Documentation

Section four specifies all the command line options, and the use of Animay to create an animation, and how to generate animations using other peoples Animay files.

The use of the Motif previewer and editor is covered in a separate document entitled "Animay Motif Editor".

Animay does not actually render any of the frames which go to make up an animation. All the hard work is done by a program called POV-Ray (Persistence Of Vision Raytracer), a copyrighted freeware program that can create some stunning 3D images through the process of raytracing. Because POVray does not actually need any graphics or other machine dependent features to generate a scene, it may be compiled on almost any platform. Pre-compiled versions are available for the PC, the Macintosh, and the Amiga, and it can be compiled under Unix, and VAX.

A scene is created by describing the elements which make up the scene in a text file. Elements can be objects such as spheres, planes, cubes, pyramids, cylinders, etc, all of which can have different textures. The scene can also have different sources of light (at least one light source helps). POVray then takes the scene you have described and creates an image file of the scene. To do this, the scene also contains details about a "camera". The camera usually has a location, and a point it is focussed on, but may also have other features, such as a different field of view angle, a different "up vector", and so on.

You will need to install POVray on your system to generate animations with Animay. POVray may be downloaded from the Internet by anonymous FTP from the following sites :

alfred.ccs.carleton.ca:/pub/pov-ray

ftp.povray.org:/pub/povray

uniwa.uwa.edu.au:/pub/povray

1.2 About Animay

Animay is a front-end to POVray for creating animations. It adds movement to any scene created with POVray. It does this by replacing certain parameters within a POVray file with variables, which are then altered to give a number of different images, each slightly different from the previous. These images may then be compiled into an animation format such as mpeg.

Animay uses a slightly different format of data file to POVray, which are usually given the extension ".anp". These files are the same as POVray's ".pov" files, but also contain an "animation" block which details information on how to animate the scene. The values within the POVray file which are to change in the animation are also replaced by variables (represented by $ within the normal POVray data). When Animay generates a frame of animation, it writes a temporary POVray file, replacing all the variables with a different value for that time, and passes the file to POVray, which does all the hard work in generating the frame.

Animay has two modes of operation. The first is in command line mode, where any options are specified when Animay is run, and Animay goes ahead and generates the frames. The second mode consists of a previewer and editor, which uses X-windows graphics and the Motif widget set. As a result, the preview/edit mode can only be used on a Unix workstation with both X-windows and the Motif widget set. The command line mode requires no graphics or other machine dependent features, though, and so should work on most platforms that POVray works on. The command line mode generates the same animation as the preview mode, but all editing must be done manually.

1.3 Other Utilities

Although POVray is the only other essential tool for creating animations, there are a number of other utilities which may be helpful.

1.3.1 Viewers

It's helpful to have a picture viewer, to preview what individual frames are like. If configured correctly, Animay (in preview mode) can generate, then display a frame at a specified time. It does this by first running POVray with the correct data, then running the viewer you specify. Even when using Animay on other systems, it is helpful to look at different frames to get some idea of the final animation.

One of the most widely used viewers for X-windows is "xv". Unfortunately, POVray generates targa files when used with Animay, and "xv" and some other viewers will not display targa files. To get around this, there is a small converter called "tga2gif" available at most POVray sites, which converts Targa files to the more common GIF format. Another set of utilities called "ImageMagick" contains a utility called "display" which can display Targa format images. It also contains a utility called "convert" which, suprisingly enough, can convert Targa images to a large number of different formats.

1.3.2 Animators

Also of great importance is some software to compile each frame image, and display them one after the other to generate the final animation. There are two types of utilities to help with this. The first reads in all frames, which are stored in individual files, and then displays them one after another. An example of this is the "animate" utility, which is also a part of the "ImageMagick" set of programs. The second type of utility consists of an encoder, which assembles all the frames into one animation file, and a decoder, which plays back the animation. An example animation format is the "mpeg" format. Using "mpeg_encode", all the frames can be compressed and compiled into one ".mpg" file. Using "mpeg_play" this file can then be played back. Other animation formats include ".fli", ".gl", and ".anm".

2.0 Installing Animay

There are a few files you will need to edit before compiling Animay. These contain specific things about where things are installed on your system, and what system you are using. These are specified in the files animay.h, and Makefile.

2.1 animay.h

This file contains a number of defines which tell Animay what utilities to use, where they are, plus a few default options. Just change whatever defines you need to what you need. The format of a define is :

#define ""

So, for example :: #define WHEREAMI "Antarctica"
tells Animay that wherever it needs to refer to the users location, it should use Antarctica. (No, Animay doesn't need to know this. It was just an example of define.)

MOSAIC_CMD: This should be set to the command for loading a WWW browser for viewing the Animay documentation. The original documentation is at "http://www.cage.curtin.edu.au/~phillips/animay/", so if your WWW reader was mosaic, you would define MOSAIC_CMD to be "mosaic http://www.cage.curtin.edu.au/~phillips/animay/". There are a few examples within animay.h. Comments begin with "/*" and end with "*/", and only the uncommented one will be used. If you don't have a WWW reader, uncomment the "#undef" line, and comment out the others.
POV_CMD: This should be set to the command for executing the POVray executable. If you don't have povray installed, then download it and install it, as you can't generate animations without it. Animay will add arguments after this line specifying filenames and such. Any other POVray options you may want can also be entered as command line parameters to Animay, and these will be passed to POVray.
DISPLAY_CMD: You can preview frames within Animay by running an external viewer on the new file. DISPLAY_CMD should be set to the command to run the viewer. The filename will be appended to the end of this command line.
DISPLAY_CMD_POST: When it isn't possible to run a viewer by adding the file on the end of the command line, set DISPLAY_CMD_POST to what should follow after the filename. When the viewer is executed, the command line will be DISPLAY_CMD DISPLAY_CMD_POST. In this way, the file may be copied to a temp file, passed through a converter, and then displayed with a viewer which cannot display Targa image files. An example of this method is included in animay.h.
DEF_OUT_FILE: This should be set to the default filename for frame image files. Added to this will be the frame number (3 digits) and the extension ".tga". For example, if you want all the frames to be saved with filename "frameXXX.tga" in the "frames" directory, you would define DEF_OUT_FILE as "frames/frame".
ENV_VAR_NAME: Animay's command line options may also be set by setting an environment variable, similar to setting the POVRAYOPT environment variable for POVray. Define ENV_VAR_NAME to what you want the name of the environment to be. By default it is ANIMAYOPT, and you need not change this, but some may wish it to be changed.

You should not need to alter anything else in animay.h.

2.2 Makefile

This file controls how Animay is built and linked, and will therefore control whether or not the Motif version is compiled. There are two Makefiles supplied, called "Makefile.std" and "Makefile.Motif". If you want just the standard version of Animay, copy "Makefile.std" to "Makefile". If you want the Motif preview/edit version, copy "Makefile.Motif" to "Makefile".

The standard version should compile on most platforms without any problems. If you have any troubles, send me some E-mail describing the problem and I'll try and fix it.

The Motif version has only been tested on HP300/400's and HP700's under HPUX's VUE, and Silicon Graphic's Iris and Indy systems, but should work fine with most unix systems with the Motif libraries. Once again, if you have any troubles, send me some E-mail describing the problem, and I'll try and fix it.

3.0 Creating an Animation

This section will show how to create animation files (files of this type usually with the extension ".anp"). It hilights the differences between an Animay file and a POVray file, and shows how to animate a POVray scene by modifying an existing POVray file.

A tutorial will then be given, showing the steps to creating an animation from scratch.

3.1 The Animay File

The animation files Animay uses (which usually have the extension ".anp") are the same as POVray's files, except with extra information concerning how to animate the scene.

The animation requires two changes to a scene file :

The first change involves embedding variable names within the standard scene data. For each value you want to animate, replace this with a variable name, preceeded by a "$" symbol. For example, if you had an object which you wanted to animate up and down the Y axis, then the translation vector may look something like <10.0, $myobjy, 3.5>.

The second changes involves adding a new structure to the file. This structure has the format :

	animation
	{   frames [number of frames]
	    duration [total duration of animation]
	    period [time between each frame]
	    keyframes
	    {   [variable name 1]
		{   [time 1], [value at time 1],
		    [time 2], [value at time 2],
			:
			:
	        }
		[variable name 2]
		{   [time 1], [value at time 1],
			:
			:
		}
		:
		:
	    }
	}

Where each quote in []'s is replaced by a value, be it numerical, or a variable name.

Only two of frames, duration and period is required, as the third can be calculated by the first two. If all three are specified, the period given is ignored and recalculated to fit the duration and frames values.

Each variable name corresponds to a variable name embedded in the scene part of the file. For example, for our object with translation vector <10.0, $myobj, 3.5>, our animation block may look something like this :

	animation
	{   frames 200
	    duration 5
	    keyframes
	    {   myobj
		{   0.0, 0.0,
		    1.0, 5.0,
		    3.7, -3.2,
		    5.0, 7
		}
	    }
	}

Note that in the animation block the variable name is not preceeded by a "$". The keyframe values are times and values which you want to occur. In other words, you want the value of the variable to be "X" at time "T". Animations must consist of at least two keyframes, and it is typical to place a keyframe at time 0 (the start of the animation) and at the end of the animation.

When Animay goes to generate the animation, it calculates a value at each frame time, based on the specified keyframes. It does this by calculating a natural interpolation between the points. The resultant pathway is usually a smooth curve, known as a spline curve.

The spline curve of each variable may be previewed by running Animay with the -p command line option. For the Motif version of Animay this will enter edit mode, and display the splines in a window. For the standard version, a simple text bar graph will be printed, giving a rough idea on what the spline looks like.

3.2 Tutorial

3.2.1 Creating the Scene

Let's take a simple example POVray scene, and animate it. First, a checkered plane, with a wood sphere above it (If you are new to creating scenes with POVray, refer to the POVray documentation). We want to animate the sphere along the Y axis, so let's replace the sphere's Y co-ordinate with the variable "spherey" :


	plane
	{   <0, 1, 0>, 0
	    pigment
	    {  checker
	       color Red
	       color Blue
	    }
	}

	sphere
	{  <0, $spherey, 0>, 0.2
	   texture
	   {  pigment
	      {  DMFWood4
		 scale 4
	      }
	      finish {Shiny}
	   }
	}

Since our sphere will be moving upwards, let's add another plane overhead to give it some background when we're viewing it from below. Also, two light sources, opposite sides of the sphere, and one near each plane :


	plane
	{  <0, -1, 0>, -3
	   pigment
	   {  checker
	      color Brown
	      color Green
	   }
	}

	light_source { <-5, 0.5, -2> color White}

	light_source { <5, 2.5, 2> color White}

Lastly, we add our camera, which will always focus on the sphere, and which will move along all three axis, so lets use variable names "camx", "camy" and "camz". :


	camera
	{  location <$camx,$camy,$camz>
	   look_at <0,$spherey,0>
	}

3.2.2 The Animation Data

Now that the scene is complete, we add the animation structure. Let's generate 200 frames, and set the duration to 2. The duration has no set units; it is just a representation of how long the animation is relative to the time of each keyframe.

The camera will circle around the sphere twice. To do this, we add a keyframe each 1/4 of a circle for the "camx" and "camz" variables. The resultant spline are close to sine waves, with one offset from the other by 90 degrees.

The height of the camera will alter to give a varying perspective of the sphere and planes. It will initially be high, will dip down slowly, then rise rapidly to finish at the same height.

Lastly, the sphere will start near the bottom plane, rise to the top plane, and return to the bottom plane.

As all variables finish at the same value they start, the animation may be played cyclically. The effect is as if the sphere is slowly bouncing on the lower plane, and almost hitting the higher plane at the peak of its arc.

The complete animation block is now :


	animation
	{   frames 200
	    duration 2
	    keyframes
	    {   camx
	        {   0,0,     0.5,0,
	            1,0,     1.25,1,
	            1.5,0,   0.75,-1,
	            1.75,-1, 0.25,1,
	            2,0
	        }
	        camy
	        {   0,2,     1.125,1.4,
	            1.4,2.5, 2,2
	        }
	        camz
	        {   0,-1,    0.25,0,
	            0.5,1,   0.75,0,
	            1,-1,    1.25,0,
	            1.5,1,   1.75,0,
	            2,-1
	        }
	        spherey
	        {   0,0,     1,3,
	            2,0
	        }
	    }
	}

The Animay file is now complete, and the frames for the animation can be generated with a command similar to "animay -i demo.anp", where "demo.anp" is a text file with this data in it.

3.2.3 Spline Images

The following images show the spline curves of the four variables :

"camx"

"camy"

"camz"

"spherey"

3.2.4 Frame Images

The following images show frames 0, 90, and 140 of the resulting animation :

An mpeg of the demo may be retrieved by anonymous FTP from guri.cage.curtin.edu.au:/pub/animay/animay.demo.mpg

4.0 Wielding Animay

4.1 Command Line Parameters

At this stage there are only a few command line parameters for Animay, but as planned features are installed, this will increase. What follows is a list of the parameters, and an explanation as to their purpose.

-i 'filename': Specifies which file the scene and animation data is stored in. This option is required, as an animation file is necessary to generate any animation.
-o 'filename': Specifies the file prefix to save the frames as.
If the filename specified ends in a '/', then the string appended is 'frame###.tga', where ### is the frame number. For example, if the parameter is '-o frames/', then frame 0 will be saved as 'frames/frame000.tga'.
If the filename specified does not end in '/', then the string appended is '###.tga', where ### is the frame number. For example, if the parameter is '-o ahawb', then frame 0 will be saved as 'ahawb000.tga'.
-p: Gives a preview of the spline curve of each variable, rather than generating the animation. For the standard Animay, the curve is displayed as text. For the Motif version, Animay will enter edit mode, which contains a graphic display of the splines.
-e: This is available to the Motif version only, and has the same effect as the -p option. It enters Animay into edit mode, with a graphical display of the spline curves and editing facilities for easy insertion, deletion, and alteration of keyframes.

4.2 Other Ways of Setting Parameters

Parameters may also be passed to Animay by setting an environment variable. This is 'ANIMAYOPT' by default, but may be altered in "animay.h" if so desired. By setting the environment variable, any frequently used options need not be retyped. For example, you may be working on an animation from the file "scrolly.anp", you want the frames written to the "scrollyframe" directory, and you always use the Motif interface. To simplify things, you would set the ANIMAYOPT environment variable to be "-i scrolly.anp -o scrollyframe/ -e".

5.0 Glossary of Terms

The following terms are used in reference within this document. The definitions here are those relevant to this document, to help further understanding of the concepts involved. If there are any terms anyone doesn't understand within this document, E-mail me and I will include them in the glossary.

render

To generate an image from a set of 3D data by the process of Raytracing.

raytracing

A type of rendering a 3D scene by tracing a ray from the "eye" into the scene, where each collision, reflection and refraction with the ray has an effect. The resultant image can be photo-realistic.

define

In C programs, a define sets a value to a label. When the code is compiled, all occurrences of the label are replaced by the value. This is helpful in setting a value once which will be frequently used. If the value needs to be changed, it only needs to be changed in the one place, rather than at each occurrence in the code.
The format of a define statement is :
#define The labels are usually written in all capitals, so as to easily distinguish them from variables when reading the code.

environment variable

An environment variable is a variable within a shell such as unix or DOS. These may be set before running a program, and will still be valid after a program has finished. There are different ways of setting an environment variable for different systems.

In DOS :: set 'variable'='value'
In unix's bourne shell :: 'variable'='value'; EXPORT 'variable'
And in unix's C shell :: setenv 'variable' 'value'

Trevor Phillips

phillips@guri.cage.curtin.edu.au