Streaming Setup

Data Streaming settings in Motive.

Tracking data can be streamed in real-time (Live Mode) or from a recorded capture data (Edit Mode). From Motive, data broadcasting can be enabled, or disabled, from the Data Streaming pane, and in this panel, you can configure the connection settings and decide which data to include within the delivered data packet. For the best performance, disable streaming of unnecessary data types. This will reduce the size of data packets and simplify the parsing process on the client side. However, make sure the following data types are enabled for streaming:

Import the Plugin Package

While in the Unity project, double click on the plugin unitypackage file and import the plugin assets into the project. When the package has been successfully imported, the followign contents will be available within the project:

Setting Up the Client Object

In order to receive tracking data from a server application (e.g. Motive), you need to create a client object. A client object can be any object within a scene in Unity, and it can be designated by attaching OptitrackStreamingClient.cs script. This script receives the tracking data from the connected server application (e.g. Motive) and makes the data available within the scene. You can either attach the client script onto an existing object or an empty object. Also, you can just import the sample from the Assets/Optitrack/Prefabs folder.

• [Motive] In the Data Streaming pane, configure the desired connection settings and check the Broadcast Frame Data box.
• [Unity] Under the Prefabs folder, import the client prefab object into the scene, or you can just attach OptitrackStreamingClient.cs script onto an existing object.
• [Unity] In the Client object, configure the connection settings from the OptiTrack Streaming Client script so that the values (Connection Type, Local Address, Server Address, Server Command Port, Server Data Port) match the parameters under the Data Streaming pane in Motive.

• Local Address: Local IP Address of the PC that the client application is running on.
• Server Address: IP address of the PC that the server application is running on.

• [Unity] Set the Bone Naming Convention type so that it matches the convention set in Motive.
• [Unity] If you wish to receive tracking data from more than one server instances, you may create multiple objects with the client script attached.

Client object in Unity and the corresponding Motive data streaming network settings.

Position data in Unity Position component of the streamed data will be received as reference positions in Unity. In other words, the streamed position will reflect object's relative displacement from its root object or the global origin if the object is placed at the root level of the hierarchy in Unity. For this reason, although it is not strictly necessary, you may find it helpful to organize your tracked objects as children of a common game object (e.g. the Client object) that can then be re-positioned in the Unity scene to effectively determine the location of the tracking volume origin. And doing so will make it easier to adjust the global origin of Motive within a scene in Unity. [Unity Hierarchy Pane] Components set to children of the root Client object.

Animating Rigid Body

1. [Unity] On an object that you wish to animate, attach OpitrackRigidBody.cs script.
2. [Unity] In the Streaming Client entry, link the Client object which the client script is attached to. By default, it searches for an existing client instance, but this must be specified when there are more than one streaming client objects.
3. [Unity] For the Rigid Body ID entry, enter the User Data ID which is assigned to each rigid body asset in Motive.
4. [Motive] Make sure Motive is streaming, play the scene in Motive.
5. [Unity] Play the scene. The linked object will be animated according to the rigid body movement in Motive.

OptiTrack Rigid Body configuration along with the rigid body properties in Motive. Configured Streaming ID must match the Rigid Body ID designated from the client side.

Animating Skeleton

1. [Unity] On Unity characters, attach OptitrackSkeletonAnimator.cs script as one of its components.
2. [Unity] For the Streaming Client entry, link the object which the client script is attached to. By default, it searches for an existing client instance, but this must be specified when there are more than one streaming client objects.
3. [Unity] Enter Skeleton Asset Name which is Assigned in Motive
4. [Unity] For the Destination Avatar entry, link to the character that the script is loaded to.
5. [Motive] From the Data Streaming pane, make sure Motive is streaming.
6. [Unity] Play the scene. When everything is set up properly, the linked avatar in Unity will be animated according to the streamed skeleton in Motive. The position of the actor will be in its reference position as explained above.

Optitrack Skeleton Animator script configuration from a character in Unity.

Oculus DK2, CV1)

1. [Motive] First of all, follow the HMD Tracking Setup section and prepare HMD rigid bodies in Motive.
2. Make sure the HMD software is running.
3. [Unity] In the Unity project, check the Virtual Reality Supported box from the player settings (Edit → Project Settings → Player), as shown in the image below.
4. [Unity] From the Prefabs folder (OptiTrack/Prefabs) of the imported plugin package, import the HMD prefab (HMD - OptiTrack) object into the scene.
5. [Unity] In the Streaming Client entry, specify the object which the streaming client is attached to. By default, it searches for an existing client instance, but this must be specified when there are more than one streaming client objects.
6. [Unity] For the Rigid Body ID entry, enter the User Data ID value given for the HMD rigid body in Motive.
7. [Unity] For the Rigid Body Orientation entry, enter the orientation of the rigid body coordinate axis that is defined in Motive.
8. [Unity] Play the scene. When the HMD is properly connected, the scene will be visible from the HMD.

OVRManager Having OVRManager enabled within the project may introduce an additional offset to the position of the HMD. If you are seeing positional offset in the HMD position, remove the OVRManager object.

