Oculus HMDs

Vizard 8 » Reference » Stereo & Displays » Display devices » Oculus HMDs

8.0

Oculus HMDs

The oculus module adds support for the Oculus Rift HMD. The following sample code will setup the main window to render to the Oculus Rift HMD and link the HMD sensor to the main viewpoint.

import oculus
hmd = oculus.Rift()
viz.link(hmd.getSensor(), viz.MainView)

A full sample script can be found at \examples\devices\oculusExample.py

Getting Started

In order to use the Oculus Rift HMD with Vizard you must first complete the following steps:

Download and install the Oculus Rift setup tool for version 1.38 or above. Note, the Rift requires Windows 7 or above.
Open the Oculus application and ensure all devices are connected and that your machine meets the minimum requirements. You can use the Oculus application to download and run demo content to ensure the Rift functions properly.
Open the Settings > General page within the Oculus application and enable the Unknown Sources option to allow Vizard scripts to run on the Rift HMD.

Oculus 0.8 Runtime

You can use the older 0.8 Oculus runtime with Vizard if you have a DK2 or DK1 and are unable to update to the latest runtime. Simply use the following code when importing the oculus module:

import oculus_08 as oculus

Troubleshooting

The image in the HMD stutters very badly

This can happen when the frame rate drops below the refresh rate of the HMD. Here are some techniques to resolve this issue:

Reduce the rendering complexity of the scene (i.e. lower poly count, texture sizes, ...)
On Windows 7 we also recommend that you disable DWM.
Use the <hmd>.setTextureScale command (see below) to reduce the resolution of the rendered image in the HMD.

Screen/Ortho objects do not appear in the HMD

The Oculus SDK is provided the rendered image of the world and automatically performs the distortion correction before displaying the image in the HMD. All other rendering performed after the world (i.e. screen objects and sub windows) will not appear in the HMD. You can use GUI canvas nodes to display UI to the user with proper distortion correction applied. See the Oculus example script for sample code.

Rift HMD

The oculus.Rift class provides an interface for setting up the Oculus Rift HMD within Vizard and applying it to window for rendering. The oculus.Rift class constructor accepts the following optional keyword arguments:

Argument	Description
sensor=None	If specified, the Oculus sensor object associated with the HMD. If None, then the first detected sensor will be used. A list of all detected sensors can be retrieved using the oculus.getSensors() command.
window=viz.MainWindow	The window to apply the HMD render settings to.

The oculus.Rift object contains the following methods:

Method

Description

<hmd>.getSensor()

Get the position/orientation sensor object associated with the HMD. See below for a list of methods available to the sensor object.

<hmd>.getLeftTouchController()

Returns a sensor for the left touch controller. See below for more details.

<hmd>.getRightTouchController()

Returns a sensor for the right touch controller. See below for more details.

<hmd>.getRemoteController()

Returns a sensor for the remote controller. See below for more details.

<hmd>.getXboxController()

Returns a sensor for the Xbox controller. See below for more details.

<hmd>.getCameraList()

Returns a list of camera sensors. See below for more details.

<hmd>.setTextureScale(scale)

Set the scale factor for HMD input texture. A value higher than 1 will increase resolution of the image, at the cost of performance. A value lower than 1 will decrease image quality, but at the benefit of better performance. The default value is 1.

<hmd>.getTextureScale()

Get the scale factor for the HMD input texture.

<hmd>.setZoom(factor)

Set the FOV zoom factor. This should be a value higher than or equal to 1. The default value is 1.

<hmd>.getZoom()

Get the FOV zoom factor.

<hmd>.setMonoMirror(mode)

Set whether window mirror is in mono. mode can be True, False, or viz.TOGGLE.

<hmd>.getMonoMirror()

Get whether window mirror is in mono.

<hmd>.getStatus()

Returns HMD status flags. Can be a combination of the following values:

<oculus>.STATUS_ORIENTATION_TRACKED:

The orientation was detected and computed for the last frame.
<oculus>.STATUS_POSITION_TRACKED:

The position was detected and computed for the last frame.
<oculus>.STATUS_CAMERA_CONNECTED:

The camera is connected to the machine.
<oculus>.STATUS_CAMERA_TRACKED:

The camera position was detected and computed for the last frame.
<oculus>.STATUS_HMD_CONNECTED:

The HMD is connected to the machine.
<oculus>.STATUS_HMD_MOUNTED:

The HMD is on the user's head.
<oculus>.STATUS_HMD_FOCUS:

The Vizard window has focus in the HMD and is being displayed to the user.
<oculus>.STATUS_SHOULD_QUIT:

The application should quit as soon as possible.
<oculus>.STATUS_SHOULD_RECENTER:

The user has requested to the have the tracking recentered.

<hmd>.getProfile()

Returns the current user profile settings of the HMD or None if no user profile is active. The user profile object has the following attributes:

name	Name of profile
ipd	Specified IPD value
playerHeight	Specified player height (in meters)
eyeHeight	Player eye height (in meters)
gender	One of the following gender values: oculus.GENDER_UNSPECIFIED oculus.GENDER_MALE oculus.GENDER_FEMALE
eyeCup	One of the following eye cup values: oculus.EYECUP_A oculus.EYECUP_B oculus.EYECUP_C

<hmd>.addCameraBounds(camera=None)

Creates a node for rendering the position tracking boundary of the HMD camera. If the HMD does not support position tracking, then None is returned. camera can be a camera sensor returned by the <hmd>.getCameraList() method, or None to use the first detected camera.

<hmd>.remove()

Remove the HMD object and resources.

Rift Sensor

