VideoAvatar Library

VideoAvatar Library version 1.0

Electronic Visualization Laboratory
University of Illinois at Chicago
851 S. Morgan St., Room 1120
Chicago, IL 60607-7053
(312) 996-3002
(312) 413-7585 fax
cavesupport@evl.uic.edu

written by Joseph A. Insley

There are two different services provided by the VideoAvatar library. The first is supplying remote avatars, which represent and are controlled by remote, networked users. The second is to allow the use of local avatars, whose position and orientation are controlled by the programmer. The two services may be used together or independently.

1. Networking

2. Compiling: Includes/Makefiles

3. Needed Files

4. Configuration File

5. Functions

6. Examples

7. Additional Information

Networking

In order to use the REMOTE AVATARS you need to add some code to your .caverc file:

 Network          y
 NetworkAddress   224.2.242.117
 NetworkPort      6302
 NetworkAppPort   6303
 NetworkTTL       4
 NetworkUpdateInterval   .05

The two port numbers should be unique numbers that are the same for all users that wish to share the same environment. There could be conflicts if multiple users have the same port numbers, but are running different applications.

Consult CAVE User's Guide or Dave Pape for further info on the Network stuff.

Compiling: Includes/Makefiles

Include

In C++ files
For OpenGL applications include:

#include "VidAv.h"

In C++ files
For Performer applications include:

#include "pfVidAv.h"

Makefiles

Here is an example makefile

Needed Files

Each avatar (local or remote) requires a pair of files:

VABaseName.vamv: a movie file from which images will be taken to represent the avatar
VABaseName.vachroma: a text file which contains information on how to drop out the background from the movie images

These files are created using VAgui and VAip, which are documented elsewhere.

