Hello brave soul.

First thing's first, this is a developer release and needs to be compiled. It has many third-party dependencies from the renderer to the video capture context. As yet there is no lovely statically linked binary of levelHead or automagical build script for a folder of dependencies. Nonetheless, I've installed levelHead on many (Ubuntu) systems now and what's listed below should work fine for you.

levelHead is known to build on the English editions (see bug below) of Ubuntu 7.04, 7.10, 8.04, 8.10 and Debian Etch, Lenny systems against the following external dependencies. It's adviseable you adhere to these versions if you want to avoid going spontaneously mad:

  • cal3d 0.11 https://gna.org/projects/cal3d/
  • osgcal 0.1.44 http://download.gna.org/underware/
  • openscenegraph 1.2 http://www.openscenegraph.org/projects/osg/wiki/Downloads/PreviousReleases
  • gstreamer (any) http://www.gstreamer.net/
  • bakefile (any) http://www.bakefile.org/
  • ARToolkit 2.72.1 http://www.hitl.washington.edu/artoolkit/download/
  • ARToolkitPlus 2.1.1 http://studierstube.icg.tu-graz.ac.at/handheld_ar/artoolkitplus.php

    • Optional:

  • linux-uvc revision 228 http://linux-uvc.berlior.de/
  • libwebcam revision 22 http://www.quickcamteam.net/software/libwebcam

    • If you're using Debian Stable (Etch) or Ubuntu 7.10 you can grab cal3d, osgcal and openscenegraph using your package manager. Remember to install the headers (-dev) packages. There are currently no packaged binaries of ARToolkit or ARToolkitPlus available for Linux (or perhaps any platform).

    *BUGNEWS*: The bug encountered after installation where rooms appear 'black' was finally found by Pablo Ripolles. It is related to localisation: levelHead only seems to run on an operating system localised to English! Odd indeed and one I hope to get to the bottom of shortly.Thanks Pablo!

    This project is not 'freeware'. Make sure you understand your legal responsibilities to the GPLv3 license before downloading this project. It will be enforced.

    Getting levelHead

    Code and assets are provided under two differing licenses: the code is governed by the GPLv3 and the art is covered by the GPLv3 compatible CC-BY_SA 3.0. For the rationale as to why I chose this configuration, please read the comments in the top of the levelHead.cpp file itself. Both art and code are available in a subversion repository, aquired with the following command:

    svn co http://www.inclusiva-net.es/svn/levelhead/trunk

    Hardware dependencies

    Cameras: levelHead now uses the Logitech QuickCam Pro 9000 camera, a really good USB2 camera. The Sony Eyetoy should still work fine, but you'll need to take care to choose the right capture driver when compiling ARToolkit (see below). My advice for those with neither camera would be to check this list of Linux UVC compatible cameras and give it a go. Most of the Logitech Quickcam range are supported by this driver on Linux and are good cameras. For an optimal setup you'll need to configure the camera you have to accomodate lens distortion and focal depth. I've provided the camera_para.dat's for both the Quickcam Pro 9000 and the EyeToy in the bin/Data. To configure other cameras see this page.

    Other: This project has been developed primarily on an NVIDIA FX 570M with the proprietary driver. The BETA was mostly developed on an ATI 9700 card running the proprietary fglrx driver. If you run hardware with an open driver and levelHead is still performant, I'd like very much to hear from you..

    Tracking is done on the CPU and so you will notice a difference with faster CPUs. Not suprisingly the biggest bottleneck is video frame-rate however: with a higher frame-rate there's simply more opportunity for the tracker to find its targets.

    Compilation steps:

    1. Install GStreamer

    2. Compile ARToolkit.

  • If using a Linux UVC supported camera, when running ./Configure be sure to choose 'GStreamer' as the video capture driver.
  • If using the Sony Eyetoy, when running ./Configure be sure to choose 'Video4Linux' as the video capture driver (don't choose the option Video4Linux Sony Eyetoy). You will probably need to also comment out the ARTOOLKIT_CONFIG environment variable in /path/to/levelHead/trunk/bin/run.sh
  • There is no need to install ARToolkit system-wide. Just run make after this point.

    • 3. Compile ARTookitPlus

  • Follow the steps in the INSTALL file of ARToolkitPlus

    • 4. Install other dependencies above.

  • NOTE: I use uvcdynctrl from Logitech's libwebcam in /path/to/levelHead/trunk/bin/start_levelHead.sh to focus the camera. This greatly improves performance of the tracking so it's reccommended you install it (system wide) too.

    5. Compile levelHead.

  • cd /path/to/levelHead/trunk/src/levelHead/bin
  • edit the path_config.sh to match the paths you have for ARToolkit and ARToolkitPlus.
  • Edit the path in /path/to/levelHead/trunk/bin/build.sh to point to ARToolkit
  • sh build.sh to build

    • 6. Make the cubes.

  • See the file /path/to/levelHead/trunk/bin/Data/images for details about printing and making the cubes.


    • 7. Lighting.

  • Like any computer-vision related project that works in the visible spectrun, lighting is important. levelHead works well with good ambient lighting, however all that really matters is that the face of the cube facing the camera is lit at all times. The light shouldn't be too bright and nor should it be coming from one direction only as a shadow will be cast over the front face when the cube is turned left and right. Here's an image taken by an independent photographer that describes pretty much the ideal lighting conditions for play. Note the direction of the shadows cast. Two soft spotlights (40W) from in front and above the cubes, around 3m either side of the plinth and pointing toward the side of the cube facing the camera, produced this lighting.

    Running levelHead

  • Plug in the camera
  • Edit the file run.sh to suit your display context.
  • sh start_levelHead.sh


    • Any questions, join #levelhead on irc.freenode.net after the 10th of August and I'll see what I can do. I'll be travelling up until this time.

    Good luck!