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).

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.

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!

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 endsection 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 endsection 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 endsection

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.

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/ /-0.000000\ |-0.000000| \-0.000000/ 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.

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.

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 endsection section ControlWindow windowPos (100, 100), (1600, 900) windowType Mono decorate true screenName ControlScreen viewerName HMDViewer endsection endsection endsection

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!