Unity - Getting started

With this SDK you will be able to easily find and get data from your Tobii eye tracker. If you are new to eye tracking we recommend that you spend some time exploring the content in Tobii Pro's Learn & Support section of the Tobii Pro website . There you will find a lot of information about how eye tracking works in general and how to design studies.

In the Common concepts section of this website, you will find information about concepts which are common for all supported languages, such as the different coordinate systems used, and how time stamps are defined.

There are two ways in which you can use the Tobii Pro SDK to develop applications in Unity: Either you use the prefabs included in the package (there are a number of them for both screen based eye trackers as well as for VR eye trackers). Or, you develop your own behaviours by going directly towards the Pro SDK Mono API.

Importing Tobii Pro SDK into your Unity project

Visit our download site for Tobii Pro SDK , and download the latest version of the Tobii Pro SDK Unity Binding.

Adding Tobii Pro SDK to your Unity project

  1. Create a new project, or open an existing project, in Unity.
  2. Select Assets > Import Package > Custom Package... from the main menu, or by right-clicking in the Project window.
  3. Browse to find the downloaded Tobii Pro SDK unitypackage file.
  4. In the next dialog, select to import all files.
  5. Now you can start pulling in the prefabs from either the VR, or ScreenBased, folder into your project. Please see section below more info!
  6. Alternatively, if you want to develop everything from scratch you can start using Tobii Pro SDK Mono API in your scripts.

Adding eye tracking to your application with Pro SDK Unity Prefabs

The Tobii Pro SDK prefabs are meant as a help to start working with the Tobii Pro eye trackers within Unity. The source code used in the prefabs are included and can be used as a starting point for any eye tracking enabled project. Note that they are not guaranteed to be suited for any particular purpose and additional development and testing may be necessary for any given project or use case.

There are two groups of prefabs where each group covers the same use cases for screen based and VR eye trackers respectively:
The VR prefabs are located in: \Assets\TobiiPro\VR\Prefabs
The screen based prefabs are located in: \Assets\TobiiPro\ScreenBased\Prefabs
The [EyeTracker] or [VREyeTracker] prefabs are necessary for any of the other prefabs to work, but apart from that they are independent of each other.

A quick guide to adding Pro SDK Prefabs to your Unity project

  1. Import the Tobii Pro SDK Unity package as described above
  2. Locate the prefabs folder corresponding to the eye tracker you intend to use (VR or ScreenBased) in the Unity Project Window.
  3. Start by dragging the [EyeTracker]/[VREyeTracker] prefab and dropping it into your Hierarchy Window.
  4. Select the new [EyeTracker]/[VREyeTracker] object and use the Inspector Window to edit it's configuration.
  5. If you have more than one (ScreenBased) eye tracker connected to your computer, use the "Eye Tracker Serial Start" text box to create a filter that matches only the eye tracker you want to use. If you only have one eye tracker, check the "Connect to first" box.
  6. You can now drag-drop any of the other prefabs into your hierarchy. You edit their configurations similarily in the Inspector Window. Please note that none of them have any keyboard shortcut (for starting/toggling feature) assigned by default! You need to set this yourself (to an previously unused key)!
  7. Please check the readme files in the package for more detailed information about each Prefab!
Note: The VR prefabs require that you import the Steam VR package into your project!

Examples and Demo Scenes

There are two demo scenes located in \Assets\TobiiPro\Examples\PrefabDemo. One for VR and one for screen based eye trackers. They both highlight how to use the eye tracking prefabs in a simple scene. You can try these out as demos, or use them as examples on how to use the Pro SDK Unity Prefabs.

Developing your own behaviours using the Pro SDK Mono API

The Tobii Pro SDK Mono API is an adaptation of the .NET binding that is compatible with Unity's version of C# (.NET 3.5 / Mono). Hence you can use the same syntax when using the Unity binding as you would when using the .NET binding (with some exceptions). However, since there are some important differences between the two bindings (regarding usage and supported methods), the Mono API has it's own reference guide pages.

