User Tools

Site Tools


Calibration Instructions for a Minicave

These are draft instructions for calibrating a single-screen “cave” with NaturalPoint 3-camera tracking system. The system we're using has a Windows PC running NaturalPoint Optical Tracker and a Linux box running VRUI on a 3D TV. The two computers talk over ethernet. The VRDevices.cfg file has the name of the Windows PC, etc. You need to start the VRDevicesDaemon on the Linux box with the proper configuration file (see starting a vr device).

Here is a summary of cfg changes from fresh install.

These instructions assume you've done a crude calibration for the tracking subsystem. The process described here takes 3-4 hours if you are experienced and everything is working.

1. Get whole system running

Make sure all software is running on all essential computers and talking to the proper hardware. This is not essential, but it is good to validate all hardware is working, software is communicating, and cameras and 3D TV in correct and final physical installation before starting the calibration. See X Windows Configuration.

2. Mark location of 3D TV

Draw lines on the table in case the TV must be moved or gets bumped. Then you can realign the TV without having to recalibrate the entire system.

3. Calibrate optical tracker

Information here does not include detailed steps on how to calibrate the NaturalPoint optical tracker. Refer to NaturalPoint documentation. <add pdf link here>

  1. Play with optical tracker beforehand to understand it and do a crude calibration.
  2. Start up Point Cloud Calibration tool on OptiTrack machine.
  3. Click “Advanced” to see Illumination, Exposure, and Threshold. You set these in that order.
    • Illumination set lower than “15” (max) means that the cameras do *not* strobe, but give constant illumination. (This is desirable.)
    • Settings are not super sensitive, and only Illumination is important: First time: Illumination = 5, Exposure = 20, and Threshold = 115. Second time: Illumination = 8, Exposure = 87, and Threshold = 140
    • Note: There is still active-stereo-glasses sync IR interference with cameras. So may want to reduce Illumination even further, keeping in mind the possible loss of tracking signal.
  4. Start calibration & move reflectors around the space.
  5. Complete calibration, which may take computational time (e.g. ~10 minutes). If an error message comes up, redo the calibration.
  6. Set the ground plane. The orientation doesn't matter, but you need to make sure that the calibration tool shows the grid parallel to the ground plane and the 3 cameras overhead. If it is not stable or the geometry is bad, set the ground plane again.
  7. Store calibration file (*.cal).

4. Set up TotalStation

Assemble and mount the TotalStation laser range-finder. This is a $4-10K piece of precision equipment, often available in Geology Departments. It is possible to do part of this calibration with a tape measure, but it isn't easy or accurate.

  1. Set up the tripod. Put tape under each foot to keep the tripod stable and protect the floor.
  2. Mount the TotalStation on tripod, at a height appropriate to screen and capture volume. (About 5 ft in our case.)
  3. Connect TotalStation to laptop using special cable (in “tackle box”) and serial (DB-9)-to-usb adapter.
  4. Level the TotalStation. It will not operate unless you level it first. (Leveling is not required for calibration data, though.) Printed instructions are in the tool box. GET instruction document from Eric and connect here.

5. Run Calibration Programs

Make sure you have Vrui's four calibration programs (in …Vrui/Calibration), on the computer attached to the TotalStation as well as the computer running the 3D TV. They should be packaged with newer versions of Vrui. Instructions are online at These programs are now part of Vrui (065 and above) distribution.

  • XBackground produces a reference grid on the 3D TV screen.
  • MeasureEnvironment collects data from TotalStation on (a) ground plane (floor), (b) 3D TV screen plane and keystoning, and © three horizontal capture volume planes. It outputs a TotalStation survey file.
  • ScreenCalibrator takes the data (Total Station survey file) and OptiTrack calibration file (*.csv) and produces Vrui configuration command lines.
  • AlignTrackingMarkers calibrates tracked objects (e.g., head and Wiimote antlers) and sets their orientation using data from NaturalPoint object tracking program (*.rdef, an XML file). It outputs VRDevices.cfg command lines.

