Low-Low-Cost Installation Instructions

This page is a quick guide to set up and configure an entry-level low-cost VR environment based on a 3D TV and a Razer Hydra desktop 6-DOF input device. Because these are entry-level systems, these instructions are aimed at users that want a working system quickly, and don't necessarily want to explore all possible configuration options to squeeze the last 0.5% performance out of their system, unlike the target audience for the installation instructions for the next level up. Meaning, this guide will go with the most common options, and work off pre-made configuration files as much as possible.

Hardware Shopping List

Graphics Computer: The PC running the 3D TV and the VR software. This computer needs to run the Linux operating system, and needs to have a somewhat-decent 3D graphics card with the vendor-supplied drivers installed. If you already have a gaming PC, you don't need to buy anything. Simply install Linux, either as the main operating system, or in a dual-boot configuration. Running Linux in a virtual machine won't work, because virtual machines don't get access to the graphics hardware, and as a result rendering will be very slow.
If you don't already have a graphics card, get whatever model of Nvidia GeForce that fits your budget.
3D TV: As mentioned on the main page, there is no clear best technology among current 3D TVs. To keep this guide simple, I'm just going to go ahead and recommend a passive-stereo (polarized) 3D TV such as the LG Cinema Screen 55LM7600. It is comparatively cheap ($1399.99 for 55"), has good stereo quality, and because the glasses are passive it has the least moving parts, so to speak. For a bigger 65" screen, there's the Vizio M3D651SV for $1950.50.
Razer Hydra: You can get this from Amazon, right along with the 3D TV, for $64.99. Don't wait, buy it right now!

Hardware Setup

This one is simple. Place the 3D TV on a desk, and connect it to your graphics card using a digital connection, either a DVI cable or an HDMI cable. 3D TVs typically have a dedicated input for digital DVI/PC connections; consult your TV's user's manual. Then, when you turn on your computer, the login screen and desktop should appear on the 3D TV in glorious high definition.

Now connect the Razer Hydra to your PC by plugging it into any USB port. Place the Hydra's base station onto the desk about 6" in front of the center of the TV, and orient it such that the cables coming out of the base station point to the back, directly towards the TV.

Software Installation

The only software you need to get started is the Vrui VR toolkit. Grab version 2.6-002 from the download page and follow the quick installation instructions, or just download and run the installation script. You will end up with Vrui installed in a Vrui-2.6 directory underneath your home directory, and Vrui's example programs installed in src/Vrui-2.6-002/ExamplePrograms underneath your home directory.

Running the Hydra Driver and Checking Tracking

In Vrui, applications do not talk directly to the Hydra device. The primary reason is that it takes the device a few seconds to "warm up" after it is switched into 6-DOF tracking mode, and having to wait every time an application is started gets old really fast. Instead, Vrui's VR device driver, VRDeviceDaemon, permanently connects to the Hydra when started, and Vrui applications connect to VRDeviceDaemon when they in turn are started. This leaves the Hydra in 6-DOF mode for the entire duration the driver is running, and means there is no wait time for applications.

VRDeviceDaemon is configured via its own configuration file, VRDevices.cfg in the Vrui installation's configuration directory (~/Vrui-2.6/etc in the default installation). The VRDevices.cfg packaged with Vrui already contains a template section for the Razer Hydra, and nothing has to be edited for initial testing. From a terminal, simply start the device driver as follows (a $ sign indicates commands typed into the terminal):

$ ~/Vrui-2.6/bin/VRDeviceDaemon
... lotsa output ...
Waiting for client connection

After VRDeviceDaemon prints "waiting for client connection," the Hydra is ready to be used by applications. For initial testing, Vrui contains a text-based utility that connects to a running VRDeviceDaemon and continuously prints tracking and button / joystick data. To run it, open a new terminal window and widen it to at least 120 columns, and run DeviceTest as follows:

$ ~/Vrui-2.6/bin/DeviceTest localhost:8555 -t 0 -o -v -b

This will continuously print the position and orientation of the Hydra's left handle (selected by -t 0; write -t 1 to track the right handle), and the state of both handles' buttons and analog axes. Press any button to see a "." turn into an "X," and push the joystick or the shoulder button to change the analog values between -1 and +1.

The printed (x, y, z) position should correspond to the tracked handle's motion: moving the handle to the right or left (relative to the TV) will increase or decrease the x value, respectively; moving it towards the TV or away from it will increase or decrease the y value, respectively; moving it up or down will increase or decrease the z value, respectively. The position is measured in inches relative to the base station, and moving the handle by a certain distance should correspond to an equal change in the displayed position.

