Difference between revisions of "Unity: Vive HMD Tracking"

(Notes for Unity users)
(Notes for Unity users)
 
(No difference)

Latest revision as of 16:36, 23 September 2019

Main PageOptiTrack Unity Plugin → Unity: Vive HMD Tracking

Page Scope

This page provides instructions on setting up the OptiTrack OpenVR driver for integrating OptiTrack system with Vive HMDs within SteamVR applications; including Unreal Engine 4 and Unity.

Overview

For integrating Vive HMDs, the OptiTrack OpenVR Driver must be used. This driver lets you track the head-mounted display (HMD) and the VR controllers using OptiTrack motion capture system and stream the tracking data from Motive directly into SteamVR. In other words, this will basically override the tracking from the lighthouse stations. The plugin ships as an installer package (MSI) which will set up the driver along with a utility tool for configuring client streaming settings. Once integrated, the streamed tracking data can be used in any application platform that utilizes SteamVR. For tracking of objects other than the HMDs, please read through the OptiTrack Unity Plugin page for details.

Supported Systems

At the time of writing, only Vive HMDs (Vive, Vive Pro) are supported.


HTC Vive HMD Setup[edit]



First of all, setup and optimize the motion capture volume as explained in the Getting Started guide or the Hardware Setup documentation. If you plan to install any obstacles (e.g. walls) within the capture volume, make sure they are non-reflective, and place and orient the cameras so that every corner is thoroughly captured by multiple cameras.

General Setup Steps

  1. Attach the markers on the HMD
  2. Create a rigid body asset
  3. Calibrate the Pivot Point of the rigid body
  4. Configure the rigid body settings in Motive

Place Markers on the HMD[edit]

For the camera system to track the HMD, a set of markers must be attached to the HMD. You can either use the active markers (Vive Pro clip or Active Tags) or the passive markers. Passive markers are retroreflective markers that reflect infrared light emitted from the IR LEDs on the camera. On the other hand, the active markers are LED markers that emit the IR light and has the intelligence to be uniquely identified.

In general, for most VR applications, using active markers is recommended for better tracking stability and ease of use. Active markers also have advantages over passive markers when tracking a large number of objects. For applications that are sensitive to the accuracy of the tracking data, using passive marker may have more benefits. To get more help with finding the best solution for your tracking application, please contact us.

When using the active markers, you can conveniently put a set of 8 markers onto the HMD by using the Vive Pro Clip, or you can attach the markers from the Tag manually onto the HMD using adhesives and marker posts.

Vive Pro Clip[edit]

Vive Pro Clip is an HMD enclosure with a total of 8 active markers embedded for tracking. This clip is designed to fit onto Vive Pro HMDs only. It can be mounted easily by pushing it onto the HMD until the latches click, and you can detach it by gently lifting the three latches located at the top, left, and right side of the clip.

Once the clip has been mounted, next step is to import the provided rigid body asset into Motive and refine the definition to get the calibrated pivot point position and orientation, which will be explained on the next section.

  • Active marker clip for HTC Vive Pro.

Marker Types[edit]

You can either use the passive retro-reflective type markers or the active LED markers to track the HMD. Passive markers are retroreflective markers that reflect infrared light emitted from the IR LEDs on the camera. On the other hand, the active markers are LED markers that emit the IR light which gets uniquely identified in Motive. Either type of marker can be used to track HMDs. Using active marker is recommended especially for applications that involve tracking of multiple HMDs in the scene.

Marker Placement[edit]

  • Make sure the markers are attached securely and do not move. If the markers happen to move even slightly after a rigid body is defined, it will negatively affect the tracking and the rigid body definition may need to be updated.
  • Avoid placing multiple markers in close vicinity as they may overlap in the camera view in certain orientations.
  • Using marker posts to extend out the markers is recommended to improve marker visibility from more angles.
  • If you are using the active markers, there is an extra USB port on the HMD that you could draw the power from.
  • Please read through the Rigid Body Tracking page for additional information on the marker placement on a rigid body.

Create HMD Rigid Body in Motive[edit]

After the markers have been placed on the HMD, a rigid body asset must be defined from those markers in Motive.

For HMDs, their rigid body pivot point must be placed at the root of the user's nose when the HMD is put on. If this is not positioned accurately, there may be unexpected smoothing during head rotations. For the best VR experience, it is very important to have this pivot set up correctly. Please follow the below instruction to get the calibrated pivot point of the HMD.

Creating an HMD rigid body in the Builder pane.

This feature can be used only with HMDs that have the OptiTrack Active HMD clips mounted.

For using OptiTrack system for VR applications, it is important that the pivot point of HMD rigid body gets placed at the appropriate location, which is at the root of the nose in between the eyes. When using the HMD clips, you can utilize the HMD creation tools in the Builder pane to have Motive estimate this spot and place the pivot point accordingly. It utilizes known marker configurations on the clip to precisely positions the pivot point and sets the desired orientation.

Info2.png

HMDs with passive markers can utilize the External Pivot Alignment tool to calibrate the pivot point.