The Oculus sensor object provides the position and orientation data associated with the internal HMD sensor. The sensor has the following methods in addition to the standard extension sensor methods:

Method	Description
<sensor>.getResolution()	Returns the native [width,height] resolution of the HMD.
<sensor>.getAcceleration()	Get the sensor acceleration vector (m/s^2)
<sensor>.getAngularVelocity()	Get the sensor angular velocity (rad/s)
<sensor>.getRenderSize()	Returns the recommended (width,height) for rendering the input texture for each eye at native resolution
<sensor>.getProjectionMatrix(eye)	Returns the projection matrix for the specified eye
<sensor>.getViewOffset(eye)	Returns the view translation offset for the specified eye
<sensor>.getCameraFrustum()	Returns the (left, right, bottom, top, near, far) frustum of the position tracking camera.

Touch Controller

The touch controller sensor provides position, orientation, and button data for the Rift Touch controllers. The sensor supports the following buttons:

Button

oculus.BUTTON_X

oculus.BUTTON_A

oculus.BUTTON_Y

oculus.BUTTON_B

oculus.BUTTON_THUMB

oculus.BUTTON_ENTER

oculus.BUTTON_INDEX

oculus.BUTTON_HAND

oculus.BUTTON_X_TOUCH

oculus.BUTTON_A_TOUCH

oculus.BUTTON_Y_TOUCH

oculus.BUTTON_B_TOUCH

oculus.BUTTON_THUMB_TOUCH

oculus.BUTTON_INDEX_TOUCH

oculus.BUTTON_INDEX_POINT

oculus.BUTTON_THUMBS_UP

Touch Controller objects support the standard extension sensor interface for providing position and button values. They also provide the following methods to access additional data:

Method	Description
<touch>.getConnected()	Returns whether the controller is connected.
<touch>.getIndexTrigger()	Returns the index trigger value (0 to 1).
<touch>.getHandTrigger()	Returns the hand trigger value (0 to 1).
<touch>.getStick()	Returns the stick (x,y) position value (-1 to 1).
<touch>.setVibration(duration, frequency=1.0, amplitude=1.0)	Set the vibration of the controller for the specified duration (seconds). frequency is a scale factor between 0 and 1 that adjusts the frequency of the vibration between the supported ranges. amplitude is a scale factor between 0 and 1 that controls the strength of the vibration. If duration or amplitude are less than or equal to 0, then the vibration will be disabled.

Remote Controller

The remote controller sensor provides button data for the Rift Remote. The sensor supports the following buttons:

Button

oculus.BUTTON_REMOTE_UP

oculus.BUTTON_REMOTE_DOWN

oculus.BUTTON_REMOTE_LEFT

oculus.BUTTON_REMOTE_RIGHT

oculus.BUTTON_REMOTE_ENTER

oculus.BUTTON_REMOTE_BACK

The remote sensor also provides the following methods:

Method	Description
<remote>.getConnected()	Returns whether the controller is connected.

Xbox Controller

The Xbox controller sensor provides button data for the Rift Xbox controller. The sensor supports the following buttons:

Button

oculus.BUTTON_XBOX_UP

oculus.BUTTON_XBOX_DOWN

oculus.BUTTON_XBOX_LEFT

oculus.BUTTON_XBOX_RIGHT

oculus.BUTTON_XBOX_ENTER

oculus.BUTTON_XBOX_BACK

oculus.BUTTON_XBOX_A

oculus.BUTTON_XBOX_B

oculus.BUTTON_XBOX_X

oculus.BUTTON_XBOX_Y

oculus.BUTTON_XBOX_LTHUMB

oculus.BUTTON_XBOX_LSHOULDER

oculus.BUTTON_XBOX_RTHUMB

oculus.BUTTON_XBOX_RSHOULDER

The Xbox sensor also provides the following methods:

Method	Description
<xbox>.getConnected()	Returns whether the controller is connected.
<xbox>.getLeftStick()	Returns the left stick (x,y) position value (-1 to 1).
<xbox>.getRightStick()	Returns the right stick (x,y) position value (-1 to 1).
<xbox>.getLeftTrigger()	Returns the left trigger value (0 to 1).
<xbox>.getRightTrigger()	Returns the right trigger value (0 to 1).

Camera Sensor

The camera sensor provides position and orientation data for the HMD tracking camera. The sensor also provides the following methods:

Method

Description

<camera>.getStatus()

Returns the camera status flags. Can be a combination of the following values:

<oculus>.STATUS_CAMERA_CONNECTED:

The camera is connected to the machine.
<oculus>.STATUS_CAMERA_TRACKED:

The camera position was detected and computed for the last frame.

<camera>.getFrustum()

Returns the (left, right, bottom, top, near, far) frustum of the position tracking camera.

Oculus Platform applications

To register your script as an Oculus Platform application and perform the required entitlement check, just add the following code to your script:

oculus.initPlatform('insert Oculus Platform appId here')

You can use the following code to handle the result of the entitlement check:

def onViewerEntitled(e):
    if e.error:
        viz.logError('Could NOT get an entitlement')
    else:
        viz.logNotice('User has an entitlement')
oculus.onPlatformMessage(oculus.Message_Entitlement_GetIsViewerEntitled, onViewerEntitled)

Oculus HMDs

Getting Started

Oculus 0.8 Runtime

Troubleshooting

The image in the HMD stutters very badly

Screen/Ortho objects do not appear in the HMD

Rift HMD

Rift Sensor

Touch Controller

Remote Controller

Xbox Controller

Camera Sensor

Oculus Platform applications

See also

In this section:

Other sections: