CalVR

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.

CalVR Specs

1. Operating system: CentOS 5 Linux, Mac OS X (experimental: only tested on 10.6.7.)
2. Programming language: C++
3. Graphics API: OpenSceneGraph
4. Build system: CMake
5. Tracking APIs supported: VRPN, TrackD
6. PC cluster support
7. Support for multi-screen virtual reality systems

Building OSG

The developer release of OSG can be found here. (See below 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.

Getting the Code

First you will need an account on the GIT server.

The repo is now split into two sections, one of the framework and another for the plugins.

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 CalVR

The project is built with cmake. At the moment, it is set to require at least version 2.8.

The major external libraries needed are:
OpenSceneGraph - development build 2.9.x - Note: the later builds at the moment have some text bounding box issues, 2.9.7 is the current suggested version for Linux and 2.9.16 is the suggested version for OS X.
MiniXML - 2.6

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.

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.

Runing CalVR

Before runing CalVR you need to add osg/lib into your LD_LIBRARY_PATH in .cshrc. On Mac OS X, set DYLD_LIBRARY_PATH.

Add an environment variable to .cshrc, for example:

setenv CALVR_HOME /home/hwang/CalVR/
setenv CALVR_CONFIG_FILE config.xml

For more infomation on the config file, see: CalVR Config File

The main CalVR executable is CalVR/bin/CalVR.

Adding a new Plugin for CalVR

Use CalVR/plugins/calit2/ModelLoader as a template:

Make a copy of the ModelLoader folder, rename it to <YourPluginName>. Each source code directory has the files "CMakeLists.txt" and "cmake_install.cmake". In order for cmake to generate a make file for the new plugin, we need to add an entry to these cmake files in the parent directory, and modify the cmake files in the new plugin directory.

Under the parent directory, e.g., CalVR/plugins/calit2/CmakeLists.txt, add the following lines:

OPTION(PLUGIN_EXAMPLEPLUGIN "ExamplePlugin" ON)

IF(PLUGIN_EXAMPLEPLUGIN)
 ADD_SUBDIRECTORY(ExamplePlugin)
ENDIF(PLUGIN_EXAMPLEPLUGIN)

Under parent directory, say CalVR/plugins/calit2/cmake_install.cmake, find:

IF(NOT CMAKE_INSTALL_LOCAL_ONLY)

add the following line (change to absolute path):

INCLUDE("~/CalVR/plugins/calit2/ExamplePlugin/cmake_install.cmake")

Under the new plugin directory you may remove the CMakeFiles folder as well as the old Makefile which were copied from ModelLoader. There should be only two source files and two cmake files left. Modify these files to adapt the new plugin's name.

Launch cmake, delete the cache if necessary, configure and generate again. Note that under the PLUGINS entry, the calit2 checkbox should be on, and you should be able to find your new plugin name under PLUGIN along with the ModelLoader.

Go back to the plugin directory, the new Makefile should have been generated. Type make to build.

Now we need to modify the CalVR/config/config.xml to turn on the new plugin. We can search for ModelLoader and add the exact lines to config.xml, and modify the names to the new plugin's name. Now run CalVR, in the terminal we should see the init message of the new plugin.

COVISE->CalVR Translation Table

COVISE Syntax	CalVR Syntax
using namespace covise	using namespace cvr
COVERPLUGIN(MyPlugin)	CVRPLUGIN(MyPlugin)
bool MyPlugin::init()	bool MyPlugin::init()
void MyPlugin::preFrame()	void MyPlugin::preFrame()
void MyPlugin::postFrame()	void MyPlugin::postFrame()
void MyPlugin::menuEvent(coMenuItem*)	void MyPlugin::menuCallback(MenuItem*)
void MyPlugin::key(int type, int keySym, int mod)	MyPlugin::keyEvent(bool keyDown, int key, int mod)
cover->getObjectsRoot()->addChild(node)	SceneManager::instance()->getObjectsRoot()->addChild(node)
cover->getPointerMat()	TrackingManager::instance()->getHandMat(int handIndex)
cover->getViewerMat()	TrackingManager::instance()->getHeadMat(int headIndex)