Run XBackground in a terminal on the Linux box running the 3D TV and send grid to the 3D TV:

./XBackground -type 2 -display :0.1

A white-line grid should show up on the 3D TV screen. 300 pixels is the default square size.

Run MeasureEnvironment on the machine connected to the TotalStation

./MeasureEnvironment /dev/ttyUSB

Brings up a window on the machine connected to the TotalStation. This will produce a TotalStation survey file (“MeasuredPoint.csv”). MeasureEnvironment has three toggle buttons: Measure Floor, Measure Screen, Measure Balls.

  1. Start measurements
    1. Choose “Measure Floor”
      1. Start shooting by telling TotalStation to acquire data
      2. Take at least 3 random points on the floor. 6 is a good number, spread out under the work volume.
      3. Points show up in Vrui window
    2. Choose “Measure Screen” to measure screen plane and keystoning
      1. Shoot the grid points on the 3D TV in reading order. There is no “undo”.
      • The keystoning of the 3D TV interferes with the keystoning in Vrui. Ideally, one could turn it off.
    3. Choose “Measure Balls” in main Vrui Window. During this step, you locate the ball with both the TotalStation and the optical tracking system. (See hints below.)
      1. Place a small reflecting ball on a tripod in the future work space. Move to random locations during the next set of measurements, covering the width, height, and depth of the work space.
      2. On optical tracking computer, go to “Calibration Results” and go to sample data capture panel at bottom. The round red button is to record, and the black square button is to stop. Click on and off the recording quickly (~50 samples).
      3. Shoot the center of the ball with the TotalStation.
      4. Repeat ~18 times, with non planar reflecting ball locations
      5. “Save” the data in the optical tracking program to the Desktop (PlaneData*.csv).
      • You must record the location of the ball with both systems each time. If you miss one, you start over or edit the file layer.