Steps[edit]

  1. First of all, make sure Motive is configured for tracking active markers.
  2. Open the Builder pane under View tab and click Rigid Bodies.
  3. Under the Type drop-down menu, select HMD. This will bring up the options for defining an HMD rigid body.
  4. If the selected marker matches one of the Active clips, it will indicate which type of Active Clip is being used.
  5. Under the Orientation drop-down menu, select the desired orientation of the HMD. The orientation used for streaming to Unity is +Z forward and Unreal Engine is +X forward, or you can also specify the expected orientation axis on the client plugin side.
  6. Hold the HMD at the center of the tracking volume where all of the active markers are tracked well.
  7. Select the 8 active markers in the 3D viewport.
  8. Click Create. An HMD rigid body will be created from the selected markers and it will initiate the calibration process.
  9. During calibration, slowly rotate the HMD to collect data samples in different orientations.
  10. Once all necessary samples are collected, the calibrated HMD rigid body will be created.


Info2.png

This is supported only for Motive versions 2.1.2 or above. If you are using any other versions of Motive 2.1, please update the version to 2.1.2, or use a template to create the rigid body definition; instructions for which is provided in the following page: Using a Template File to Create Vive Pro Active Clip Rigid Body

Step 1: Create Rigid Body[edit]

  1. [Motive] Place the HMD at the center of the tracking volume and make sure the HMD markers are well tracked in Motive.
  2. [Motive] Open the Builder pane under the View tab.
  3. [Motive: Builder pane] Select Rigid Bodies at the bottom and select the Create tab
  4. [Motive: Builder pane] Make sure rigid body is selected under the type section.
  5. [Motive] Select all of the HMD markers in the 3D viewport.
  6. [Motive: Builder pane] Click Create to create a rigid body.


Step 2: Use the External Pivot Alignment tool[edit]

For using OptiTrack system for VR applications, it is important that the pivot point of HMD rigid body gets placed at the appropriate location, which is at the root of the nose in between the eyes. External Pivot Alignment tool utilizes both the OptiTrack mocap system and the HMD's own tracking system (Oculus Tracker / Vive Base Stations) for precisely calculating the location of the pivot point of an HMD. When using this feature, both systems must be tracking the HMD simultaneously.

Info2.png

HMD Compatibility Notes:

  • For Motive versions 2.1 Final and later: Oculus and Vive HMDs are supported.
  • For older versions of Motive: Only Oculus HMDs are supported.
  • The corresponding native HMD tracker must be tracking the HMD along with the motion capture system simultaneously.
  • For CV1 active HMD clips, the rigid body definition will be provided separately.

Info2.png

External Pivot Calibration Tips:

  • Do not move around the HMD during calibration. You will want to keep it at one position and slowly rotate the HMD so that it can calibration from different orientations. When rotating, please rotate it slowly.
  • Camera Exposure: Lower down the camera exposure setting to where the exposure is minimized but the HMD is still tracked well in Motive. This will help with preventing IR interference between the VR HMD's own tracking system and the motion capture system during the pivot calibration process. Set this to around 30us ~ 100us.
  • Frame rate: Lower down the system frame rate down to 30 FPS for better sampling.
  • Calibration Result: For best VR experience, please aim for the error result below ~1mm/marker.

Steps[edit]

  1. First of all, connect the HMD Tracker (Oculus Tracker / Vive Base Stations) and have its corresponding software running in the background.
  2. Launch Motive.
  3. [Motive] Create a rigid body asset from the markers on the HMD.
  4. [Motive] Open the Builder pane and access editing options for rigid bodies.
  5. [Motive] Select the HMD rigid body in Motive.
  6. [Motive → Builder pane] Under Detected Type, it should indicate the type of HMD you will be using.
  7. [Motive → Builder pane] Set the desired number of sample counts (Default: 750) and the desired orientation.
  8. [Motive → Builder pane] Press start to initiate the sampling process.
  9. [Motive → Builder pane] During calibration, make sure both the mocap system and the HMD tracker (Oculus Tracker / Vive Base Stations) is tracking the HMD.
  10. [Motive → Builder pane] Once it starts collecting the samples, point the HMD towards the tracker and slowly rotate it and sample different orientations.
  11. [Motive → Builder pane] When it finishes collecting samples, it will display the offset distance, in mm, between positions of the pivot point detected by the HMD tracking system and the motion capture system.
  12. [Motive → Builder pane] If the results are satisfying, press Apply to calibrate the HMD rigid body.


Setting up the OpenVR driver[edit]


Info2.png

SteamVR Required: The VR driver streams tracking data through SteamVR. Please make sure SteamVR is installed on the computer before setting up the driver.

Setup Steps[edit]

Download and run the installer[edit]

Download the OpenVR driver from the downloads page. Once downloaded, launch the installer and follow the prompts to set up the driver.

OpenVR Installation.gif

Open the configuration program[edit]

Once the driver has been successfully installed, launch the configuration utility software (C:\Program Files\OptiTrack\OpenVR Driver\ConfigUtil). Using this tool, you can load and check existing configurations and make changes to the settings as needed. To import current settings, click Load and to save out the changes, click Save.