The tracked handle's orientation is not printed in the usual pitch, roll, yaw angle triplet form (because that's a deeply flawed way to represent 3D orientations), but as a rotation axis / angle pair. While not as intuitively readable, rotating the handle should lead to repeatable and predictable changes in the printed orientation. Specifically, holding the handle level with the front shoulder buttons pointing directly at the TV should result in a rotation angle close to 0°.

After initial testing, VRDeviceDaemon should be shut down by pressing Ctrl+C inside its terminal window. This will cleanly shut down the driver, and reset the Hydra device to its default state.

Software configuration

As already mentioned, VRDeviceDaemon is configured via ~/Vrui-2.6/etc/VRDevices.cfg. This configuration file contains settings directly affecting the Hydra hardware, such as the strength of the motion filter and a global offset vector to position the handles. The Vrui run-time environment, on the other hand (and Vrui applications by extension), is configured via ~/Vrui-2.6/etc/Vrui.cfg and optional "patch" configuration files found in the same directory. To properly set up the 3D environment, we will be editing VRDevices.cfg and two patch configuration files, 3DTV.cfg (to enable stereo rendering on the TV) and RazerHydra.cfg (to configure the Hydra device at the application level).

Picking a 3D Coordinate Space

One fundamental set of configuration options is to define the positions, sizes, and orientations of all involved components -- the 3D TV, the Hydra's base station, and the viewer's eyes -- in the same 3D coordinate space (this is explained in more detail in Components Defining a Vrui Environment in the Vrui HTML documentation). The exact choice of coordinate space does not matter, but whatever is chosen needs to be used consistently. For simplicity, this guide will use the following convention:

The coordinate space's origin is on the floor, below the 3D TV's center point.
The coordinate space's X axis points to the right when looking at the TV.
The coordinate space's Z axis points up.
From the preceding two conventions, and Vrui's coordinate space always being right-handed, it follows that the coordinate space's Y axis points towards the TV.

Assuming that the 3D TV was placed on a desk, and the Hydra's base station was placed on the same desk, around 6" back from the centerline of the TV, the conventions lead to the following observations:

The lower-left corner of the 3D TV's image is at position (-W/2, 0.0, TH) where W is the width of the TV's image in inches, and TH is the height of the TV image's lower border above the floor. For a 55" TV (which is 48" wide) with a 6" stand and a typical 30" desk, this would be (-24.0, 0.0, 36.0).
The center point of the 3D TV's image is at position (0.0, 0.0, TH + H/2) where TH is as above, and H is the height of the TV's image in inches. For the same 55" TV (which is 27" tall) and 30" desk, this would be (0.0, 0.0, 49.5).
The position of the Hydra's base station is (0.0, -6.0, 30.0) because it is directly on the desk, 6" back from the TV's center line.
The eyes of a viewer sitting down in front of the desk are approximately at (0.0, -36.0, 48.0), assuming a typical viewing distance of 36", and a somewhat tall viewer (or tall chair).
The eyes of a viewer standing in front of the TV would be at (0.0, -36.0, 60.0), obviously depending on the viewer's height.

Note that all of these positions are approximate; since this type of 3D environment is not fully immersive, it is not necessarily to measure the setup at high precision. Besides the TV's size, which should be measured with a tape measure or calculated from the TV's diagonal size and 16:9 aspect ratio, all other positions and sizes can be estimated.

Editing VRDevices.cfg

The only relevant change in VRDevices.cfg is to define the position of the Hydra's base station. First, open VRDevices.cfg with a text editor. From a terminal, run:

$ gedit ~/Vrui-2.6/etc/VRDevices.cfg