Multiple avatars can use the same pair of files. These files should be stored together in a directory whose path is specified in va.config (see Configuration File below. Until things are set up a little better, it may be a bit difficult to capture your own avatars, but I could certainly give you a hand if you're interested. In the meantime, there are a variety of avatars located /nfs/avatars/ and /nfs/insley/AVATARS/ that you should feel free to use.)

Configuration File

va.config

This file must be in the same directory as the executable program.

Example:

VADirectory /nfs/avatars
VABaseName toast
VANumberOfImages 150
VAImageResX 256
VAimageResY 512

Currently the library is only implemented to be used between machines on the same local network.

VADirectory and VABaseName: are used to tell remote users which files to use to represent me in their environment.
They are not required if the application is not networked.
VADirectory: is the complete directory path (excluding the ending "/") to the .vamv and .vachroma files.
VABaseName

Functions

With the exception of the PreInit functions, all of these functions work the same in both the OpenGL and the Performer versions of the VideoAvatar library. However, where some of the functions need to be called from also varies between the two versions, as noted below. Functions that accept arguments that relate to the coordinate system assume that they are specified in the appropriate orientation, (OpenGL: +Y-up; Performer: +Z-up).

void va_DisableLocalAvatar(int avatar);: Turns avatar, (the indicated local avatar) off so that it does not get drawn.
(All avatars are initially enabled by default, but will not be drawn until all of their images have been loaded.)
void va_DisableRemoteAvatars(void);: Turns all remote avatars off so that they do not get drawn or updated.
(All avatars are initially enabled by default, but will not be drawn until all of their images have been loaded.)
void va_DrawAllAvatars(void); void va_DrawAllAvatars(float Xorig, float Yorig, float Zorig);: Draws all local and/or remote avatars that are currently enabled. Xorig, Yorig and Zorig, if specified, indicate the distance that the origin of the environment that the avatars are to be placed in is from the origin of the world coordinate system. (This was implemented to enable use with multi-application heirarchies such as CAT, in most cases these values can be omitted.)
In OpenGL: Should be the last function called from CAVEDisplay();
In Performer: Should be the last function called from pfCAVEPostDrawFunc();
void va_EnableLocalAvatar(int num);: Turns avatar, (the indicated local avatar) on so that it does get drawn.
(All avatars are initially enabled by default, but will not be drawn until all of their images have been loaded.)
void va_EnableRemoteAvatars(void);: Turns all remote avatars on so that they do get drawn and updated.
(All avatars are initially enabled by default, but will not be drawn until all of their images have been loaded.)
float va_GetLocalAvatarScale(int avatar);: Returns the scale value being used for avatar.
float va_GetRemoteAvatarScale(void);: Returns the scale value being used for all remote avatars.
int va_InitLocalAvatar(char *dir, char *base); int va_InitLocalAvatar(char *dir, char *base, int NumberOfImages);: Initializes a local avatar and starts a seperate process which loads in the images for that avatar. The .vamv and .vachroma files that are to be used to represent this avatar should be located in dir and have the base name base. The integer that is returned is an id which is used to reference this avatar when updating its position or changing its drawing status, etc. The optional NumberOfImages argument can be used to override the value set in va.config for the number of images that should be used for this avatar. Only this particular avatar will be effected. Remote avatars always use the value set va.config, and cannot be set individually.
In OpenGL: Should be called after va_PreInit(); and before CAVEInit();
In Performer: Should be called after va_PrePreInit(); and before pfCAVEConfig();
int va_InitTex(void);: Sets up the texturemapping for the video avatars.
In OpenGL: Should be called with CAVEInitApplication();
In Performer: Should be called only once with pfCAVEPreDrawFunc();
int va_LocalAvatarIsEnabled(int avatar);: Returns 1 if avatar is enabled for drawing, and 0 if it is not.
int va_LocalAvatarIsLoaded(int avatar);: Returns 1 if avatar's images have finished being loaded, and 0 if they have not. This is useful to know if you don't want to start updating the avatar's position until after it starts being drawn. (By default, avatars but will not be drawn until all of their images have been loaded.)
void va_PreInit(void);: OpenGL version:
Reads "va.config" file, initializes shared memory, and adds CAVE networking callbacks.
Must be called before CAVEInit();
Performer version:
Adds CAVE networking callbacks.
Must be called after pfCAVEConfig(); and before pfConfig();
void va_PrePreInit(void);: Performer version only:
Reads "va.config" file and initializes shared memory.
Must be called after pfInit(); and before pfCAVEConfig();
int va_RemoteAvatarsAreEnabled(void);: Returns 1 if remote avatars are enabled for drawing, and 0 if they are not.
void va_SetLocalAvatarScale(int avatar, float scale);: Sets the scale value for avatar to be scale.
void va_SetMonoMode(void); void va_SetMonoMode(int WhichAvatar);: Can be used to force avatars to be drawn in mono, or in other words use the same image to repersent the avatar to both eyes. Can be useful when the number of images being used is so low as to prevent fusion from taking place. WhichAvatar can be va_LOCAL, all local avatars; va_REMOTE, all remote avatars; va_ALL, all local and remote avatars; or the id of a particular local avatar, as returned by va_InitLocalAvatar(). If WhichAvatar is not sepeicied, va_ALL is assumed. All avatars are in stereo mode by default.
void va_SetRemoteAvatarScale(float scale);: Sets the scale value for all remote avatars to be scale.
void va_SetStereoMode(void); void va_SetStereoMode(int WhichAvatar);: Used to return avatars to stereo mode. WhichAvatar can be va_LOCAL, all local avatars; va_REMOTE, all remote avatars; va_ALL, all local and remote avatars; or the id of a particular local avatar, as returned by va_InitLocalAvatar(). If WhichAvatar is not sepeicied, va_ALL is assumed. All avatars are in stereo mode by default.
void va_UpdateAllAvatars(void); void va_UpdateAllAvatars(float Xorig, float Yorig, float Zorig);: Updates positions, etc. for all remote avatars, if there are any and they are enabled. Does additional calculations required for local avatars. Xorig, Yorig and Zorig, if specified, indicate the distance that the origin of the environment that the avatars are to be placed in is from the origin of the world coordinate system. (This was implemented to enable use with multi-application heirarchies such as CAT, in most cases these values can be omitted.)
Must be called after all (if any) calls to va_UpdateLocalAvatar();
In OpenGL: Called from CAVEFrameFunction();
In Performer: Called from pfCAVEPostDrawFunc();
void va_UpdateLocalAvatar(int avatar, float Xpos, float Ypos, float Zpos, float UProt); void va_UpdateLocalAvatar(int avatar, float Xpos, float Ypos, float Zpos, float UProt, float Xorig, float Yorig, float Zorig);: Updates avatar to be at the position indicated by Xpos, Ypos, and Zpos and facing in the direction of UProt (which corresponds to rotation around the Y-axis in OpenGL and the Z-axis in Performer. Also, 0degrees is looking down the -Z-axis in OpenGL, or the +Y-axis in Performer, positive rotation is clockwise.) Note: because all avatars are placed on the same sized polygon, the user's head is actually somewhere in the middle of that polygon. To simplify things the Ypos (Zpos in Performer) is based on the position of the user's feet, (or the ground that they are standing on). Xorig, Yorig and Zorig, if specified, indicate the distance that the origin of the environment that the avatars are to be placed in is from the origin of the world coordinate system. (This was implemented to enable use with multi-application heirarchies such as CAT, in most cases these values can be omitted.)
Must be called before va_UpdateAllAvatars();
In OpenGL: Called from CAVEFrameFunction();
In Performer: Called from pfCAVEPostDrawFunc();

Examples

The code for all the following examples can be found in VideoAvatarExamples.tar.gz

Remote

This is a simple program that uses remote avatars. You will need to add the block of Networking calls to your .caverc file. As stated in the Networking section above, it is a good idea to change the NetworkPort and NetworkAppPort numbers to unique numbers, so that you don't accidentally connect to another user that may be running a different application. However, all users that want to be networked should all use the same numbers. (This will also work for a single user logged into multiple machines.)

Try it out:
In VideoAvatarExamples/remote directory compile by typing "make remote" (or "make pfremote" for Performer version). To execute, type "remote" (or "pfremote") from two or more different machines.

You can navigate before the images are loaded, but the avatars won't start drawing until all of their images are done loading. MIDDLE_BUTTON toggles the enable for remote avatars off and on. LEFT_BUTTON prints the enable state for the remote avatars. The "9" key decreases the scale of all Remote Avatars. The "0" key increases the scale of all Remote Avatars.

Here is a look at the OpenGL example code.
Here is a look at the Performer example code.

Local

This is a simple program that uses a local avatar. There is no need to add anything to your .caverc file. If networking does happen to be enabled, and another application which uses the same NetworkPort and NetworkAppPort is started, a remote avatar will be loaded, but the call to va_DisableRemoteAvatars(); will prevent it from being drawn or updated. In fact, this call is the only difference between this program, which has only local avatars, and the one that has both local and remote avatars.

Try it out:
In VideoAvatarExamples/local directory compile by typing "make local" (or "make pflocal" for Performer version). To execute, type "local" (or "pflocal").

You can navigate before the images are loaded, but the avatar won't start drawing until all of its images are done loading. MIDDLE_BUTTON toggles the enable for that local avatar off and on. LEFT_BUTTON prints the enable state of that avatar. RIGHT_BUTTON toggles the user-defined update off and on. The "-" key decreases the scale of the Local Avatar. The "=" key increases the scale of the Local Avatar. Note in the code that whenever the avatar is being drawn, va_UpdateLocalAvatar(); must be called. Because even if the avatar's position is not changing, the user's position might be.

Here is a look at the OpenGL example code.
Here is a look at the Performer example code.

Local & Remote

This is a simple program that uses both local and remote avatars. You will need to add the block of Networking calls to your .caverc file. As stated in the Networking section above, it is a good idea to change the NetworkPort and NetworkAppPort numbers to unique numbers, so that you don't accidentally connect to another user that may be running a different application. However, all users that want to be networked should all use the same numbers. (This will also work for a single user logged into multiple machines.)

Try it out:
In VideoAvatarExamples/both directory compile by typing "make both" (or "make pfboth" for Performer version). To execute, type "both" (or "pfboth") from two or more different machines.

You can navigate before the images are loaded, but the avatars won't start drawing until all of their images are done loading. MIDDLE_BUTTON toggles the enable for that local avatar off and on. LEFT_BUTTON toggles the enable for remote avatars off and on. RIGHT_BUTTON toggles the user-defined update off and on. The "-" key decreases the scale of the Local Avatar. The "=" key increases the scale of the Local Avatar. The "9" key decreases the scale of all Remote Avatars. The "0" key increases the scale of all Remote Avatars. Note in the code that whenever the avatar is being drawn, va_UpdateLocalAvatar(); must be called. Because even if the avatar's position is not changing, the user's position might be.

Here is a look at the OpenGL example code.
Here is a look at the Performer example code.

Additional Information

Sketch for SIGGRAPH 97: Contains a paper the was written for, and will be presented as, a Sketch at SIGGRAPH 97 in Los Angeles in August 1997.
Stereo Vision: Explains how to calculate the number of images that are needed for stereo vision. Shows examples of how many images are needed if object is viewed from various distances.
Selecting an Image: Explains how to calculate which image should be used to represent an avatar at any particular point in time (or space, as the case may be).
Capturing an Avatar: Explains how the chroma keying is done to drop out the background of the avatars. Also explains how to set up and run the software to capture your own avatars.
Gallery of Avatars: Has a handful of images of VideoAvatars being used in applications.