Introduction

This manual will provide information on how to best use the ImmersiveViz plugin for PyMol.

Concept

One important thing to remember is that ImmersiveViz by itself doesn't really serve any purpose for PyMol unless it is controlled by some form of head tracking. Currently it is set up to communicate with the drivers from the Head Tracking Driver Project (HTDP). So to use ImmersiveViz properly you must first run the ImmersiveViz program (instructions found [here]), and then run a head tracking driver (instructions [here]).

GUI

The GUI allows you to control and fine tune how the head tracking is mapped to PyMol. It is broken down into 3 parts which are covered here.

Note: Achieving an optimal viewing experience requires a fair amount of tweaking of these controls. The default values are simply a starting point. At the beginning you will likely want to turn off the zoom control (set Zoom Tab, Error Threshold to 100 (see below)).

Rotation Tab

In the rotation tab, you can control how much rotation is used for the head tracking. Finding the perfect setting will create an immersive experience, but the mind isn't so easy to fool (small variations in settings can make the experience seem unnatural).

Accelerated Rotation

These settings can either increase or decrease the amount of rotation the molecule goes through based on your head movements. When you change a numerical value, be sure to hit enter to set it. If enabled (by clicking the On button), the rotation is accelerated (if Field of View is less than Angle) or decelerated (if Field of View is greater than Angle).

Some tips:

• To try for a more immersive setting, set Field of View to 40 and Angle to 10
• To try for a more functional setting, set Field of View to 40 and Angle to 170
• This will allow you to see around the sides of the molecule better
• These values are just a ratio, so 20,40 is the same as 40,80, and so on.

Weighted Rotation

The weighted rotation is a parameter to smooth out the rotation. If you find that the molecule is shaking from left to right (or up and down), then try decreasing the weight. If you find that the rotation is delayed and has to catch up with your movements, then try increasing the weight. Ideally you want to have the weight as high as possible without any jitters. There are no recommended values for this as it depends on the form of head tracking used, the environment, etc.

Auto Configuration

	The auto configuration is perhaps the most important of all settings. It should be used as soon as you start the head tracking program, and before you use PyMol. Calibration will occur 3 seconds after clicking one of the configuration buttons - Assume a normal position (generally centered in the field of view) and wait for the 3 second calibration to complete.
	CV: Configure for Computational Vision form of face tracking.
	IR: Configure for the Wiimote form of Infra Red head tracking.
	AR: Configure for Augmented Reality tracking (currently not implemented).

Zoom Tab

The zoom tab allows the user to have fine control over the various zoom functionality when controlling the molecule.

Zoom Weight

Like the weighted rotation, this parameter attempts to smooth out the zoom input. If the molecule appears to be fluctuating in distance, try playing with this parameter (smaller numbers make it smoother).

Ratio

This is calculated during the "Auto Calibration". Generally you should not change this, but if you want to change the amount of zoom that occurs based on your distance from the screen, this is the parameter.

Max Error

Under the advanced features, the max error affects how many drastic differences in distance we must see before registering the change. This helps when the distance calculated goes to extremes only momentarily (because of error in the data). Increasing the max error will cause the zoom to delay when moving in or out.

Error Threshold

	This parameter goes hand in hand with the max error. The threshold defines how different the distance parameter must be before we consider it "drastically different".
	Tip: If you would like to turn the zoom off, you can just set the error threshold to a large value (ie. 100). This distance will never exceed this and therefore the zoom will not be used.

Other Tab

The other tab contains miscellaneous controls that don't entirely relate to the zoom or rotation.

Frames Per Second

	While this isn't exactly a control, it is useful to see how the plugin is working. It shows the frames per second of the plugin's operation.
	In: This is the frame rate of how fast the head tracking is being fed into the plugin. For the iSight webcam, this hovers around 15 depending on the lighting conditions. For the Wiimote head tracking, this should be much larger.
	Out: This is the frame rate of how fast we are computing the new orientation of the molecule and setting it in PyMol. The calculations done are not that computationally intensive, and an added delay is inserted to slow down the script. This value should be around 30.
	Tip: If the molecule seems to be lagging behind your motions, or possibly choppy, check the In frame rate. If it is too low, adverse affects may happen.

Screen Placement

	This experimental feature translates the molecule forward (if "In front" is selected). The motivation for this is to adjust where we would assume the user is looking at: to the center of the molecule or behind it. The ratio is another assumption made on the size of the molecule and where where it exists in space.
	If you would like to try this feature out, load up 1jnx.pdb (provided with the plugin), turn it on end so lengthwise it is pointing away from you, and select the "In front".