Please make sure you are running this tool with admin privileges; if not, it might not be able to modify the settings properly. If the configuration software detects a running instance of SteamVR through OpenVR, it will be indicated as Initialized at the very top as shown in the image. Please note that when the settings get modified while SteamVR is running, the SteamVR must be restarted to apply the changes.

OpenVR ConfigTool.png

Configure connection settings[edit]

First, configure the connection settings so that the driver listens to the Motive server where the tracking data is streamed from. The server address must match the address where Motive is streaming the data to, and the local address must match the IP address of the computer on the network where the driver is installed.

OpenVR ConfigTool Connection.png


Set up the HMD[edit]

In the HMD section, enable the HMD and input the rigid body ID of the HMD. The rigid body ID must match the streaming ID property of the HMD rigid body definition in Motive.

OpenVR ConfigHMD.png VR HMDProperties 20.png


Save out the configuration[edit]

Save the configurations by clicking on Save. This will modify the set of configurations in the steamvr.settings file in the steam installation directory and they will override the HMD tracking with the tracking data from Motive. If you already had an instance of OpenVR or SteamVR running, restart the application to apply the changes.

Info2.png

Configuration File

The configuration tool basically imports and modifies the contents in the steamvr.settings file (C:\Program Files (x86)\Steam\config\steamvr.settings). When needed, the driver related settings can be changed directly from this file also, but it will be easier to configure the settings using the provided configuration tool.

Confirm the setup[edit]

Launch SteamVR. If the driver is successfully set up, you should see a tracker icon added beneath the HMD icon and the HMD will now be using the motion capture system instead of the base stations. Here, please make sure all of the lighthouse base stations are powered off.

OpenVR SteamVR.png


Vive Controllers[edit]

Setting up the controller (optional)[edit]

Info2.png

Important note: External pivot calibration feature is not supported for controllers in Motive 2.1. This will be supported in the next release. In 2.1, you will need to manually position and orient the rigid body pivot point.

When needed, the Vive controllers can be configured as well. To do so, open the configuration utility tool while SteamVR is running. At the top of the configuration tool, it should indicate OpenVR status as Initialized and the controllers must be showing up in SteamVR. Then, in the controller sections, enable the controllers, specify the override device using the drop-down menu, and input the corresponding streaming ID of the controller rigid bodies in Motive. Once everything has been configured, save the changes and restart SteamVR. When the override is configured properly, SteamVR will have additional tracker icon per each enabled controller.

OpenVR Controller.png


Data Streaming[edit]

Now that the driver is set up, the HMD tracking will be overridden by tracking data from the mocap camera system, and you can integrate HMDs into the game engine through their own VR integration.

Streaming settings in Motive[edit]

HMD rigid body streaming settings in Motive.

First of all, make sure the streaming settings are configured in Motive for streaming out the data:

  • Broadcast Frame Data must be set to true.
  • Local interface must be set to the desired IP address to stream the tracking data from.
  • Streaming of Rigid Bodies must be set to True
  • For wireless streaming, use Unicast streaming type.

Confirm the Connection[edit]

Once Motive is configured for streaming, launch SteamVR home to check the connection. If everything is setup correctly, you should be able to move around, or translate, within the scene freely. You may also need to check the ground plane to make sure it's well aligned.

If you experience any unexpected rotations in the view as you move your head, it could indicate that the HMD pivot point has not been calibrated properly. Please revisit the HMD Setup section and make sure the HMD rigid body pivot point is positioned and oriented at the expected pivot; which is at the root of nose with z-forward.

Notes for Unity users[edit]

Once this has been set up, the motion capture system will be used to drive the HMD in SteamVR. In Unity, you should be able to setup development for SteamVR applications and use our system.

For OpenVR development, please make sure the Unity project is configured accordingly. In Unity, open player settings from Edit → Project Settings → Player and select the OpenVR under the Virtual Reality SDK lists. Once this is set up properly, it will play the scene on the HMD.

Unity-OpenVR documenation: https://docs.unity3d.com/Manual/VRDevices-OpenVR.html

Streaming Rigid Body/Skeleton data[edit]


This driver is designed for streaming of HMD and controller tracking data only. For streaming tracking data of other rigid body objects, you will need to use the corresponding plugins (UnrealEngine or Unity). In other words, the HMD tracking data will be streamed through the SteamVR using the driver you've installed, and all other tracking data will be streamed through the plugin.

Aligning world coordinates with the plugin[edit]

Client Origin[edit]

When using the OpenVR driver along with the OptiTrack Unity Plugin for streaming of tracking data other than the HMD, such as rigid bodies and/or skeletons, it is important that the OptiTrack Client Origin object is located at the global origin without any rotations. In other words, the position must be set to (0,0,0) and the rotation must be set to (0,0,0) on the client origin. This is important because the driver does not use the OptiTrack Unity Plugin but instead streams the HMD tracking data directly onto SteamVR through a separate channel.

Related Pages[edit]