vhdPLUS

What is vhdPLUS?

The vhdPLUS Development Framework is a modern, fully component oriented simulation engine and software middleware solution created by and reflecting many years of the R&D experience of both the MIRALab, University of Geneva and VRlab, EPFL labs in the domain of VR/AR and virtual character simulation.

New release April 25th 2008

In this release we include a new library (libcapture) that provides a common interface to several video capture APIs and can be used as part of an Augmented Reality setup. It currently connects to the has the following access modes:

The library is simple and clean enough to include your own API of choice.
Besides the release of this new library there also have been several fixes and cleanups to the sources and configuration files.

Documentation

For a basic introduction into vhdPLUS and the motivation for its development you could read this page. If you are interested in the inner workings of vhdPLUS or if you want to know how vhdPLUS is structured, you can find more information in the documents below. They also include a case study of vhdPLUS's parent framework VHD++, an encompassing framework including several proprietary virtual human simulation plugins (e.g. real-time hair, clothes) employed in several EU and Industrial projects. These proprietary plugins are not included with vhdPLUS. So wherever you read "VHD++" in these documents, you can replace it with "vhdPLUS".

You can also take a look at the source code documentation.

Prerequisites

As a development environment we use Microsoft Visual Studio 2003 .NET (sometimes referred to as version 7.1)
In order to be able to install and run vhdPLUS your system needs to have a number of 3rd party libraries installed.

GNU Tools (Flex, Bison, Sed, etc.)

We use some of the GNU tools like Sed in our build process. If you haven't already installed these tools on your system, you can download Windows versions for them from this page.

Python & Scons

Even though we use Visual Studio for our development, we use SCons as our build system. And since SCons uses Python, you need to install both these components. (We currently use Python 2.3 and SCons 0.96.1)

OpenThreads

The threading in vhdPLUS is based on OpenThreads. So you will need this library to run vhdPLUS. However if you are going to use OpenSceneGraph as a rendering platform, you can skip this download and get it included with the OpenSceneGraph package (see below).

QT

vhdPLUS uses QT for its GUI-s and for the OpenSG based viewer service (see below). We are currently using QT version 3. You can either use the commercial version that can be obtained from Trolltech, or you can use the Open Source implementation that can be found here. We have successfully used both of them.

OpenSceneGraph & OpenSG

This release of vhdPLUS comes with two scenegraph based rendering services. One is based on OpenSceneGraph and another more basic service is based on OpenSG.
In order to use the OpenSceneGraph service you will need to setup OpenSceneGraph and its dependencies on your system. The three basic components can be found on the OpenSceneGraph website in one convenient package including all their dependencies.
You will also need osgNV, which can be found at the osgNV website. OpenSG can be found on their website. You could build all the libraries, but we require neither OSGWindowGlut nor OSGWindowQT.

SWIG

SWIG is a software development tool that connects programs written in C and C++ with a variety of high-level programming languages. We use it to connect to Python. You can find SWIG at the SWIG website.

Xerces

Everything in vhdPLUS is set up and initialized using XML. We use Xerces for handling this. You can find it here.

Downloading vhdPLUS

You can download vhdPLUS by going to the sourceforge project page. There you will find a .zip file containing the current release. We currently do not use a CVS repository.

Installing vhdPLUS

Before actually building vhdPLUS, you need to make sure that all the necessary outside components have been set up properly. Make sure that the "Path" environment variable includes the directories containing the binaries of the prerequisites as well as the dll's. Make sure that Visual Studio knows where to find the include and library files for the libraries you are going to use, as well as the binary files (exe's) for the tools you are going to use like sed.
Within the vhdpp_open_sourcePLUS/cfg directory, you will find 5 files. These files are used for the setup of the build system (directories, compiler options, etc.) the selection of modules that need to be built when doing a full build and the mapping of actual library names to easier to use names. Modify the vhdpp_open_sourcePLUS\cfg\config_md.win32 and vhdpp_open_sourcePLUS\cfg\config_md_dbg.win32 to use the proper paths. Modify the vhdpp_open_sourcePLUS\cfg\modules.lst.win32 for the modules you want to build (Just leave it as is when you want to build everything) and modify libnames_debug.win32 and libnames_release.win32 for the external dependencies. These last two files are used to create a common name for both the release and debug versions of libraries.
The vhdPLUS distribution comes with a Visual Studio 7.1 solution file called vhdpp_open_source.sln. If you open this you will notice that there are a number of projects included. Some are libraries, some are services and others are GUI's. There is however one special project called BuildAll. As the name suggests, building this project means that everything will be built. So for the initial build, build this project. Sometimes the building process doesn't work at once because of some unresolved dependencies. Just building the BuildAll project again most of the times resolves these issues.

