Setting up Vrui for Oculus Rift

As promised, here is a detailed guide to get Vrui version 3 running with an Oculus Rift (and optionally a Razer Hydra, since that seems to be the 6-DOF input device du jour).

Step 1: System Preparation

If you are already running Linux, good for you. Skip the next paragraph.

If you don’t have Linux yet, go and grab it. I personally prefer Fedora, but it’s generally agreed[citation needed] that Ubuntu is the easiest to install for new Linux users, so let’s go with that. The Ubuntu installer makes it quite easy to install alongside an existing Windows OS on your system. Don’t bother installing Linux inside a virtual machine, though: that way Vrui won’t get access to your high-powered graphics cards, and performance will be abysmal. It won’t be able to talk to your Rift, either.

One of the first things to do after a fresh Linux install is to install the vendor-supplied drivers for your graphics card (if you don’t have a discrete Nvidia or ATI/AMD graphics card, go buy a GeForce!). Installing binary drivers is much easier these days. Here are instructions for Nvidia and ATI/AMD cards. If you happen to be on Fedora, enable the rpmfusion repositories and get the appropriate driver packages from there.

Finally, you need to download Vrui’s required and optional software dependencies. Since there are scripts for that, let’s talk about dependencies in…

Step 2: Installing Vrui

This is the easy part. There are automatic installation scripts for Fedora and Ubuntu on the Vrui download page. Just download and run the appropriate script as explained on the download page. If you don’t trust my script, do it manually via the “Quick Installation Guide.” If you do run the script, it will ask you for your password early on, to install the dependency packages. It’s OK; look at the script source if you’re in doubt.

The script will download the sources into a src/Vrui-3.0-001 directory directly underneath your home directory, and install Vrui in a Vrui-3.0 directory directly underneath your home directory. That’s fine for now; if you want to install Vrui elsewhere later, you’ll have to run the build process manually and supply an installation directory.

If the script completes, it will immediately start the first Vrui example application, which is a simple virtual globe (see Figure 1).

Figure 1: The Vrui application that pops up automatically after successful installation. Note: the packaged globe texture is uglier due to licensing reasons.

What you’re looking at is Vrui in desktop mode. Use the left mouse button to rotate the globe, the “z” key to pan it in the window plane, and the mouse wheel to zoom. The right mouse button brings up a pop-up menu to change program settings. The desktop user interface is explained in detail in the HTML documentation packaged with the Vrui source, or installed in ~/Vrui-3.0/share/doc, or on the Vrui web site.

Step 3: Connecting and Enabling Your Oculus Rift

First, connect your Rift’s control box to a USB port on the PC, and to a DVI or HDMI port on your graphics card. Next, activate the Rift’s screen. How to do that depends on the brand of your graphics card; here’s how to do it for an Nvidia card using the vendor-supplied drivers. Start the nvidia-settings utility, and go to the “X Server Display Configuration” tab. Then press the “Detect Displays” button, and the “Layout” pane should now show your main display, and the Rift’s display somewhere next to it (labeled “OVR Rift DK” or similar). Click on the Rift’s display, and select “TwinView” in the “Configuration” drop-down box. Drag the Rift’s display to where you want it. You can mirror the displays, but I strongly advise against it. I suggest placing the Rift’s display immediately to the right of the main display. Check if the Rift’s resolution is set to 1280×800; if it’s not, select 1280×800 from the “Resolution” drop-down box. Finally, click on your main display again, check the “Make this the primary display for the X screen” button, and press the “Apply” button. This will momentarily blank your screen, and should then turn on the Rift’s screen, which should at this point show the desktop’s background image. See Figure 2 for how it looks like on my computer. Take note of the “Position: Absolute: +1920+0” field in the lower right of Figure 2. You’ll need to enter those numbers into a Vrui configuration file later.

Figure 2: The nvidia-settings utility showing the position of an Oculus Rift next to the main display.

Before moving on, you’ll have to fix a permission issue. Under Linux, only the superuser can talk directly to USB devices connected to the computer. Since you won’t want to run all Vrui applications as root, you need to create a special device rule file that will open select devices (your Rift, and your Hydra while you’re at it) for any user. Fortunately, the Vrui package already includes such a rule file. Just copy it to the proper location, and re-plug your USB devices:

> sudo cp ./src/Vrui-3.0-001/Share/69-3d-inputdevices-acl.rules /etc/udev/rules.d/

The ./src/Vrui-3.0-001 path is where the automatic installation script put the sources. If you installed manually, use the location you used instead. Enter your password when prompted to be able to copy the rule file to the /etc/udev/rules.d system directory.

Step 4: Calibrating Your Oculus Rift

Before you can meaningfully use your Rift with Vrui, you need to run a few calibration steps. In detail, you need to extract information about the Rift’s internal geometry from its firmware, you need to run a hard- and soft-iron calibration on its three-axis magnetometer, and you need to determine the forward direction of your desktop with respect to magnetic north. No worries, there’s a utility for all that. Open a terminal window, and run the calibration utility like this:

> ./Vrui-3.0/bin/OculusCalibrator