Towards the top of the file, find the "localhost" section, and the "RazerHydra" section inside of that. Then locate the "transformation" tag inside the "Calibrator" section. This tag's value defines the position and orientation of the Hydra's base station relative to the selected coordinate space. The default value in the file, translate (0.0, 0.0, 0.0) * rotate (0.0, 0.0, 1.0), 0.0 (a backslash in the file continues a tag's value across a line break), means that the base station is placed at the coordinate space's origin, and oriented with the cables pointing towards the TV.

As explained above, this needs to be changed to reflect the Hydra's actual position, (0.0, -6.0, 30.0). That said, we will not use this position directly. What would happen is that to pick up a virtual object that is located directly in the 3D TV's image plane, the user would have to move a tracked handle to that same location, i.e., the user would have to touch the TV's screen. That is not desirable. Instead, we will virtually offset the Hydra device by 12" away from the TV, such that objects in the TV's image plane can be picked up by safely holding a tracked handle 12" back from the TV. Therefore, change the transformation value in VRDevices.cfg to the following:

transformation translate (0.0, 6.0, 30.0) \
               * rotate (0.0, 0.0, 1.0), 0.0

By using a y value of +6.0 instead of -6.0, we are adding a 12" offset. (How does this work? When holding a handle in an imaginary plane directly above the base station, which is 6" in front of the TV, the Hydra reports a y value of 0.0. The transformation adds 6" to that, meaning that to achieve a y value of 0.0, corresponding to the TV's screen, one would have to hold a handle 6" back from the base station, or 12" in front of the TV.)

Editing 3DTV.cfg

The next step is to configure the position, size, and orientation of the 3D TV, and the viewer, in 3DTV.cfg. Open 3DTV.cfg with a text editor. From a terminal, run

gedit ~/Vrui-2.6/etc/3DTV.cfg

This configuration file is set up for a 55" diagonal 3D TV, placed such that the image's lower border is exactly 30" above the floor. To adapt to your specific setting, edit the following tag/value pairs in section Vrui/Desktop:

Change displayCenter to your TV's center point, i.e., (0.0, 0.0, TH + H/2) as explained above.
Change displaySize to half your TV's diagonal size.
Change newInputDevicePosition to a point 3" back from your TV's center point, i.e., (0.0, -3.0, TH + H/2).
In section Viewer, change headDeviceTransformation to your typical eye position as explained above. For example, for sitting down, change it to "translate (0.0, -36.0, 48.0)."
In section Screen, change the origin to the lower-left corner of your TV's image, i.e., (-W/2, 0.0, TH) as explained above.
In section Screen, change the width and height values to the width and height of your TV.
In section Listener, change headDeviceTransformation to the same value you used in section Viewer, e.g., "translate (0.0, -36.0, 48.0)."
The changes needed in section Window depend on the type and model of your 3D TV.
- Passive-stereo 3D TVs like the LG or Vizio recommended above can typically be run in row-interleaved mode, where the PC sends a composite 3D image where all even pixel rows are for the left eye, and all odd pixel rows are for the right eye. This is the ideal mode for passive-stereo TVs, if your particular model supports it. This mode is already selected in the file, so no changes are necessary.
- Some higher-end active-stereo 3D TVs support quincunx (checkerboard) mode, where odd pixels go to the left eye, and even pixels go to the right eye. This is the ideal mode for active-stereo TVs, if your particular model supports it. To select it, comment out the vertically-interleaved mode setting by putting hash marks (#) in front of the windowType and interleavePattern lines under the "vertically-interleaved..." heading, and uncomment the same lines under the "quincunx..." heading by removing those hash marks.
- For all other 3D TVs, use the standard HDMI top-and-bottom mode by commenting out all other mode lines, and uncommenting the three lines under the "top-and-bottom..." heading.

Testing 3D

To test the setup so far, run the ShowEarthModel application in 3D TV mode. From a terminal, run

~/src/Vrui-2.6-002/ExamplePrograms/bin/ShowEarthModel -norotate -mergeConfig ~/Vrui-2.6/etc/3DTV.cfg

This (rather long) command line will start the Earth Viewer example application, and configure it for 3D TV mode by reading the 3DTV.cfg configuration file. If everything worked, a virtual globe will pop up in the middle of the TV, more or less filling the image. However, the globe will not appear in stereo yet. To achieve that, the TV will have to be put into stereo mode manually. There is typically a dedicated "3D" button on the TV's remote control. Pressing this button will typically show a warning message about potential health hazards of 3D, and after confirming that message, will show a selection of different stereo modes. This is typically where to find out what stereo modes are supported by a particular TV model. The stereo modes are typically represented as icons. For example, top-and-bottom mode is usually represented as two half-height images stacked on top of each other, while vertically-interleaved mode is represented by an image with horizontal lines through it, and quincunx mode is represented by a checkerboard. After selecting the same mode that was previously configured in 3DTV.cfg, the globe should now appear in stereo.

It is still possible that the globe appears "inverted," meaning it looks more like a hollow sphere than a globe. This means that the roles of the left and right eyes are flipped. Depending on the chosen stereo mode, this can be fixed by exiting the application by pressing the Escape key and editing 3DTV.cfg in the following ways:

For vertically-interleaved stereo, flip the eyes by changing interleavePattern from RRLL to LLRR.
For quincunx stereo, flip the eyes by changing interleavePattern from LRRL to RLLR.
For top-and-bottom stereo, flip the positions of the left and right sub-images by renaming leftViewportPos to rightViewportPos and vice versa.

Restarting ShowEarthModel with the same command line should now show the globe in proper stereo.

Connecting the Razer Hydra

There are no required changes to the Hydra's patch configuration file, RazerHydra.cfg. After stereo rendering on the 3D TV has been configured properly, all it takes to add the Hydra device is to start the device driver, and patch in the RazerHydra.cfg file. First, start the VR device driver again. In a terminal, run:

$ ~/Vrui-2.6/bin/VRDeviceDaemon

and wait for the "waiting for client connections" message. Then run any desired Vrui application, e.g. the Earth viewer, from a new terminal as follows:

~/src/Vrui-2.6-002/ExamplePrograms/bin/ShowEarthModel -norotate -mergeConfig ~/Vrui-2.6/etc/3DTV.cfg -mergeConfig ~/Vrui-2.6/etc/RazerHydra.cfg

In this configuration, the positions of the Hydra's handles are indicated by two grey cones that move in a 1:1 relationship with the physical handles, albeit offset by a fixed translation vector. Initially, the cones will not show up, because the handles are mapped below the lower edge of the TV's image when they are resting on the base station. When picking them up, and moving them up and back from the TV, they will appear somewhere in the 3D image.

Using the Hydra Handles

The RazerHydra.cfg configuration file maps a common set of tools to the buttons and joysticks on the left and right handles. Most importantly, the top-right button on the left handle, and the top-left button on the right handle, are mapped to a 6-DOF navigation tool. To try it, move one of the handles such that the tip of the grey cone representing it touches the displayed virtual globe. Then press and hold the navigation button, and move the handle. You will notice that the globe follows the motions of the handle 1:1, as if you had picked up a real globe. Releasing the navigation button will leave the globe at its current position. You can use both handles interchangeably, and you can scale the displayed globe by using both handles at the same time. Pick up the globe with one of the handles, and then press and hold the navigation button on the other handle. Then, moving the two handles apart will make the globe bigger, and moving the handles together will shrink the globe. Releasing either of the navigation buttons will stop scaling, and lock the globe to the other handle in a 6-DOF fashion.

A secondary function is mapped to the lower-right button on the left handle, and the lower-left button on the right handle. Pressing either one will pop up the application's main menu. Move the handle with the button pressed to highlight a menu item or go through submenus, and release the button to select the highlighted entry. The same menu buttons can also be used to interact with on-screen user interface elements such as dialog windows or sliders. Refer to the Using Vrui Applications document in the Vrui HTML documentation for the basics of GUI interaction.

The joysticks on either handle can be used to fly through space. Pushing the joystick forward or backwards will fly in the direction in which the handle is pointing, and pushing the joystick left or right will rotate the view in that direction. Joystick navigation works best when the virtual environment is large compared to the physical environment, such as in building walkthroughs at 1:1 scale. It will not work well in the Earth viewer application.

All other buttons on the two handles can be bound to arbitrary Vrui tools. The tool binding mechanism works exactly as explained in the Using Vrui Applications document. Pressing an unused button will bring up the tool selection menu, and pressing and releasing a button while a handle's cone is positioned above the red tool kill zone will remove the topmost tool assigned to that button so that it can be reassigned to a different tool. For example, a cutting plane tool can be bound to the trigger button (the one above the analog shoulder button) by pressing it, highlighting "Clipping Plane" from the "Pointer" submenu, and then releasing the button. Afterwards, pressing the button will activate a cutting plane that removes all 3D geometry behind it. You can cut away arbitrary portions of the virtual globe by moving and/or rotating the handle while keeping the trigger button pressed.

Finalizing Configuration

Specifying two patch configuration files on each application's command line is annoying. Vrui can be permanently configured to always start applications in 3D TV / Razer Hydra mode. The first step is to create a configuration file containing all settings from Vrui.cfg, 3DTV.cfg, and RazerHydra.cfg. Run any Vrui application, e.g., ShowEarthModel, from a terminal with the following command line:

$ ~/src/Vrui-2.6-002/ExamplePrograms/bin/ShowEarthModel -mergeConfig ~/Vrui-2.6/etc/3DTV.cfg -mergeConfig ~/Vrui-2.6/etc/RazerHydra.cfg -dumpConfig Merged.cfg

The -dumpConfig Merged.cfg command line option will instruct Vrui to dump its configuration space after merging the two patch configuration files to a new configuration file named Merged.cfg.

Afterwards, simply back up the original Vrui.cfg file in ~/Vrui-2.6/etc, and replace it with the newly-created configuration file:

$ mv ~/Vrui-2.6/etc/Vrui.cfg ~/Vrui-2.6/etc/Vrui.cfg.orig
$ mv Merged.cfg ~/Vrui-2.6/etc/Vrui.cfg

From that point on, simply starting any Vrui application (assuming the VR device driver is already running) will run it in 3D TV mode and enable the Razer Hydra device:

$ ~/src/Vrui-2.6-002/ExamplePrograms/bin/ClusterJello

will run the Virtual Jell-O application. In it, you can assign a 6-DOF dragging tool (from the "Dragger" tool submenu) to any button on either handle, and then use that button to pick up and drag the blob of virtual Jell-O.