Integrating HMD (Android: Gear VR)

Gear VR devices can also be integrated and the tracking information can be streamed via wifi connections using a router with sufficient bandwidth. The required bandwidth will vary depending on many factors (e.g. router type, the number of tracked object, etc.). For more specific information on this setup, contact us. The following settings must be configured in addition to the above HMD settings for developing Gear VR experiences using the plugin. For more information on developing Gear VR applications in Unity, refer to Unity documentations.

Settings

1. [Unity] For developing Android applications in Unity, make sure the environment is set up for Android development: Getting Started with Android Development. Below are some of the important steps:

• Download the Unity Android package under File → Build Settings... → Android.
• Put your phone into the Developer Mode. On Samsung Galaxy, for example, go to Settings → About Phone and tab on the build number a few times.
• Install, then enabled the developer mode by turning on the Gear VR Service → Memory → Developer Mode.

2. [Unity] Include the OSIG file (oculus signature) in the Project/Assets/Plugins/Android/assets/ directory. See: Oculus Signature File Generator.

3. [Unity] Open the Player Settings (Edit → Project Settings → Player) and check the Virtual Reality Supported box under the XR Settings section. Then add the Oculus SDK under the list of Virtual Reality SDK as shown in the image below.

4. [Unity] In Player Settings under the Other Settings section, there are a few other options that need to be set:

• Configuration → Internet Access → Require
• Identification → Package Name → com.[Company Name].[Product Name]. This just needs to be unique.
• Identification → Minimum API Level ↠ (API level 19).

• 
• 

5. [Motive] Under the Data Streaming pane, set the Network Type setting under the Advanced Settings to Unicast.

Note: the plugin currently only supports the Unicast broadcasting for streaming onto Android.

Connecting via Wifi

1. [Motive] Set the streaming IP address to the IP address of the router.

2. [Android] Connect the smartphone to the router which the Motive is streaming to.

3. [Unity] Configure the Client object. This can be done using the Client - OptiTrack prefab included in the plugin.

• Set the Connection Type to Unicast.
• Set the Local Address to the IP address of the phone. The local address can usually be found under the phone's settings. The IP address for the Samsung Galaxy, for example, can be found under Settings → About Phone → Status → IP Address". For some phones, the address of 0.0.0.0 may work.
• Set the Server Address to the router's IP address, or whatever the IP address that the host PC (server) is streaming data to. This address can also be found under the phone's settings when the smartphone is connected to the wifi router of the tracking server.

4. [Unity] Configure the HMD object.

• Drag the “HMD - OptiTrack” prefab into the scene.
• Drag your Client object into the Streaming Client property.
• Set the Rigid Body ID to the streaming ID of whatever rigid body you are using as the HMD in Motive.

5. [Unity] Connect a smartphone into the PC, build and run the project. Make sure network permission is given to the Unity application.

6. [Motive] Double check that Motive is streaming. If everything is set up properly, Motive will provide the tracking data to the phone.

Marker Attachment

Active HMD ClipPassive Markers

Active Markers

Attachment & Placement

With the HMD bracket, simply attach the active marker bracket onto an CV1 HMD and use the active markers on it to define a rigid body.

When using the OptiTrack Active Marker Kit, active markers are actively labeled individually from their own unique illumination patterns, and only the matching active markers get contributed to the rigid body solve. The biggest benefit from the individual labeling is that markers can be placed in perfectly symmetrical placements among multiple rigid body assets.

• 

  Putting the HMD bracket on
• 

  When detaching the bracket from the HMD, first pull up the two latches behind the bracket and slowly pull it from the top.

Passive Markers

Attachment

When attaching retroreflective markers, make sure markers are securely attached and readily captured by the cameras. For attaching the markers, we recommend using our 20 mm wide and 30 mm tall M4 threaded plastic marker bases with Acrylic adhesives, available at the webstore, to attach the markers onto the HMD.

Placement

A markered HMD will be defined as a rigid body in Motive. When placing markers, make sure the placement asymmetry is respected in the arrangement within the HMD. Also, the marker arrangements between multiple HMDs must be incongruent. For more details, read about marker placement from the Rigid Body Tracking page.

Create an HMD Rigid Body

In Motive, select the markers that are attached on the HMD and create a rigid body (Hotkey: CTRL + T) as you would do for other rigid bodies. Once the rigid body is created, select the asset and open the Properties pane. The following settings need to be configured for HMD tracking.

Rigid body properties for the HMD asset.

Deflection

Deflection setting is the tolerable distance, in millimeters, that a rigid body marker may deviate from its expected position before it is unlabeled and unassociated with the rigid body. The deflection is set to 4 mm by default. For HMD tracking applications, we recommended lowering this value to 3 or 2. This will reduce the amount of computation required for labeling, and overall latency may be reduced.

Tracking Algorithm

The tracking algorithm setting determines which protocol to use for solving the rigid body in Motive.

Passive Markers