This will open another Vrui application (still in desktop mode), showing a global coordinate frame made of three arrows (red for X, green for Y, blue for Z) and a local coordinate frame representing your Rift’s current orientation (see Figure 3). Don’t worry if the local frame doesn’t properly follow your actual Rift yet and if the magnetic field points the wrong way — you haven’t calibrated yet!

Figure 3: Initial display of OculusCalibrator utility. The red/green/blue arrows represent the X, Y, and Z axes of the global and local coordinate systems, respectively. The yellow arrow is the direction of gravity, and the purple arrow is the direction of the local magnetic field (which won’t be correct until calibration is done).

Immediately after startup, the OculusCalibrator utility will print a bunch of configuration data, looking something like this:

Display information: 
  Distortion type             : 1
  Screen resolution           : 1280 x 800
  Physical screen size        : 5.89606 x 3.68504
  Vertical screen center      : 1.84252
  Lens center distance        : 2.5
  Screen/eye distance         : 1.96063, 1.96063
  Lens correction coefficients: 1, 0.22, 0.24, 0, 0, 0, 

Configuration file settings to paste into etc/OculusRift.cfg:

  section LeftScreen
    name LeftScreen
    deviceMounted true
    deviceName OculusRift
    origin (-2.94803, 1.96063, -1.84252)
    horizontalAxis (1.0, 0.0, 0.0)
    width 2.94803
    verticalAxis (0.0, 0.0, 1.0)
    height 3.68504

  section RightScreen
    name RightScreen
    deviceMounted true
    deviceName OculusRift
    origin (0, 1.96063, -1.84252)
    horizontalAxis (1.0, 0.0, 0.0)
    width 2.94803
    verticalAxis (0.0, 0.0, 1.0)
    height 3.68504

  section HMDWindow
    windowPos (0, 0), (1280, 800)
    decorate false
    windowType SplitViewportStereo
    leftViewportPos (0, 0), (640, 800)
    rightViewportPos (640, 0), (640, 800)
    leftScreenName LeftScreen
    rightScreenName RightScreen
    viewerName HMDViewer
    lensCorrection true
    lcPoly (1, 0.22, 0.24)
    leftLcCenter (0.575988, 0.5)
    rightLcCenter (0.424012, 0.5)
    mouseScreenName MouseScreen

As the printout says, you will later paste these settings into ~/Vrui-3.0/etc/OculusRift.cfg. For now, you will do accelerometer and magnetometer calibration. For this, you’ll need to find a stable and horizontal surface onto which to place your Rift. Also, you’ll need to create some tools inside the OculusCalibrator utility.

First, press and hold the “1” key. This will pop up a “Tool Selection Menu.” While holding the “1” key, move the mouse (but don’t press any mouse buttons) to highlight the “Show Raw Measurements” item, then release the “1” key to select it. If you now press the “1” key again, the utility will start visualizing raw accelerometer and magnetometer data. There will be a jittery red dot somewhere around the global coordinate frame, and a green dot somewhere close to its origin (might be obscured by the arrows or hard to see). The red dot is the current linear acceleration vector indicating the direction of gravity. The green dot is the current magnetic flux vector, pointing to magnetic north. Pressing “1” again will hide the raw measurements, and so forth.

Second, press and hold the “2” key, and select a “Start/Stop Recording” tool from the tool selection menu just as above. Whenever you press the “2” key again (don’t do it now!), it will record all accelerometer and magnetometer readings until you release the key again. This is how you will capture about a dozen measurement points for various orientations of your rift. Before doing that, though, press the “3” key, and select a “Show Tracking” tool. Then press “3” to hide the coordinate arrows, and “1” again to show raw measurements. Now you should see the red and green dots.

To collect calibration data, you have to place your Rift onto a stable surface (like your desk) in a variety of orientations. Start by placing the Rift upright, i.e., nose piece down, onto the surface, pointing in the “preferred forward direction,” e.g., facing your monitor. Then let go of it, and press and hold the “2” key for about one second. This will collect a “tie point” of several hundred measurement points, which will be shown as a small cloud. Be careful not to touch or move the Rift, or bump the desk, or stomp around, while collecting measurements; the accelerometers in particular are very sensitive. The result of capturing one tie point should be a small cloud of points with no outliers.

After this first step, rotate your Rift by 90° around the vertical and repeat. Do that two more times, and now you have four tie points or small clouds of red points forming more or less a square. Now put the Rift back facing your monitor, and rotate it upwards 90° so that the front place faces up. After collecting this tie point, lay it down on the front plate to collect the sixth one. You should now have six points roughly forming the corners of an octahedron.

Figure 4: Two steps in the accelerometer / magnetometer calibration procedure. Left: the first six calibration tie points (red: accelerometer, green: magnetometer) form a rough octahedron. Right: the full set of tie points.

Six tie points are not enough for calibration; you need at least ten (hard- and soft-iron calibration have ten free parameters). By observing the real-time measurement point in the display, rotate your Rift in 45° increments to fill in the biggest gaps between the existing tie points (see Figure 4). You might need to use some object to prop up the rift in a particular orientation. After you have collected ten or ideally more tie points, exit the utility by pressing the “Esc” key, or closing the window. This will automatically run the calibration procedure, and print out the results. It will also create a file “OculusRiftCalibration.dat” in the current directory containing the results in binary form. Here’s typical output from the calibration:

