AGAVE - Access Grid Augmented Virtual Environment

Electronic Visualization Laboratory, University of Illinois at Chicago
System Requirements
Building COANIM
Importing your models
Download COANIM


The overall concept behind AGAVE is to append a low-cost PC-based graphics workstation to an Access Grid node that can be used to project 3D stereoscopic computer graphics to allow collaborators to share 3D content.

The details on how to build the AGAVE can be found at:

This document describes how to install several pieces of software that will allow collaborators to share 3D content over AGAVE.

System Requirements

 The software has been tested on Red Hat Linux Version 6.1.  In addition, you should have installed
IRIS Performer - (required)

CAVE library - (needed only if you intend to compile the application from scratch. We recommend that you use the precompiled executeables the first time around.)

CAVERNsoft - (needed only if you intend to compile the application from scratch. We recommend that you use the precompiled executeables the first time around.)

Content - COANIM

COANIM (or the Collaborative Animator) is the application for viewing 3D content over AGAVE. It basically provides a  flip-book playback of 3D models. Coanim provides this capability to collaborating users so that several users can playback, stop, and single step through the animation.The example dataset that has been included in this distribution contains an animation of the heart and lung showing the blood flow between them.

COANIM relies on the CAVERNsoft toolkit for the networking support required in order for distributed users to collaboratively visualize data.

The IRIS Performer and CAVElib allows the COANIM application to run across various display architectures. Hence, a collaborator in the CAVE is able to work with a collaborator on AGAVE seamlessly.
Coanim Overview


  1. Unpack the distribution using the command

  2. tar -zxvf agave.tar.gz
  3. This will create a top-level directory called agave with the following sub-directories

  4. (Note : 'xxx' denotes current version number)
      CAVERNG2_xxx The CAVERNSoft networking libraries
      modules_xxx The COANIM application and supporting modules
      AGAVE_README_files This README file
  5. Change the current directory to agave

  6. cd AGAVE
  7. Begin by running the server as follows

  9. Now, multiple clients on different machines can collaborate through this central server. For each client, type

  10. RUN_CLIENT <yourName> <serverIPAddress>
      serverIPAddress is the address of the server in step 4
      yourName is the name used to identify yourself in the collaborative environment
    This will bring up a model of the heart and lung as shown below. If you do not experience the 3D nature of the graphics, you will have to adjust certain parameters in the configuration file .caverc located under AGAVE/modules_xxx/coanim. The file explains which parameters ( X and Y offsets) you would need to modify.

    Use the RUN_CLIENT script as an example of how to use coanim to view your own data. Note that coanim requires that you have a copy of all the data at each collaborating site before collaboration begins, since coanim must load the data files from local disk. See the section on Importing Your Own Modules for details.

    Note also that you can obtain a list of coanim's command line options by typing: coanim and pressing return.



With this example, among other things, you can cycle through the animation of the lung, and using the cutting plane, slice through the heart to see the blood flow inside. Described here are all the possible forms of interaction.

Button Controls

The wand buttons are programmed for the following interactions within COANIM
LEFT button Brings up the menu shown below. Select items using the left button
MIDDLE button  Rotate the object around. It will follow your wand
RIGHT button Pickup and move the clipping plane

Keyboard Controls

Alternatively, all the menu options above are also accessible using the following keyboard shortcuts.
X Play animation
SHIFT + X Stop animation
Enable Cutting Plane
SHIFT + C Disable Cutting Plane
B Scale up the models
SHIFT + B Scale down
- Decrease Play Speed
= Increase Play Speed
N Show Next Frame
R Reset
I Rotate Up
K Rotate Down
J Rotate Left
L Rotate Right
U Rotate Counter Clockwise
O Rotate Clockwise

Simulated Wand Controls

In AGAVE, the wand is controlled using the mouse and keyboard. Moving the mouse while holding down the appropriate key will move or rotate the wand.
CTRL + mouse movement Move wand left/right/forward/back
SHIFT + mouse movement Move wand left/right/up/down
ALT + mouse movement Rotate wand left/right/up/down
< and > Roll wand (rotate about Z)
HOME Reset wand to be in front of user

Pressing the mouse buttons corresponds to pressing the wand buttons. Holding down the spacebar while moving the mouse controls the joystick values. Note that the joystick controls set the X and Y values based on the current position of the mouse on the screen, rather than the mouse's relative movement (i.e. the top of the screen is Y=1.0, etc.). The joystick is reset to (0,0) when the spacebar is released.

Building COANIM

It is recommended that you use the already pre-compiled software. However, if you still need to build the software, these are the steps
  1. Change directories - cd AGAVE/modules_xxx

  2. Set an environment variable CAVERN_DISTRIB to point to the CAVERNsoft distribution within the AGAVE directory.
        For example, if the distribution is in /usr/tmp/AGAVE/CAVERNG2_xxx, then
        for csh and tcsh, type

        setenv CAVERN_DISTRIB /usr/tmp/AGAVE/CAVERNG2_xxx

        for bash,type


  3. To build, type - Make.script LINUX

Importing your models

If you have pfb models, these can be easily imported into COANIM
  1. Change directories - cd agave/modules_xxx/coanim
  2. Edit the file RUN_CLIENT- vi RUN_CLIENT
  3. In the command-line options for coanim, replace $frames/*.pfbwith your pfb filenames
  4. If you have IRIS Performer installed, you can convert from other 3D file formats to pfb, using

  5. pfconv <yourfile>.<format> <newfilename>.pfb

Download COANIM

                COANIM.tar.gz - Click to begin download


If you have any problems, questions, or feedback please send email to
You can also visit the CAVERNsoft G2  website at The Open Channel Foundation