A quick guide to a functional application

Most eye tracking applications follow the same pattern in terms of in which order functionality is used. The order is usually as follows:

  1. Browsing for eye trackers or selecting an eye tracker with known address.
  2. Establishing a connection with the eye tracker.
  3. Running a calibration procedure in which the eye tracker is calibrated to the user.
  4. Setting up a subscription to gaze data, and collecting and saving the data on the computer running the application. In some cases, the data is also shown live by the application.

Here's how to do this with the Pro SDK Mono API in Unity:

Step 1: Browsing

Start with the EyeTrackingOperations, a static class residing in Tobii.Research namespace. Use either the FindAllEyeTrackers function to get a list of available eye trackers or the GetEyeTracker function that only returns one eye tracker specified by the eye tracker URI. This could be done in one of Unity's "initialization" event functions, such as Awake() or Start (convenient if you only have one eye tracker), or on demand (if you want the user to be able to chose eye tracker).

Step 2: Connecting to an eye tracker

The objects returned from the functions FindAllEyeTrackers and GetEyeTracker are instances of the class IEyeTracker. Through those objects you can interact with the eye trackers.

Step 3: Performing a calibration

To calibrate the eye tracker, use either a ScreenBasedCalibration or a HMDBasedCalibration object (depending on the type of eye tracker). The ScreenBasedCalibration / HMDBasedCalibration class requires an IEyeTracker object in the constructor. More information about how a calibration works can be found in the section Calibration.

Step 4: Subscribing to data

When you have the IEyeTracker object and want to subscribe to gaze data, subscribe to either the GazeDataReceived or the HMDGazeDataReceived event (depending on the type of eye tracker). The data will be available as GazeDataEventArgs or HMDGazeDataEventArgs respectively.
Note: The events in the SDK are called on a thread internal to the SDK. That thread can not safely set values that are to be read on Unity's main thread. The simplest way to make it safe is to enqueue the data, and dequeue it on the main thread, e.g. via Update() in a MonoBehaviour. This pattern is used in the examples included in the unitypackage.

Step 5: Unsubscribing from data and cleaning up

In Unity it is important to unsubscribe from any Pro SDK data that you have unsubscribed to, otherwise Tobii Pro SDK will not be able to terminate properly, and you risk that your application/game will hang on exit. Unsubscribe to the Tobii Pro SDK events together with your other clean up code, for example in one of Unity's terminating event functions, OnDisable() or OnApplicationQuit().
To be on the safe side, you can also call the Terminate() method on EyeTrackingOperations to ensure that all Tobii Pro SDK resources gets cleaned. Only do this when closing down application or object (i.e. in OnApplicationQuit(), OnDestroy() or similar).

Useful tips and hints

  • Examples

    You can use the code from the prefabs as examples on how to use Pro SDK in Unity. The [EyeTracker] prefabs should work as a great inspiration to most of the steps in the guide above (with the exception of Step 3). The [Calibration] prefabs (obviously) describes Step 3 pretty well.
  • Units

    All "real-world" values in Pro SDK are in millimeters. In Unity, the standard unit is meter. Hence, you will need to convert all Pro SDK data values from millimeters to meters when using them in Unity (and vice versa). See the Coordinate systems section of this documentation for more info about coordinates and transforms.
  • Eye tracker and camera origins in VR

    When working with VR in Unity, the Camera's position is fixed to a point inside the VR headset (or "HMD"). Likewise, the VR eye tracker has a fixed point inside the HMD which it considers to be the origin of its coordinate system (0,0,0). Unfortunately, in the Tobii Pro VR Integration, these two points are not always the same.
    With Steam VR in Unity, the origin of the HTC Vive headset is located 15 mm "behind" the eye tracker's origin. Thus, expressed in Tobii Pro HMD Coordinates, the headset's origin is located at coordinates (0, 0, -15). Hence, you need to adjust all space coordinate values recieved from the eye tracker with this offset.
    This offset is not present in OpenVR.