Accelerometer calibration:
/ 0.558433,  0.646509, -0.519787\
|-0.653681,  0.728727,  0.204105|
\ 0.510738,  0.225796,  0.829556/


Centroid: 433.661, 206.628, 213.666
Radii: 98418.2, 97662.6, 98118.5
Average radius: 98066
Calibration residual: 464.974
accelCorrection ((1.00047, 0.00330878, -0.000186873),
                 (0.00330878, 1.00064, 0.00178359),
                 (-0.000186873, 0.00178359, 0.998908),
                 (-434.506, -208.577, -213.72))

Magnetometer calibration:
/ 0.986811, -0.144338, -0.073279\
| 0.159605,  0.943102,  0.291693|
\ 0.027007, -0.299542,  0.953701/

/ 0.000000\
| 0.000000|
\ 0.000000/

Centroid: -861.914, 3745.42, 7969.13
Radii: 4967.61, 5191.87, 5806.38
Average radius: 5310.38
Calibration residual: 24.5314
magCorrection ((1.06721, 0.00958621, 0.00879575),
               (0.00958621, 1.01479, -0.0299147),
               (0.00879575, -0.0299147, 0.924402),
               (813.843, -3554.17, -7247.05))

As indicated, you will later paste the accelCorrection and magCorrection lines (line-wrapped here to fit onto the screen) into Vrui’s device driver configuration file, ~/Vrui-3.0/etc/VRDevices.cfg. But for now, simply start OculusCalibrator again. It will automatically read the binary calibration file it just created, and now the magnetometer readings should make sense (see Figure 5). If you place the Rift such that its internal X axis (pointing level right when wearing it) points directly to magnetic north, you’ll see that the smaller red arrow indicating its orientation is now parallel to the larger red arrow representing the global X axis. As you rotate the Rift in your hands, the orientation indicated on the screen should correspond 1:1 to what you’re doing.

Figure 5: Orientation tracking on OculusCalibrator after initial calibration. The local X axis is aligned with the global X axis because the Rift is rotated to be parallel to magnetic north. The purple arrow points north and down according to the local degree of latitude, and the yellow arrow is parallel to the local Y axis because the Rift is held level.

If you feel adventurous, you can even enable inertial positional tracking by binding a key to the “Lock Position” tool. Pressing that key once will place the local coordinate frame at the Rift’s currently estimated position, and it will follow the Rift’s motion in space. This will work for a (very) short while, but then drift will accumulate and the Rift will zoom off into space. Bind a “Reset Position” tool to a key to get it back to the origin. As you can see, pure inertial tracking does not work.

As the last step, place the Rift onto your desk with the nose piece down, and the front plate facing in what you want to be the “forward” direction, e.g., directly towards your monitor. Then bind a “Print Yaw Angle” to a key, press the key, and read off the yaw correction transformation that is printed out. You will later (as in right now) paste this into ~/Vrui-3.0/etc/VRDevices.cfg.

Step 5: Making Calibration Data Permanent

This is the part where you enter the various bits of calibration data you just collected into the appropriate places in Vrui’s configuration files. Start by opening ~/Vrui-3.0/etc/VRDevices.cfg using a text editor (use gedit unless you already have a favorite):

> gedit ./Vrui-3.0/etc/VRDevices.cfg

