Difference between revisions of "CalVR"

From Immersive Visualization Lab Wiki
Jump to: navigation, search
(Coin3d)
 
(59 intermediate revisions by 3 users not shown)
Line 1: Line 1:
==Overview==
+
=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.
 
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.
 +
 +
If you just want to use CalVR, you can build it from source at [https://github.com/CalVR/calvr this GitHub link].
  
 
==What is CalVR?==
 
==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
+
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, for non-profit use. 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.
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==
+
==CalVR Specification and Features==
  
# Operating system: [http://www.centos.org/ CentOS 5] Linux, Mac OS X (experimental: only tested on 10.6.7.)
+
* Operating system:  
# Programming language: C++
+
** Developed for [http://www.centos.org/ CentOS] Linux
# Graphics API: [http://www.openscenegraph.org OpenSceneGraph]
+
** Also builds for other Linux flavors, for instance SuSe
# Build system: [http://www.cmake.org/cmake/resources/software.html CMake]
+
** Mac OS X: experimental, not always tested
# Tracking APIs supported: [http://www.cs.unc.edu/Research/vrpn/ VRPN], [http://www.mechdyne.com/trackd.aspx TrackD]
+
** Windows: limited to single node
# PC cluster support
+
* Programming language: C++
# Support for multi-screen virtual reality systems
+
* Graphics API: [http://www.openscenegraph.org OpenSceneGraph] (OSG)
 +
** Preferred 3D model file format: VRML, parsed by OSG's Coin3D library
 +
* Build system: [http://www.cmake.org/cmake/resources/software.html CMake]
 +
* XML configuration file for display layout, software parameters, plugin parameters
 +
** Supports Twinview, Xinerama, separate X displays
 +
* Tracking APIs supported: [http://www.cs.unc.edu/Research/vrpn/ VRPN], [http://www.mechdyne.com/trackd.aspx TrackD], [http://code.google.com/p/omicron-sdk/ Omicron (UIC/EVL)]
 +
** Multiple tracked heads and hands supported
 +
** Support for tracked head-mounted displays
 +
** Per-screen fixed cameras are possible
 +
* PC cluster support
 +
** Synchronization over Ethernet, 1+ Gbps preferred
 +
** Each cluster node runs a copy of CalVR
 +
** CalVR on cluster nodes run by remote ssh call from head node
 +
** Buffer swap synchronized over Ethernet
 +
* Support for multi-screen virtual reality systems
 +
** Stereo modes supported: all OSG supported modes (passive, quad-buffer, interlaced), 8-view autostereoscopic displays, mirrored displays
 +
* Support for sound effects through audio server
 +
* Support for collaborative sessions to link multiple VR systems over IP networks
 +
* Separation of core framework code and application development through plug-in system
 +
** Plug-ins are compiled independently of core code into shared object files
 +
* Coordinate system: z coordinate is up
 +
* Two GUI widget libraries supported, clean API for additional libraries
 +
** Functionality abstracted from GUI widget implementation
  
==Building CalVR==
+
=Building CalVR=
  
The project is built with cmake.  At the moment, it is set to require at least version 2.8.
+
The project is built with [http://www.cmake.org/ cmake].  At the moment, it is set to require at least version 2.8.
  
===Dependencies===
+
==Dependencies==
  
 
The major external libraries needed are:
 
The major external libraries needed are:
<br>[http://www.openscenegraph.org/projects/osg/wiki/Downloads OpenSceneGraph] - version 3.0.1 is currently recommended.
+
<br>Latest stable release of [http://www.openscenegraph.org/index.php/download-section/stable-releases OpenSceneGraph]. These instructions have been updated for version 3.6.2.
<br>[http://www.minixml.org MiniXML] - 2.6
+
<br>Latest [http://www.minixml.org MiniXML]
 
<br>
 
<br>
 
<br>Optional Libraries that add additional features:
 
<br>Optional Libraries that add additional features:
Line 33: Line 55:
 
<br>Interleaver - A research library used to render lenticular screens - I will post a copy or add to source when I get permission.
 
<br>Interleaver - A research library used to render lenticular screens - I will post a copy or add to source when I get permission.
  
====Building OSG====
+
===Building OSG===
  
The latest release of OSG can be found [http://www.openscenegraph.org/projects/osg/wiki/Downloads here]. (See above for suggested version)
+
Download OSG from the above link.
 
<br>Go to main OSG directory and type <tt>ccmake .</tt>
 
<br>Go to main OSG directory and type <tt>ccmake .</tt>
<br>In CMAKE_BUILD_TYPE, press Enter to edit the field, type in one of the options that with debug information: RelWithDebInfo
+
<br>In CMAKE_BUILD_TYPE, press Enter to edit the field, type in one of the options with debug information: RelWithDebInfo
 
<br>On Mac OS X, set OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX to "imageio" and OSG_WINDOWING_SYSTEM to "Cocoa".  
 
<br>On Mac OS X, set OSG_DEFAULT_IMAGE_PLUGIN_FOR_OSX to "imageio" and OSG_WINDOWING_SYSTEM to "Cocoa".  
 
<br>Press 'c' to configure, press 'g' to generate. and 'q' to quit. Now type <tt>make</tt> to build. Go get coffee.
 
<br>Press 'c' to configure, press 'g' to generate. and 'q' to quit. Now type <tt>make</tt> to build. Go get coffee.
Line 43: Line 65:
 
=====OSG Extra Libraries=====
 
=====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.
 
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/
+
=====simage=====
<br>This is a highly recommended library to add.  It adds vrml support to osg.
+
 
<br>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
+
Download simage 1.7.0: https://bitbucket.org/Coin3D/coin/downloads/simage-1.7.0.tar.gz
<br>After you have configured/built/installed simage, configure coin with a line something like this:
+
 
 +
If you get the error message "../../simage-1.7.0/src/simage_png.c:326:7: error: dereferencing pointer to incomplete type" then patch simage_png.c by replacing "if (setjmp(png_ptr->jmpbuf)) {" with "if (setjmp(png_jmpbuf(png_ptr))) {".
 +
 
 +
If you want support for extra image types such as TIFF, JPEG, PNG, GIF or JPEG2000, we recommend the following package installs before running configure:
 +
<pre>
 +
sudo yum install libtiff-devel
 +
sudo yum install libjpeg-devel
 +
sudo yum install libpng-devel
 +
sudo yum install giflib-devel
 +
sudo yum install jasper-devel
 +
</pre>
 +
 
 +
=====Coin3d=====
 +
 
 +
Download Coin 3.1.3: https://bitbucket.org/Coin3D/coin/downloads/Coin-3.1.3.tar.gz
 +
 
 +
<br>This is a highly recommended library to add.  It adds VRML support to OSG.
 +
<br>If you want the VRML models to have texture support, you need to build coin with the simage library: https://bitbucket.org/Coin3D/simage
 +
<br>After you have configured/built/installed simage, configure Coin with a line something like this:
 
  configure --prefix=YOURINSTALLPATH --with-simage=YOURSIMAGEINSTALLHOME --disable-dl-simage
 
  configure --prefix=YOURINSTALLPATH --with-simage=YOURSIMAGEINSTALLHOME --disable-dl-simage
 
If all went well, the final configure settings output should contain:
 
If all went well, the final configure settings output should contain:
  simage linkage:           link-time binding
+
  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.
+
 
======LibTIFF-4======
+
If you get the error message "error: ‘cc_debugerror_post’ was not declared in this scope" then include the header
 +
<pre>
 +
#include <Inventor/C/errors/debugerror.h>
 +
</pre>
 +
at the beginning (after the #define) of the file Coin-3.1.3/include/Inventor/SbBasic.h
 +
 
 +
If you get errors about abs functions, add the following define to the src/base/dict.h file before the first header include
 +
<pre>
 +
#define __STRICT_ANSI__
 +
#define __CORRECT_ISO_CPP_STDLIB_H_PROTO
 +
</pre>
 +
 
 +
If you get the error message "/usr/lib/libGL.so: could not read symbols: File in wrong format":
 +
fix it in libtool, or temporarily rename to wrong libGL.so so the linker can't find it.
 +
 
 +
To build osg with Coin3D, define the INVENTOR_INCLUDE_DIR to point to the coin include directory and the INVENTOR_LIBRARY_RELEASE to point to the coin library.
 +
 
 +
=====LibTIFF-4=====
 
ftp://ftp.remotesensing.org/pub/libtiff/
 
ftp://ftp.remotesensing.org/pub/libtiff/
 
Most versions of linux have libtiff installed.  The problem is that this is normally only version 3.X.  There are some features of tiff version 4 that are useful and required for some things.  It is recommended to build and compile against the latest tiff 4 version.
 
Most versions of linux have libtiff installed.  The problem is that this is normally only version 3.X.  There are some features of tiff version 4 that are useful and required for some things.  It is recommended to build and compile against the latest tiff 4 version.
 +
<br>Note: in the cmake configuration tool, the tiff include/library variables are flagged as advance.  You will need to hit 't' to turn on advanced mode and change the entries.
 +
 +
=====COLLADA=====
 +
 +
Download [http://sourceforge.net/projects/collada-dom/files/Collada%20DOM/Collada%20DOM%202.2/Collada%20DOM%202.2.zip/download Collada 2.2] from the Collada server. Note that OSG 3.0.1 '''will not''' work with newer versions of Collada!
 +
 +
* Fix a bug, when in main Collada directory: mv dom/include/1.4/dom/domasset.h dom/include/1.4/dom/domAsset.h
 +
* cp Makefile.linux Makefile
 +
* Only build minizip and dom: in Makefile comment out lines for fx, rt and viewer.
 +
* make
 +
* Copy include files to your include directory:
 +
** mkdir /share/calvr/extlibs/include/collada-dom2.2
 +
** cp -r /share/calvr/extlibs/src/collada-dom-2.2/dom/include/* /share/calvr/extlibs/include/collada-dom2.2
 +
* Copy library files to your lib directory:
 +
** cp /share/calvr/extlibs/src/collada-dom-2.2/dom/build/linux-1.4/libcollada* /share/calvr/extlibs/lib
 +
* Add to .bashrc: export COLLADA_DIR=<prefix-dir>. <prefix-dir> is what you would normally put as --prefix= when configuring. Example: /share/calvr/extlibs
 +
* Run OSG's ccmake .
 +
* Make sure at least all COLLADA lines without DEBUG in them are filled out correctly.
 +
 
===Getting the Code===
 
===Getting the Code===
  
 
The CalVR repository is split into two sections, one of the framework and another for the plugins.
 
The CalVR repository is split into two sections, one of the framework and another for the plugins.
  
====GitHub====
+
===GitHub===
 +
There are two ways to check out the CalVR source code from the GitHub repository: read-only and developer mode. Programmers who want to write CalVR plugins, but don't intend to modify the core should read-only checkout the core, and use the developer checkout method for the plugins.
  
 +
====Read-Only Checkout====
 
You can do a <i>read only</i> checkout by doing the following:
 
You can do a <i>read only</i> checkout by doing the following:
 
  git clone git://github.com/CalVR/calvr.git CalVR
 
  git clone git://github.com/CalVR/calvr.git CalVR
 
  git clone git://github.com/CalVR/calvr_plugins.git CVRPlugins
 
  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 [https://github.com 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:
+
====Developer Checkout====
 +
Developers at 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. Plugin developers outside of IVL should check out the read-only version of the core, and the developer version of the plugin code.
  
ssh-keygen -t rsa
+
To check out code as a developer you first need to get permission from one of the CalVR administrators (Andrew Prudhomme, Philip Weber, Jurgen Schulze). Then you need to [https://github.com create a GitHub account]. Send your account name to an administrator to be added to the developer list.  
 
+
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 [http://help.github.com/linux-set-up-git/ 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):
 
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):
Line 79: Line 152:
 
  git clone https://username@github.com/CalVR/calvr_plugins.git CVRPlugins
 
  git clone https://username@github.com/CalVR/calvr_plugins.git CVRPlugins
  
====Calit2 Server====
+
If you're also working on the CalVR core code, pull it down like this:
  
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.
+
git clone https://username@github.com/CalVR/calvr.git CalVR
  
Checkout the main framework from the repository:
+
==Building Core for Linux==
 
+
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:
 
To help aid the cmake configure, you can optionally set environment variables for the location of these libraries:
Line 122: Line 187:
 
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.
 
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.
 
<br>Now generate and run make.
 
<br>Now generate and run make.
<br>Note: Different plugins have there own library and data dependencies.  See [Plugin Requirements].
+
<br>Note: Different plugins have there own library and data dependencies.  See [[Plugin Configuration]].
 +
 
 +
==Building Core for Windows==
 +
 
 +
The instructions for the Windows build are on a [[BuildWindowsCore | separate page]].
 +
 
 
==CalVR Configuration==
 
==CalVR Configuration==
  
Line 146: Line 216:
  
 
The main CalVR executable is ${CALVR_HOME}/bin/CalVR.
 
The main CalVR executable is ${CALVR_HOME}/bin/CalVR.
 +
 +
Show rendering statistics:
 +
* Click on main rendering window on head node
 +
* Press Shift-S repeatedly to see various levels of detail
 +
* Press Shift-P to see the same on the console
  
 
==CalVR Application Development==
 
==CalVR Application Development==
  
 
Applications using the CalVR environment are developed in the form of [[CalVR Plugins]].
 
Applications using the CalVR environment are developed in the form of [[CalVR Plugins]].

Latest revision as of 22:56, 3 July 2018

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.

If you just want to use CalVR, you can build it from source at this GitHub link.

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, for non-profit use. 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 Specification and Features

  • Operating system:
    • Developed for CentOS Linux
    • Also builds for other Linux flavors, for instance SuSe
    • Mac OS X: experimental, not always tested
    • Windows: limited to single node
  • Programming language: C++
  • Graphics API: OpenSceneGraph (OSG)
    • Preferred 3D model file format: VRML, parsed by OSG's Coin3D library
  • Build system: CMake
  • XML configuration file for display layout, software parameters, plugin parameters
    • Supports Twinview, Xinerama, separate X displays
  • Tracking APIs supported: VRPN, TrackD, Omicron (UIC/EVL)
    • Multiple tracked heads and hands supported
    • Support for tracked head-mounted displays
    • Per-screen fixed cameras are possible
  • PC cluster support
    • Synchronization over Ethernet, 1+ Gbps preferred
    • Each cluster node runs a copy of CalVR
    • CalVR on cluster nodes run by remote ssh call from head node
    • Buffer swap synchronized over Ethernet
  • Support for multi-screen virtual reality systems
    • Stereo modes supported: all OSG supported modes (passive, quad-buffer, interlaced), 8-view autostereoscopic displays, mirrored displays
  • Support for sound effects through audio server
  • Support for collaborative sessions to link multiple VR systems over IP networks
  • Separation of core framework code and application development through plug-in system
    • Plug-ins are compiled independently of core code into shared object files
  • Coordinate system: z coordinate is up
  • Two GUI widget libraries supported, clean API for additional libraries
    • Functionality abstracted from GUI widget implementation

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:
Latest stable release of OpenSceneGraph. These instructions have been updated for version 3.6.2.
Latest MiniXML

Optional Libraries that add additional features:
VRPN - Needed for vrpn tracking support - version 7.29 was that last I tested, though higher probably works.
Interleaver - A research library used to render lenticular screens - I will post a copy or add to source when I get permission.

Building OSG

Download OSG from the above link.
Go to main OSG directory and type ccmake .
In CMAKE_BUILD_TYPE, press Enter to edit the field, type in one of the options 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.

simage

Download simage 1.7.0: https://bitbucket.org/Coin3D/coin/downloads/simage-1.7.0.tar.gz

If you get the error message "../../simage-1.7.0/src/simage_png.c:326:7: error: dereferencing pointer to incomplete type" then patch simage_png.c by replacing "if (setjmp(png_ptr->jmpbuf)) {" with "if (setjmp(png_jmpbuf(png_ptr))) {".

If you want support for extra image types such as TIFF, JPEG, PNG, GIF or JPEG2000, we recommend the following package installs before running configure:

sudo yum install libtiff-devel
sudo yum install libjpeg-devel
sudo yum install libpng-devel
sudo yum install giflib-devel
sudo yum install jasper-devel
Coin3d

Download Coin 3.1.3: https://bitbucket.org/Coin3D/coin/downloads/Coin-3.1.3.tar.gz


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: https://bitbucket.org/Coin3D/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

If you get the error message "error: ‘cc_debugerror_post’ was not declared in this scope" then include the header

#include <Inventor/C/errors/debugerror.h>

at the beginning (after the #define) of the file Coin-3.1.3/include/Inventor/SbBasic.h

If you get errors about abs functions, add the following define to the src/base/dict.h file before the first header include

#define __STRICT_ANSI__
#define __CORRECT_ISO_CPP_STDLIB_H_PROTO

If you get the error message "/usr/lib/libGL.so: could not read symbols: File in wrong format": fix it in libtool, or temporarily rename to wrong libGL.so so the linker can't find it.

To build osg with Coin3D, define the INVENTOR_INCLUDE_DIR to point to the coin include directory and the INVENTOR_LIBRARY_RELEASE to point to the coin library.

LibTIFF-4

ftp://ftp.remotesensing.org/pub/libtiff/ Most versions of linux have libtiff installed. The problem is that this is normally only version 3.X. There are some features of tiff version 4 that are useful and required for some things. It is recommended to build and compile against the latest tiff 4 version.
Note: in the cmake configuration tool, the tiff include/library variables are flagged as advance. You will need to hit 't' to turn on advanced mode and change the entries.

COLLADA

Download Collada 2.2 from the Collada server. Note that OSG 3.0.1 will not work with newer versions of Collada!

  • Fix a bug, when in main Collada directory: mv dom/include/1.4/dom/domasset.h dom/include/1.4/dom/domAsset.h
  • cp Makefile.linux Makefile
  • Only build minizip and dom: in Makefile comment out lines for fx, rt and viewer.
  • make
  • Copy include files to your include directory:
    • mkdir /share/calvr/extlibs/include/collada-dom2.2
    • cp -r /share/calvr/extlibs/src/collada-dom-2.2/dom/include/* /share/calvr/extlibs/include/collada-dom2.2
  • Copy library files to your lib directory:
    • cp /share/calvr/extlibs/src/collada-dom-2.2/dom/build/linux-1.4/libcollada* /share/calvr/extlibs/lib
  • Add to .bashrc: export COLLADA_DIR=<prefix-dir>. <prefix-dir> is what you would normally put as --prefix= when configuring. Example: /share/calvr/extlibs
  • Run OSG's ccmake .
  • Make sure at least all COLLADA lines without DEBUG in them are filled out correctly.

Getting the Code

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

GitHub

There are two ways to check out the CalVR source code from the GitHub repository: read-only and developer mode. Programmers who want to write CalVR plugins, but don't intend to modify the core should read-only checkout the core, and use the developer checkout method for the plugins.

Read-Only Checkout

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

Developer Checkout

Developers at 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. Plugin developers outside of IVL should check out the read-only version of the core, and the developer version of the plugin code.

To check out code as a developer you first need to get permission from one of the CalVR administrators (Andrew Prudhomme, Philip Weber, Jurgen Schulze). Then you need to create a GitHub account. Send your account name to an administrator to be added to the developer list.

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 https://username@github.com/CalVR/calvr_plugins.git CVRPlugins

If you're also working on the CalVR core code, pull it down like this:

git clone https://username@github.com/CalVR/calvr.git CalVR

Building Core for Linux

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.
Note: Different plugins have there own library and data dependencies. See Plugin Configuration.

Building Core for Windows

The instructions for the Windows build are on a separate page.

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.

Show rendering statistics:

  • Click on main rendering window on head node
  • Press Shift-S repeatedly to see various levels of detail
  • Press Shift-P to see the same on the console

CalVR Application Development

Applications using the CalVR environment are developed in the form of CalVR Plugins.