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.

The Tobii Pro SDK for Unity 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 Unity binding has it's own documentation pages.

The Tobii Pro SDK for Unity is delivered as a Unity package. However, in accordance with the other language bindings it is just an API for accessing the data of the eye tracker. In this case the API is in C# and consists of a set of precompiled .dlls (two native, and one managed). This means that you need to do some work yourself to make it work, such as creating your own MonoBehaviour scripts to attach to your Unity objects. Please see below for more instructions.

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 where you downloaded the Tobii Pro SDK unitypackage file.
  4. Select to import all files.
  5. Now you can start using Tobii Pro SDK in your scripts by adding using Tobii.Research; to your code, or try out the examples in the Examples folder.
  6. If you're using Tobii Pro VR Integration we recommend that you go here to download the examples package for VR which includes working example scenes, and prefabs that takes care of all the steps mentioned below!

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 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

  • 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.