Measure Balls Hints:

  • This is best as a two-person operation: One taking data via TotalStation. One moving the single-reflective-ball tripod to various locations.
  • Using double-sided tape mount a reflective ball on a second tripod.
  • Each measurement consists of two items: A location measurement from the TotalStation *and* a sample of the same location as seen by the optical tracking program.
  • The measurements must be coordinated between both the TotalStation and the optical tracking. (The Vrui program which uses this data is not bothered by too many optical tracking samples, but the *order* of the samples (first plane, first location; first plane, second location; …) must be the same.

6. Produce Configuration File Data

The following steps produce the VRDevices.cfg and Vrui.cfg configuration file snippets. The information is output to the monitor and needs to be copied into the configuration files.

  1. Transfer PlaneData*.csv to the laptop, which is running MeasureEnvironment. (We used a USB stick.)
  2. Using ScreenCalibrator read in the TotalStation survey data file (“MeasuredPoint.csv”) and the optical tracking data (PlaneData*.csv).
ScreenCalibrator -screensize 1920 1080 -squaresize 300 -meterstoinches MeasuredPoint.csv PlaneDataXXX.csv
  • screensize is the pixel dimensions of the 3D TV
  • squaresize is the pixel size of the grid on the TV. The default is 300 pixels, but it can be set in XBackground. These values must agree.
  • The default units for Vrui are inches, so meterstoinches tells it the units are in meters.

ScreenCalibrator will show a Vrui screen that includes the measured ground points, screen points, and capture volume points. In the Vrui window, you can get a sense of the quality by looking at the points. The screen points should be planar and blue and green squares show the screen plane for keystone correction and non-correction. The yellow and purple points reflect the optical tracking system and TotalStation points for the capture volume. You can use the MeasurementTool to measure the difference if you'd like.

The output from the ScreenCalibrator is a lot of debugging information. The last two sections have headings “Configuration Settings for Screen”, which you need to copy and paste into Vrui.cfg, and “Configuration Settings for Tracking Calibrator”, which you need to copy and paste into VRDevices.cfg

Example debugging information:

Read 16 ball points from Optitrack sample file

Read 16 ball points from TotalStation survey file

Projective transformation fitting final distance: 5.21709e-05

Projective transformation matrix:

{{1.39562, 0.000824092, 0, -0.696758}, {9.70548e-05, -0.0172738, 0, 0.00858753}, {0.00603279, 0.790516, 0.860841, 0.887623}, {0.00813294, 0.00541506, 0, 1}}

Screen transformation fitting final distance: 8.91217e-05

Optimal screen size: 1.38495, 0.776524

Optimal screen origin: (-0.693183, 0.00865426, 0.890582)

Optimal horizontal screen axis: (0.999996, -3.77073e-05, -0.00270194)

Optimal vertical screen axis: (0.00270044, -0.0221164, 0.999752)

Text to paste into Vrui.cfg:

Configuration settings for screen:

origin (-27.2907, 0.340719, 35.0623)

horizontalAxis (0.999996, -3.77073e-05, -0.00270194)

width 54.5256

verticalAxis (0.00270044, -0.0221164, 0.999752)

height 30.5718

offAxis true

homography ( ( 27.3982, 0.0503181, 0.00403911 ), \

             ( 0.0480105, 15.3663, 0.00268931 ), \

             ( 27.3067, 15.3006, 1 ) )

For example, this code snipped goes in in Vrui.cfg:

section Vrui
   section minicave  <<< This name will vary depending on installation
      section Screen  <<< This name will vary depending on installation & Vrui version
         origin (-27.2907, 0.340719, 35.0623)
         horizontalAxis (0.999996, -3.77073e-05, -0.00270194)
         width 54.5256
         verticalAxis (0.00270044, -0.0221164, 0.999752)
         height 30.5718
         offAxis true
         homography ( ( 27.3982, 0.0503181, 0.00403911 ), \
                    ( 0.0480105, 15.3663, 0.00268931 ), \
                    ( 27.3067, 15.3006, 1 ) )

Also add approximate dimensions of work space to Vrui.cfg:

Section Vrui
  section minicave
    displayCenter (x, y, z) <<< 0, 0, z = height of tv center measured from floor, 50 inches
    displaySize (~radius of screen) <<< 30 inches

The following snippet goes into VRDevices.cfg, which VRDevicesDaemon uses to transform the incoming coordinates from the optical tracker into Vrui coordinates and Vrui coordinate frame of the correct (right) handedness. (Optical tracker generates lefthanded coordinate system data.) Text to paste into VRDevice.cfg:

Configuration Settings for Tracking Calibrator:

Final distance: 0.00236769

Tracking system calibration transformation: {(0.111915, -0.4617, 0.0370864), {(-0.0044532, -0.711874, -0.702293), 3.10677}}

Configuration settings for tracking calibrator:

transformation translate (4.40609, -18.1772, 1.46009) \

               * scale 39.3701 \

               * rotate (-0.0044532, -0.711874, -0.702293), 178.005

For example, in VRDevices.cfg:

section "minicave"
   section DeviceManager
      section VRPN1  <<< port to communicate to optical tracking computer
         section Calibrator
            transformation translate (4.40609, -18.1772, 1.46009) \
               * scale 39.3701 \
               * rotate (-0.0044532, -0.711874, -0.702293), 178.005

7. Tracked object calibration

<Jim - I am confused here, please fix>

  • A. On optical tracking computer, start up the program called Rigid Body Tool.
  • B. Go through the steps in this program, eventually defining “Head” and “Wiimote” tracked objects.
  • C. Store tracked objects data file (*.rdef).
  • In the optical tracking program (up and running and calibrated, already), load in the saved object file (*.rdef). (See How to Use New Calibration above.)
  • On the appropriate panel “Save” the object configuration data.

8. Calibrate tracked objects

  • We have two tracked objects: “Head” and “Wiimote”. These are the names entered in the optical tracking program previously.
  • Transfer the *.rdef XML file to the Linux box. (We used a USB stick.)
  • Run AlignTrackingMarkers on this file. (See code below.)
  • AlignTrackingMarkers will show you (in 3D) the reflective balls for each object, in turn.
  • For each object, identify the x axis. Link, via program 3D interaction, the two balls lying on the x-axis. Identify and fix the y-axis (or z-axis) similarly. Third axis is implied.
  • With this complete, save the results to a file, which will contain a Vrui configuration file snippet.
  • Insert this snippet into your VRDevices.cfg.

For example,

~/Projects/VRDeviceDaemon> AlignTrackingMarkers *.rdef -inches Head -rootSection Desktop 

Head = name from Optictrack side; -rootSection runs it on your desktop Manipulate balls on screen to identify which ball on the screen corresponds to which ball on the object. From tool selection menu, select MarkerSelector can draw lines between balls to make axis X axis = horizontal from left to right draws gray cylinder.

main menu ⇒ align x axis, should be parallel on screen establish a y axis or z axis, y straigth front, z up draw from top ball to x axis, from main menu, select -z axis if drew downward set the origin (but no marker where origin is, so eyeball it.) the origin should be obvious on your markers; measure the eye locations from that origin (later)

main menu ⇒ move origin, use marker selector tool to pull origin along x axis use measurement tool to measure distance from marker to origin, measure physically on markers, adjust until you get what you want. Exit program.


Final transformation: translate (0.23401950674106, -0.2471638399121, 0.23765573365417) * rotate (-0.58525441639481, 0.57715261691519, 0.56953676341243), 117.28882108516

Repeat for Wiimote:

~/Projects/VRDeviceDaemon> AlignTrackingMarkers *.rdef -inches Wiimote

Identify balls, draw and label axes, set origin Y-axis parallel to length of the wiimote and into the screen (selection ray comes out in the y direction)

Example output:

Final transformation: translate (-1.1959842519685, -0.4651968503937, -0.12188976377953) * rotate (-0.6049875046113, 0.57533916651842, 0.55043161494783), 111.8254205591

Then in VRDevices.cfg:

section "minicave"
   section DeviceManager
      section VRPN1
         trackerPostTransformation0 translate (0.23401950674106, -0.2471638399121, 0.23765573365417) \
            (-0.58525441639481, 0.57715261691519, 0.56953676341243), 117.28882108516
         trackerPostTransformation1 translate (-1.1959842519685, -0.4651968503937, -0.12188976377953) \
            * rotate (-0.6049875046113, 0.57533916651842, 0.55043161494783), 111.8254205591

Note that “Head” is associated with trackerPostTransformation0; Wiimote with trackerPostTransformation1.

9. Set Eye Positions

In Vrui.cfg, you need to adjust monoscopic- and stereoscopic-mode eye-location offsets—downward and backward offsets from the glass's antler location. This makes a noticeable difference and, in principle, would be set for each user.

Eye positions - measure where your eyes are in relationship to the origin on the glasses. Mono is between the two eyes (z = -1.75 inch (down), y = -0.5 inch (back), x = 0) Th half average eye distance is 1.25 inches, so adjust x for the right and left eye positions.

Section Vrui
  Section Viewer
    monoEyePosition (0, -0.5, -1.75)
    rightEyePosition (1.25, -0.5, -1.75)
    leftEyePosition (-1.25, -0.5, -1.75)
    headLightPosition (0, -0.5, -1.75)

10. Test

Test all Vrui application functionality: head tracking, wiimote tracking, wiimote buttons. <add explicit things to test>

Files to save for backup:

On Linux computer:

  1. Vrui.cfg
  2. VRDevices.cfg

On OptiTrack computer:

  2. Head *.rdef file
  3. Wiimote *.rdef file
keckcaves/tracking.txt · Last modified: 2010/03/12 22:10 by sumner