CalVR
Contents |
Overview
This wiki page was created to give programmers an overview of how to use IVL's virtual reality visualization framework CalVR. Special emphasis is given to those programmers who already know how to write code for COVISE.
What is CalVR?
CalVR is a virtual reality framework which has been entirely developed in the Immersive Visualization Laboratory at Calit2. It is designed to be open source and royalty free. CalVR implements the typically used VR functionality of middleware such as CAVElib, COVISE, VRUI or FreeVR and adds to it by supporting nonstandard VR systems like autostereoscopic displays, as well as multi-user support for viewing and interaction. CalVR is entirely object oriented and written in C++. Functionality can be added through a simple plug-in system which allows compiling new modules separately from the main code. CalVR has built-in navigation algorithms, a 3D menu system, support for a variety of 3D display and tracking systems, as well as support for collaborative work at different sites. The campus wide visibility of Calit2’s Immersive Visualization Laboratory (IVL) has allowed the group to engage in a large variety of software application research and development with groups from many of UCSD’s departments. The experience from more than six years of campus-wide collaborations and many publications reporting on those projects both in the virtual reality community and also the domain sciences is flowing into the design and development of the CalVR software framework.
CalVR Specs
- Operating system: CentOS 5 Linux, Mac OS X (experimental: only tested on 10.6.7.)
- Programming language: C++
- Graphics API: OpenSceneGraph
- Build system: CMake
- Tracking APIs supported: VRPN, TrackD
- PC cluster support
- Support for multi-screen virtual reality systems
Building CalVR
The project is built with cmake. At the moment, it is set to require at least version 2.8.
Dependencies
The major external libraries needed are:
OpenSceneGraph - version 3.0.1 is currently recommended.
MiniXML - 2.6
Building OSG
The latest release of OSG can be found here. (See above for suggested version)
Go to main OSG directory and type ccmake .
In CMAKE_BUILD_TYPE, press Enter to edit the field, type in one of the options that with debug information: RelWithDebInfo
On Mac OS X, set OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX to "imageio" and OSG_WINDOWING_SYSTEM to "Cocoa".
Press 'c' to configure, press 'g' to generate. and 'q' to quit. Now type make to build. Go get coffee.
OSG Extra Libraries
There are a number of extra libraries that are optional, but can be built into osg to add additional functionality. This is done by building/installing the libraries then setting the include/library path values in the osg ccmake window. When all paths are added, configure, generate the makefiles, and compile.
Coin3d
http://www.coin3d.org/
This is a highly recommended library to add. It adds vrml support to osg.
If you want the vrml models to have texture support, you need to build coin with the simage library: http://www.coin3d.org/lib/simage
After you have configured/built/installed simage, configure coin with a line something like this:
configure --prefix=YOURINSTALLPATH --with-simage=YOURSIMAGEINSTALLHOME --disable-dl-simage
If all went well, the final configure settings output should contain:
simage linkage: link-time binding
To build osg with coin, define the INVENTOR_INCLUDE_DIR to point to the coin include directory and the INVENTOR_LIBRARY_RELEASE to point to the coin library.
Getting the Code
The CalVR repository is split into two sections, one of the framework and another for the plugins.
GitHub
You can do a read only checkout by doing the following:
git clone git://github.com/CalVR/calvr.git CalVR git clone git://github.com/CalVR/calvr_plugins.git CVRPlugins
Developers in the IVL who do not need to modify the core of CalVR should use the shared CalVR sources under /home/calvr/CalVR, and should check out the plugin sources from the GitHub repository into their home directories. To make this work you are going to need to create a GitHub account. Send your account name to an administrator to be added to the developer list. Once you have been added, you will need to create an RSA key pair with the following command:
ssh-keygen -t rsa
You can just hit return when asked for a passphrase.
If you get an error message like "Could not create directory '/home/<username>/.ssh'" then an administrator needs to run "yum install selinux-policy.noarch" on your system as this is a known CentOS bug.
Once you have your RSA key pair, you can continue with step 4 of these instructions.
Then, to pull down the CalVR plugin code from GitHub you need to do the following in your home directory (replace "username" with your GitHub name):
git clone git@github.com:username/CalVR/calvr_plugins.git CVRPlugins
Calit2 Server
This is only for those users who already have an account on Calit2's GIT server. This is a backup server for GitHub. By default, all plugin developers should use GitHub only.
Checkout the main framework from the repository:
git clone vis2.calit2.net:/git/calvr CalVR
Checkout the plugins from the repository:
git clone vis2.calit2.net:/git/calvr_plugins CVRPlugins
Building Core
To help aid the cmake configure, you can optionally set environment variables for the location of these libraries:
OSG_HOME - location of OpenSceneGraph install, very good to set if cglx has a copy of osg in /usr/local
MXML_HOME - location of MiniXML install
Go to the project root and run
ccmake .
then type 'c' to configure.
If the configure doesn't find the core libraries, manually fill in the information. For OpenSceneGraph, fill in the OSG_HOME value and reconfigure. This should fill in the OSG_INCLUDE_DIR correctly. Note that this process also sets the library locations in hidden variables, so you can't just fill in the include directory manually.
There are also optional libraries that add additional fuctionality.
Interleaver - if present, builds the ability to create a screen for lenticular 3D rendering - TODO: upload src here
From the ccmake menu you can also select which plugins you want to build. Turn those plugins on and reconfigure. The configure will tell you if there are undetected additional libraries needed to build those plugins and the cmake variables for those libraries will now be in the main menu.
When you are done, select the option to generate and exit ccmake.
From here, run make.
Building Plugins
The plugins are built in a similar way. Go the the plugin root directory and run
ccmake .
The plugins also need OpenSceneGraph and this can be set the same way as above. The plugins need to know where the CalVR home directory is. This can either be manually set or it will look for the CALVR_HOME environment variable.
You can then toggle the plugins that you want to build on and reconfigure. If there plugins have any dependencies, they will appear in the cmake config.
Now generate and run make.
CalVR Configuration
Environment
Before runing CalVR you need to add the library directories into your LD_LIBRARY_PATH in .cshrc/.bashrc. On Mac OS X, set DYLD_LIBRARY_PATH.
These directories should include the ${CALVR_HOME}/lib directory and any lib directories for the CalVR dependencies (i.e. osg/mxml/etc)
Add an environment variable to .cshrc/.bashrc, for example:
.cshrc
setenv CALVR_HOME /home/calvr/CalVR/ setenv CALVR_CONFIG_FILE config.xml
.bashrc
export CALVR_HOME=/home/calvr/CalVR/ export CALVR_CONFIG_FILE=config.xml
Config File
Calvr uses an xml based configuration file.
For more infomation on the config file, see: CalVR Config File
Running CalVR
The main CalVR executable is ${CALVR_HOME}/bin/CalVR.
CalVR Application Development
Applications using the CalVR environment are developed in the form of CalVR Plugins.