Towards the top of this file are a number of commented-out (prefixed by a “#”) lines defining what device driver modules to load. Find the line saying “deviceNames (OculusRift)” and remove the hash mark to activate it.

Then find “section OculusRift,” and inside that, the “accelCorrection” and “magCorrection” settings. They currently have example values (from my Rift, actually), so you want to replace them with yours. If you scroll up in the terminal window, the output from calibration should still be there. Highlight the settings (including all parentheses) with the mouse, and select “Copy” from the terminal’s pop-up menu. Then highlight the same text in the text editor, and press Ctrl+V to paste. This should replace the previous settings with your new ones. Ensure that all parentheses are properly balanced. There should be twelve numbers, in four lists of three each, per setting. You can use backslashes to break long settings over multiple lines. My values look like this:

accelCorrection ((1.00063, 0.00117503, -0.000188967), \
                 (0.00117503, 1.00053, 0.00181332), \
                 (-0.000188967, 0.00181332, 0.99884), \
                 (-488.375, -133.615, -171.469))
magCorrection ((1.06636, 0.016573, 0.00324851), \
               (0.016573, 1.01692, -0.0276182), \
               (0.00324851, -0.0276182, 0.923162), \
               (814.3, -3547.97, -7272.02))

Now go down a bit further to “section Calibrator,” and find the “transformation” setting. Here is its current value:

transformation translate (0.0, -24.0, 50.0) \
               * rotateAround (0.0, -3.0, -6.0), (0.0, 0.0, 1.0), -22.0 \
               * rotate (1.0, 0.0, 0.0), 90.0

This is the transformation that moves the Rift from its internal coordinate system (X right, Y up, Z towards the face) to Vrui’s coordinate system (X right, Y forward, Z up), and also to the final 3D viewing position (0.0, -24.0, 50.0) corresponding to a viewer sitting at a desk. What you want to change here is the middle line (“rotateAround …”). The last number in that line is the rotation angle around the vertical to align magnetic north with your desk. Replace the -22.0 (my desk is oriented 22° westward) with whatever angle was printed out for the yaw correction transformation. Now save and close VRDevices.cfg.

Next, open the configuration file for the Oculus Rift:

> gedit ./Vrui-3.0/etc/OculusRift.cfg

In this file, find and patch the “LeftScreen,” “RightScreen,” and “HMDWindow” sections with the calibration data printed out a few steps ago. Most of the settings should already match (unless your Rift is a different model than mine), but it’s best to make sure.

Finally, find the “windowPos” setting in the “HMDWindow” section. The first two numbers are the screen position of the Rift’s display. Here, enter the numbers you saw earlier inside nvidia-settings to automatically place the display window onto the Rift’s screen when a Vrui application starts up. Save and close OculusRift.cfg, and congratulations, you’re done!

Step 6: Run Vrui Applications in Oculus Rift Mode

In Vrui, low-level interaction with most input devices is handled via the stand-alone device driver, VRDeviceDaemon. Open another terminal and run it:

> ./Vrui-3.0/bin/VRDeviceDaemon -rootSection localhost

This will print some status information, and end with “VRDeviceServer: Waiting for client connection.” You must leave the terminal window open, or the driver will be shut down, but you can minimize the window to hide it. The idea is that the driver is left running for the entire time you use your Rift, no matter how often you start/stop applications.

Now, from the first terminal window, run the ShowEarthModel application again, but this time in Rift mode:

> ./Vrui-3.0/bin/ShowEarthModel -mergeConfig OculusRift.cfg

The path, ./Vrui-3.0, is where the installation scripts put the example programs. If you installed manually, yours might be in a different location, but then you should already know that. 😉

The -mergeConfig OculusRift.cfg at the end of the command line is Vrui’s way of enabling a non-default mode. It overrides default configuration settings with those making an Oculus Rift work. You can make Rift mode the default later, if you want to.

Figure 6: The ShowEarthModel application in Oculus Rift mode.

Voila! As soon as you hit enter on the command line, the virtual globe will appear in your Rift, in glorious head-tracked 3D (see Figure 6). You will still be using the mouse interface at this point, so the left button will still rotate, Z will still pan, etc. Once you’re happy with everything, it’s time to…

Step 7: Add a Razer Hydra 6-DOF Input Device

Ideally, adding a 6-DOF input device to a display environment takes some calibration, but let’s keep simpler for starters. First, shut down the already-running VRDeviceDaemon by bringing up its terminal window and pressing Ctrl+C. It will print some final status updates, and then exit. Now edit ~/Vrui-3.0/etc/VRDevices.cfg again:

> gedit ./Vrui-3.0/etc/VRDevices.cfg

This time, comment out the line “deviceNames (OculusRift)” and uncomment the line “deviceNames (OculusRift, RazerHydra).” This will enable both devices at the same time. Then save and exit the file, and restart the device driver in the terminal:

> ./Vrui-3.0/bin/VRDeviceDaemon -rootSection localhost

This time it will take longer to start, because it will have to switch the Razer Hydra into tracking mode first, and that can take several seconds. But in the end, it will display “VRDeviceServer: Waiting for client connection” again.

Now place the Hydra’s base station onto your desk, about two feet forward from your typical sitting position (this should put it pretty much right in front of your monitor). Make sure to rotate the base station such that the two cables come out towards the back, away from you. This, together with the calibration transformation in ~/Vrui-3.0/etc/VRDevices.cfg, will roughly align the Hydra and the Rift into the same coordinate system, which is essential.

Finally, run the ShowEarthModel application again, using both the Rift and Hydra:

> ./Vrui-3.0/bin/ShowEarthModel -mergeConfig OculusRift.cfg -mergeConfig RazerHydra.cfg

Now you can use the Hydra’s handles to interact with the 3D environment. By pressing the top right button on the left handle (“4”) or the top left button on the right handle (“3”) you can pick up space and move it around as if it were attached to your hands. Ideally, move the handle first until the grey cone indicating its position touches the object you want to move, then press the button. If you press both buttons at the same time, you can scale the environment by pulling your hands apart or pushing them together. The lower right button on the left handle (“2”) or the lower left button on the right handle (“1”) will pop up a menu when pressed, and they are also used to interact with dialogs already in the environment. They joysticks on either handle can be used to fly through the environment. But keep in mind that they move quite fast, so it’s best to make the 3D environment large first before trying the joysticks.

Step 8: Odds and Ends, Going Further

I recommend that you add ~/Vrui-3.0/bin to your executable search path, so you can just start programs by their names instead of having to type the ./Vrui-3.0/bin bit all the time. Open your bash (terminal shell) start-up script in a text editor:

> gedit .bashrc

and add, at the very bottom:

export PATH=$PATH:$HOME/Vrui-3.0/bin

then save and exit. Close and re-open your terminal window, or simply reload the script by

> . .bashrc

(both periods are important), and the shell will know about Vrui.

One “oddity” about the default Rift mode as described here is that the 3D environment is only shown to the person wearing the Rift. This is normally ideal, but not so great when demonstrating the Rift to someone else. It will be hard to get things back on track should they get lost. This is very easy to address. Display mirroring is a poor solution; a better approach is to let Vrui render two independent views at the same time, one in stereo for the Rift, and one in mono for everybody else. Create a new configuration file fragment using gedit:

> gedit ./Vrui-3.0/etc/Control.cfg

and paste in the following text:

section Vrui
    section Desktop
        screenNames += (ControlScreen)
        windowNames += (ControlWindow)

        section ControlScreen
            name ControlScreen
            deviceMounted true
            deviceName OculusRift
            origin (-40.0, 24.0, -25.0)
            horizontalAxis (1.0, 0.0, 0.0)
            width 80.0
            verticalAxis (0.0, 0.0, 1.0)
            height 50.0

        section ControlWindow
            windowPos (100, 100), (1600, 900)
            windowType Mono
            decorate true
            screenName ControlScreen
            viewerName HMDViewer

You can adjust the window size to fit your monitor, but leave the aspect ratio at 16:10 (or adjust the width and/or height of the ControlScreen to match your window’s aspect ratio).

Then save the file and run an application as follows:

> ./Vrui-3.0/bin/ShowEarthModel -mergeConfig OculusRift.cfg
    -mergeConfig RazerHydra.cfg -mergeConfig Control.cfg

(the command line is broken up here to fit the page; in the terminal, it all needs to be one line). Now there will be a mono window on the main screen that will show the same view as the Rift. You can even control the software by moving the mouse into the control window, and pretending you’re in desktop mode. Whatever you do will be reflected on the Rift’s display.

Positioning the Razer Hydra

You might have a preferred position for the Hydra’s base station that doesn’t match the one configured in ~/Vrui-3.0/etc/VRDevices.cfg. Simple; edit that file, and play with the calibration transformation in the RazerHydra section. You can move the base station around and/or rotate it until the coordinates match the Rift’s coordinate system. To activate any changes in the configuration file, you have to shut down and restart VRDeviceDaemon.

What’s next?

So far you’ve only seen the most basic Vrui example application. Try any of the other ones in the ~/src/Vrui-3.0-001/ExamplePrograms directory. Most are boring API demos aimed at developers, but ClusterJello is fun to play with. Once inside it, bind a 6-DOF dragging tool to buttons on your Hydra, and you can pick up and throw around the Jell-O block. VirtualClay is another fun one; by binding a 6-DOF locator tool to any button, you can model with “virtual clay” in a 3D space.

Or go all out and download some of the actual Vrui applications, such as the Nanotech Construction Kit, 3D Visualizer, LiDAR Viewer, Crusta, etc. If you have an old Quake ||| Arena game disc, get the Vrui binding for CAVE Quake Arena. It’s not very interactive, but fun!

If you have a Kinect, you can download the Kinect 3D Video package and see yourself or others in 3D while wearing the Rift. You can also record and play back 3D home movies (but keep it family-friendly, please). These are real 3D movies, not just stereoscopic movies, so they can be viewed in true 3D from any viewpoint during playback. But they are a bit fuzzy due to the Kinect’s limited resolution. Still, they’re somewhat better than the 3D home movies featured in the movie Minority Report, and definitely better than Star Wars-level holograms.

In the end, of course, go nuts and start developing cool VR software. Read all the developer documentation that is there (it’s not that much), start from the example programs, and, if in doubt, Use the Source. Good luck!

49 thoughts on “Setting up Vrui for Oculus Rift

  1. Pingback: This is a post about Vrui |

  2. Works great. Thanks! Didn’t pick up any accelCorrection values during the calibration but that using your default values seems to work just fine!

    • That’s lucky, I guess. The most important bit are the magnetometer correction values; without those, the Rift can’t align reliably to magnetic north. This might show up as slow rotations of the Rift when inside the software, even when you hold your head still. If that happens, just do the calibration.

  3. Pingback: Installing and running first Vrui applications |

  4. I’m having problems with the calibration step. I can see both sets of RGB axis and the yellow arrow. One frame responds to movements of the rift, however;
    I cannot see the Purple mag field indicator arrow,
    All of my measurements end up with red dots on the same plane and
    the config has NaN for all of the mag fields.

    Have I missed something about enabling the mag compass?

    • That’s bad. For some reason your Rift doesn’t seem to send magnetometer data at all. How long have you had it? If it’s new, maybe Oculus changed some things around in the USB interface, and my code doesn’t work properly.

      When you rotate the Rift around, does the local coordinate frame (smaller arrows) move in a way that corresponds 1:1 to what you’re doing? To check, put the Rift on your desk, nose piece down, front plate facing your monitor. Then rotate the 3D view in OculusCalibrator until the local X axis points to the right, and the local Y axis points up. Then pick up the Rift and rotate it; the axes should mirror what you’re doing precisely.

      You can use my software even without magnetic correction. In VRDevices.cfg, find the “useMagnetometer” setting in the “OculusRift” section, and change it from “true” to “false.” This will lead to yaw drift, of course. Before starting the driver, orient your Rift facing forward, and you’ll probably have to restart the driver after every application to reset yaw. I currently don’t have a yaw reset button.

      • This happens exactly the same way on my Rift too – changing the yaw orientation puts the red dots in the same place (but the pitch orientation seems to move the red dots as expected). There is nothing wrong with the device, it works fine in Windows – my order number was 48xxx so it’s from an earlier run than the most very recent rifts (that omitted some of the cables in the Dev Kit) too. Any chance of a fix? I can see many Rift users having this issue. I’m desperate to sort this out (without the yaw drift as I have Kinect for keyboard viewing), I’ve set up a whole Linux installation just for VRUI!

        BTW your work is absolutely amazing 😀

        • D’oh, I might have misunderstood the earlier problem report then. If you rotate the Rift around the vertical axis, the red dots are not supposed to change position — the direction of gravity is invariant under yaw (that’s why you can’t use accelerometers to measure yaw, and have a yaw drift problem in the first place). The green dots will change because the magnetic flux direction is yaw-dependent (and can therefore be used for drift control).

          Here’s the procedure I use. The Rift’s internal axes are X to the right, Y up, and Z towards the eyes. Place it in the following orientations:

          1. x right, y up, z towards you (i.e., like you would wear it)
          1a. x towards you, y up, z left (i.e., rotate by -90 degrees around y) — this will give the same red dot, but a different green dot
          1b. x away from you, y up, z right (i.e., rotate by 90 degrees around y from 1.) — same red dot again, but one more green dot
          2. x right, y towards you, z down (i.e., rotate by 90 degrees around x from 1.)
          3. x right, y down, z away from you
          4. x right, y away from you, z up
          5. x up, y left, z towards you
          6. x down, y right, z towards you

          These eight orientations will give you the six vertices of an octahedron for red and green dots, like in Figure 4, left. After this rotate in 45 degree increments around the x, y, or z axes to fill in the gaps between the initial points until you have 12 or more red/green points each.

          • Hi okreylos,

            Thanks so much for your detailed reply, it is extremely kind of you to spend so much time helping people to get your stuff up and running. I’m going to try this today 🙂 (as well as Kinect integration). Sorry for the late reply it would have been sooner but the system didn’t notify me by email about your response…

            Will let you know how I get on. Have been watching some of your other videos too, God I envy your job! 😀 Amazing ideas you have and you take such an articulate approach, it’s really refreshing… I’ve previously worked in VR (for a company called Superscape, formerly Freescape) and would love to do so again.

            All the best!
            Chris J

  5. I have some troubles with the last step of your guide.

    When I launch:

    ShowEarthModel -mergeConfig OculusRift.cfg

    it starts the standard Desktop mono window. I guess I’m missing something in the Vrui.cfg , where and how should I specify to use the HMDWindow instead of Desktop/Window ?

    • nevermind, I got it. I replaced OculusRift.cfg instead of paste inside the one provided in Share/

      it almost work, I just have to figure how to let xmonad place the window in the right screen!

      • xmonad… I didn’t even consider how to do this on window managers that don’t allow applications to request window placement, and don’t allow users to move windows manually.

        There must be some way of forcing the issue. If you find one, please post it here. Thanks!

      • Just had an idea. You could run the Rift’s display as a separate X screen instead of using TwinView or ATI/AMD’s equivalent. Then add “display :0.1″ (or whatever display.screen number you configured) and “windowFullscreen true” into the HMDWindow section. That might work.

  6. Pingback: Happy birthday,! |

  7. Having some trouble calibrating. I got the 6 initial points ok and did my best to fill in the space around (though not at 45 degree angles). In the terminal I get this in my results:

    Radii: -nan, 3142.87, 1817.9
    Average radius: nan
    Calibration residual: nan
    magCorrection ((nan, nan, nan), (nan, nan, nan), (nan, nan, nan), (nan, nan, nan))

    Is this due to my haphazard positioning, or some other problem?

    • No, this is a bigger issue I’m trying to narrow down. You should get two sets of calibration results, one for magnetometer and one for accelerometer. In which one do you get the nans? From the other numbers I’m guessing the magnetometer, but I want to make sure. It appears that some Rifts don’t report magnetometer data, or only some components (like y and z in your case) of the data. I don’t have a clue why yet.

      • The nans were in the magnetometer section. I tried again today, here are the results if it’s helpful… the nans seem to be on y and z this time…

        Magnetometer calibration:
        / 0.873033, 0.105547, 0.476102\
        |-0.103076, 0.994178, -0.031387|
        \-0.476643, -0.021672, 0.878830/

        / 0.000000\

        Centroid: 28363, -4290.7, -16028.5
        Radii: 18128.4, -nan, -nan
        Average radius: nan
        Calibration residual: nan
        magCorrection ((nan, nan, nan), (nan, nan, nan), (nan, nan, nan), (nan, nan, nan))

  8. I’m having partial success. I have been able to get the example displayed in my Oculus (pretty cool) but about 3 or 4 times out of 5 I’m getting core dumps (Ubuntu). I’m stuck figuring out what to do next. I can’t seem to get a stable enough configuration to reliable troubleshoot what is happening.

    I originally had similar nan issues for the magnetometer but a recent calibration seems to have cleared that up.

    Any suggestions?

    • I updated the video drivers and the Rift display is working more reliably. I’m still struggling to get the Control.cfg file to work – “Ignoring -mergeConfig argument due to Misc::File: Error opening file Control.cfg in mode rt”.

      • Sorry about the problems you’re having. This error is due to Vrui not finding the Control.cfg file (or not having proper permissions to open it, but that’s probably not it). Try giving the cfg file’s full path after the -mergeConfig, as in -mergeConfig /home/username/configs/Control.cfg . Without a path, Vrui looks for config files in Vrui’s etc directory, which is /home/username/Vrui-3.0/etc in the default installations. If your Control.cfg is in the current directory when you start a Vrui application, use -mergeConfig ./Control.cfg .

        • Thanks for the help. It ends up I had a blank space after the cfg in the name (rookie mistake, I didn’t even know Linux would let you do that). Fixed that and things got better. While I still haven’t quite gotten the Control.cfg path working properly, I found that uncommenting the “windowNames (HMDWindow, ControlWindow)” from the OculusRift.cfg gave me the control screen and the Rift screens working correctly. Then I got the earth quake data loaded. Now I’m going for the wiimotes and kinect.

  9. Pingback: A Closer Look at the Oculus Rift |

    • It should be straightforward, but…

      The basic process is the same as on Linux, but you need to follow the Mac way to install the required supporting libraries, especially libusb. Unlike Linux, Mac OS X doesn’t have a nifty software package manager that does it for you. I think the easiest way is homebrew, and there are existing homebrew recipes for Vrui.

      The biggest hurdle might be how OS X handles Human Interface Devices (HIDs). On Linux I can talk to the Rift at the USB level, but on OS X the OS itself might lock the device, and not let Vrui access it. This used to work, but I’ve heard rumors that it doesn’t on recent versions of OS X.

      I’m in the process of moving some device drivers (Razer Hydra, Oculus Rift, the upcoming PlayStation Move) from raw USB/Bluetooth to raw HID, to then use OS X’s native HID interface, but that’s going to take a while.

  10. Pingback: Someone at Oculus is Reading my Blog |

  11. Hey Okreylos,

    Great tutorial! I found the only issues I had were when I wasn’t doing exactly what you told me to do. However, I am stuck on the following error when I’m running the OculusCalibrator. After I bind keys ‘1’, ‘2’, and ‘3’ to the show raw measurements, record, and show tracking commands, keys ‘1’ and ‘3’ work with no issue, but as soon as I try to record a sample, it seg faults and I get the following error:

    terminate called after throwing an instance of ‘std::runtime_error’
    what(): USB::Device::readControl: Error during interrupt transfer on endpoint 129
    Aborted (core dumped)

    I can still run the ShowEarthModel demo with no issue.


  12. I can confirm those rumours.

    OSX 10.9.4

    vrui 3.1-002-1 from brew.

    VRDeviceDaemon: Caught exception USB::Device::claimInterface: Error while claiming interface 0 while initializing VR devices

    • A temporary workaround I use (a bit long-winded): Setup a low-spec Ubuntu VM via Parallels. Use this VM to run VRDeviceDaemon for RazerHydra, Oculus Rift etc. Connect OSX 10.9 Vrui clients through the ‘wired connection’ established by the VM manager.

      So far, this has worked seamlessly (at least for me); no latency issues or any other adverse effects on Vrui. A better, long-term solution would be to switch over to HIDAPI-based drivers as Dr.Ok mentions above.

      • I can’t get this approach work for me on OS X 10.10, even for just the Razer Hydra. I have a Ubuntu 14.04 server set up in Parallels (also tried VirtualBox) with a running `VRDeviceDeamon -rootSection localhost`(Waiting for client connection). Then from my main operating system I run `ShowEarthModel -mergeConfig RazerHydra.cfg`. (of course I changed the server ip)
        VRDeviceServer then goes:
        Connecting new client from … , Waiting for client connection, Terminating client connection due to exception IO::File::ReadError: Short read by 2 bytes, Disconnected client

        While on the Vrui application I get:
        InputDeviceManager: Ignoring input device adapter DeviceDaemonAdapter due to exception VRDeviceClient: Timeout while waiting for CONNECT_REPLY

        Any clue how to fix this?

  13. Hi okreylos,

    What affordable input device would you recommend buying today for usage with Oculus Rift DK2 + Vrui/Lidar Viewer? Since, as far as I can tell the Razer Hydra is no longer available officially. I understand you have been working on support for the PS Move, but I don’t know how well that works now and if/when it will be properly supported. Are there any viable alternatives? Or would you just advice to get an Hydra off eBay?


  14. Hi ok,

    very nice guide, thanks for all of this

    Anyway if I try to run your script, I get this

    elect@elect-desktop:~/Downloads$ sh
    Please enter your password to install Vrui’s prerequisite packages
    Reading package lists… Done
    Building dependency tree
    Reading state information… Done
    Note, selecting ‘libpng12-dev’ instead of ‘libpng-dev’
    Note, selecting ‘libtiff5-dev’ instead of ‘libtiff-dev’
    build-essential is already the newest version.
    g++ is already the newest version.
    libasound2-dev is already the newest version.
    libbluetooth-dev is already the newest version.
    libglu1-mesa-dev is already the newest version.
    libjpeg-dev is already the newest version.
    libpng12-dev is already the newest version.
    libspeex-dev is already the newest version.
    libtheora-dev is already the newest version.
    libusb-1.0-0-dev is already the newest version.
    libv4l-dev is already the newest version.
    zlib1g-dev is already the newest version.
    libdc1394-22-dev is already the newest version.
    libopenal-dev is already the newest version.
    libgl1-mesa-dev is already the newest version.
    libtiff5-dev is already the newest version.
    libudev-dev is already the newest version.
    mesa-common-dev is already the newest version.
    0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
    Creating source code directory /home/elect/src 33: Syntax error: redirection unexpected

    • elect@elect-desktop:~/Downloads$ sh

      Please run the script as

      $ bash

      or make the file executable and run it directly,

      $ chmod a+x
      $ ./

      On Ubuntu, sh is no longer a redirect to bash, and sh has a slightly different syntax.

    • You might have a newer version of the Nvidia driver. I think Twinview is now the default. Turn on your Rift and see if a new screen pops up in the “X Server Display Configuration” panel. You might have to adjust the resolution to whatever the native is (1280×800 for DK1, 1920×1080 for DK2), but other than that there should be no setup required.

  15. Hi okreylos, I suppose the calibration tool described above does not work for the DK2? I hacked the OculusCalibrator source of the Vrui 3.2 snapshot (on your github) to connect with the DK2 device ID, which at least makes the program run, but my green dot seems to behave differently than yours (judging from Fig 4: in my case it is all over the place, while in your case it always appears in roughly the same area). My calibration result doesn’t make much sense either.

    I suppose, I have to be patient and wait for the next official Vrui release…

    • The calibration program in the Vrui-3.2 snapshot should work with DK2 as-is; I’ve been using it myself to calibrate my own DK2. I never updated the firmware on mine, because it’s never been connected to any official Oculus SDK or run-time. I hope a firmware update didn’t change the USB protocol. I’ll have to look into that when I get a chance.

  16. Thanks for your reply. I tried again today with and got much better results. I also realized I needed to add a minus sign tot the magnetic north correction angle.

    I do have an issue with drift which was improved by fiddling with the driftCorrectionWeight setting. But still the world slowly rotates and translates over time. I get the impression that the magnitude of drift is different along the different axis. X-axis had the greatest drift for me before correction, after correction the drift of the other axes became more noticeable.

    (BTW this is what I changed to make the calibration tool connect to my DK2:

    • Oh, right. My bad; that’s the old calibration tool that only works with DK1. I’ve recently been using the IMUCalibrator application that’s packaged in the OpticalTracking subdirectory. Yes, one difference between DK1 and DK2 is that the third magnetometer axis is reversed. The new IMU tracking code in OpticalTracking/ already accounts for that.

      I am planning to fold the IMU code in OpticalTracking into base Vrui soon, which is why haven’t adapted the OculusCalibrator utility.

  17. Hi Dr. Kreylos,
    I made a similar edit in OculusCalibrator.cpp to search for the proper index of the DK2, but I’m noticing similar problems, the directionality is reversed and the world is slowly rotating to the left. I tried running IMUCalibrator in the OpticalTracking subdirectory of your latest snapshot, however this gives me a segmentation fault (core dumped). In fact I am noticing segfaults in all programs in that directory except for LEDFinder and ShowLEDs which only seem to display static images. Can you release a patch for OculusCalibrator to work with DK2 devices in the meantime while the world waits for the newest version of Vrui? Also, while I’m at it, I must admit, I’m on the edge of my seat, do multiple Kinect mark 2’s cause interference?

  18. Hello,
    Great article. I’m attempting to use this configuration on a DIY-Hmd, without the tracking setup. How would I exclude the tracker-portion of this configuration? My long-term plans are you utilize a polhemus fastrak with vrpn.
    Thank you.

    • The easiest way is to use VRDeviceDaemon to set up a fake Oculus Rift tracking device. In <vrui_installdir>/etc/VRDevices.cfg, change deviceNames (OculusRift) to deviceNames (FakeOculusRift), and then add a section FakeOculusRift with the following contents:

      section FakeOculusRift
        deviceType DummyDevice
        numTrackers 1
        trackerState0 <see below>
        numButtons 0
        numValuators 0
        sleepTime 10000

      Then add a new tag virtualDeviceNames (VirtualOculusRift) to section DeviceManager, and create a new section:

      section VirtualOculusRift
        name OculusRift
        trackType 6D
        trackerIndex 0

      The trackerState0 tag lets you define a fixed position and orientation for the fake Oculus Rift tracker. You can combine any number of translations and rotations, such as

      translate (0.0, -30.0, 40.0) * rotate (0.0, 0.0, 1.0), 30.0

      to position the device 30 inches back from the origin, 40 inches above the origin, and looking 30 degrees to the left. See the VR Device Daemon reference document in Vrui’s HTML documentation for details.

      • Oliver,

        Success!!! ^_^ Thank you so very much!

        It took some reading and trial/n/error to get it working. The trackerstate0 and translate statements threw me off but I eventually found it in the documentation.

        Thanks again. Looking forward to my experiments with Vrui.



Please leave a reply!