Use the ray-based tracking algorithm for HMDs with passive markers. This algorithm is recommended because it allows tracking to be less susceptible to marker occlusions and solves rigid bodies more robustly without introducing trajectory gaps. This is more suitable for tracking the passive marker HMDs since even minor occlusions can acutely affect the experience.

Active Markers

Use the marker-based tracking algorithm for HMDs using active marker clips. Ray-based tracking is not supported for active markers. However, active markers themselves already provide stable tracking from its unique illumination patterns. Thus, marker-based tracking will provide robust tracking for HMDs with active markers.

Streaming ID

The Steaming ID of a rigid body is a number that can be used for referencing the specific rigid body in external applications. Log this value for each rigid body (including the HMD(s)) in the scene. This number will be used to associate the assets in the client applications using the plugin devices.

Min Marker Count

This setting may need to be modified when tracking HMDs with passive markers. To prevent the swapping of the rigid body definition, set this setting to 4. When tracking multiple HMDs, there could be limitations to a variety of unique marker arrangements that could be achieved. If this value is set to a lower value, a set of three markers on an HMD may be congruent to another set in a different HMD, and the rigid body definitions may be switched in Motive.

Calibrate Rigid Body Pivot Point

HMD Calibration Tool

Rigid body pivot can be easily calibrated using the HMD Calibration tool. Supported only for Oculus HMD models only. Does not work with GearVR.

Active HMD ClipPassive Markers

Using the HMD Calibration Tool (Active HMD Clips)

You can also use the HMD Calibration feature to easily calibrate the pivot point of the active marker HMD clips.

1. First of all, make sure Motive is configured for active marker tracking.
2. In Live mode, select the active markers on the HMD clip and define a rigid body.
3. Under Tools tab open the Trackables pane and access the HMD calibration tab.
4. Hold the selected rigid body at the center of the capture volume so that as many cameras as possible can clearly capture the markers on the HMD clip.
5. Select the active HMD clip rigid body in Motive.
6. Make sure Detected Type shows up as OptiTrack Active HMD clip.
7. Under the Samples Counts entry, assign a number of sample frames that you wish to capture for calibration
8. Select the desired orientation of the rigid body. You can select from +Z forward (Unity), +X forward (Unreal), or -Z forward (Native)
9. Press Start to start the calibration process.
10. Slowly rotate the HMD to collect samples in diverse orientations.
11. Once all necessary samples are collected, it will report the calibration result.
12. If everything looks good, press Apply Calibration, and the HMD rigid body pivot point will be calibrated to given orientation.

Using the HMD Calibration Tool (Passive Markers)

Calibration of HMDs with passive markers utilizes both the OptiTrack mocap system and the Oculus Tracker for precisely calculating the location of the pivot point of an Oculus HMD. When using this feature, both systems must be tracking the HMD rigid body.

1. Connect the Oculus Tracker and have the Oculus software running in the background.
2. Launch Motive.
3. [Motive] Create a rigid body asset from the markers on the oculus HMD. Read: Creating Rigid Body.
4. [Motive] Open the Trackables pane. Tools → Trackables → HMD Calibration tab
5. [Motive] Select the HMD rigid body. Under Detected Type, it should indicate Custom RigidBody.
6. [Motive → Trackables pane] Set the desired number of sample counts (Default: 750) and the desired orientation.
7. [Motive → Trackables pane] Press start to initiate the sampling process.
8. [Motive → Trackables pane] During calibration, make sure both the mocap system and the Oculus Tracker is tracking the HMD.
9. [Motive → Trackables pane] Once it starts collecting the samples, point the HMD towards the Tracker and slowly rotate it and sample different orientations.
10. [Motive → Trackables pane] When it finishes collecting samples, it will display the offset distance, in mm, between pivot point position detected by oculus and the motion capture system.
11. [Motive → Trackables pane] If the results are satisfying, press Apply to calibrate the HMD rigid body.

Export the Rigid Body

Tip: Once you have the rigid body asset for the HMD configured, you can export the asset into a TRA file for future uses. Importing the TRA file (e.g. CV1.tra) will load the rigid body (HMD) asset and make it available for use; however, the marker placement must remain unchanged in order to re-load previously created rigid bodies.

Live Streaming

Once you have connected the client object and configured the script components on the assets from the scene. Play the scene, and if the properties are correctly configured, the assets in the game scene will be animated according to the position and orientation of the rigid bodies and the HMD in Motive. When playing the scene, the HMD and the assigned actor objects will be placed in respect to their location in Motive’s coordinate system disregards to their position in the editor.

Wireless Multiplayer Setup

When setting up multiplayer games with wireless clients, it is more beneficial for each client to make direct connection to both the tracking-server (Motive) and the game-server, rather than rebroadcasting the streamed tracking data through the game-server. Then, any of the game related actions that interacts with the tracking data can be processed on the game-server, and this server can send out the corresponding updates to the wireless clients. This allows the wireless clients to only receive both the tracking data or updates without having to send back any information; in other words, minimizing the number of data transfers needed. If wireless clients are sending data there will be a minimum of two transfers on the wireless network, and each transfer of data through wireless network is at risk of latency or lost packets.