Running vhdPLUS

In order to run vhdPLUS you will need to configure the system using XML files. There are two XML files that come with the vhdPLUS distribution called v11_sys.xml and v11_dta.xml. You can find them in the directory vhdpp_open_sourcePLUS\vhdMetaEngine. The v11_sys.xml file is used to set up the system. Within it you can enable or disable the loading of services.
First of all you need to make sure that all the services are specified within the <vhdServiceSchedulerConfigProperty> ... <\vhdServiceSchedulerConfigProperty> tags. After that you can specify which services should actually be started by using the following tag (loading vhdOSGViewerService in this case) <service className="vhdOSGViewerService" name="osgViewerService" />. The same goes for any GUIs that you would like to load. The following tag for example is used to load the GUI for use with OpenSG: <vhdGUIConfigProperty name = "vhdOpenSGGUI"/>. Apart from this all the services are configurable through this XML file as well. In the v11_sys.xml file that comes with this release, you will find examples for the different services. They should be mostly self-explanatory.
Within the v11_dta.xml file you specify the data you want to load and the seach paths vhdPLUS should look at for data. The XML file that comes with this release contains example tags for both the OpenSceneGraph based viewer service as well as for the OpenSG based viewer service. They should again be self-explanatory.

Once you have configured everything and you are ready to run vhdPLUS, you can do so by running vhdMetaEngine_md.exe (or the debug version of it) with v11_sys.xml and v11_dta.xml as arguments. If everything compiled successfully you will find vhdMetaEngine_md.exe in the vhdpp_build_win32PLUS\bin directory. From the command line this would look as follows:

 > vhdMetaEngine v11_sys.xml v11_dta.xml

In case you would like to run vhdPLUS from within Visual Studio, you will have to configure the vhdMetaEngine project in the Visual Studio solution. Go to the properties of the vhdMetaEngine project and go to the Debugging properties. Most likely there is already some information there, but in case there isn't, this is what you will have to fill in:

  Command : C:\whatever_path_to_vhdPLUS\vhdpp_build_win32PLUS\bin\vhdMetaEngine_md_dbg.exe
  Command Arguments : v11_sys.xml v11_dta.xml
  Working Directory : c:\whatever_path_to_vhdPLUS\vhdpp_open_sourcePLUS\vhdMetaEngine
  

Once you have done this for both the debug and release version (make sure you select the correct vhdMetaEngine exe's for both versions) you can run vhdPLUS from within Visual Studio. Have fun with it!

But WAIT a moment. What if vhdPLUS doesn't run correctly? Or what if it doesn't start up at all? How do you know what went wrong? Luckily vhdPLUS comes with its own logging mechanism. Within the directory vhdpp_open_sourcePLUS\vhdMetaEngine you will find two log files called vhdpp_cerr.log and vhdpp_cout.log respectively, after having run vhdPLUS for the first time. These two files contain the logging information vhdPLUS generates. The cerr version contains the most serious information on the run-time behaviour of vhdPLUS. Within the same directory you will find an application called vhdlogmonitor.exe. This application makes it easier to view to log-files since it will color-code the messages in there. Just open the log files in this application. You can even leave this application open while running vhdPLUS. Then you will be able to see all the logging messages appear at run-time.

The vhdPLUS team wishes you good luck and hopes you will make good use of vhdPLUS.

Acknowledgments

EPOCH NoE in Open Cultural Heritage

vhdPLUS has been released with support of the EPOCH Network of Exellence in Open Cultural Heritage, as its release is part of one of the NEWTON (New Tools Needed) projects called Characterise.

Citing vhdPLUS

If you want to cite vhdPLUS for its technology and uses, please cite the following article:

      @article{ppm03,
        author = {Michal Ponder and George Papagiannakis and Tom Molet and Nadia Magnenat-Thalmann and Daniel Thalmann},
        title = {VHD++ Development Framework: Towards Extendible, 
                       Component Based VR/AR Simulation Engine Featuring Advanced Virtual Character Technologies},
        journal = {cgi},
        volume = {00},
        year = {2003},
        issn = {1530-1052},
        pages = {96},
        doi = {http://doi.ieeecomputersociety.org/10.1109/CGI.2003.1214453},
        publisher = {IEEE Computer Society},
        address = {Los Alamitos, CA, USA},
      }
    

SourceForge.net Logo