It might be tempting to skip this part of the documentation, but I promise you that it will save you time later to at least browse through it.

This section gives an overview of the features available in the Tobii Unity SDK. It introduces the core concepts and gives you insight into what tools and features the SDK has to offer you, and how they work.

For API details on each class and function, see the Tobii Unity SDK Scripting Reference.

Section contents:

TobiiAPI

The static functions of the TobiiAPI class is the essential API of the Tobii Unity SDK.

Include the line

using Tobii.Gaming;

in a script anywhere in your game and you will have access to the static API functions.

Here are some of the API functions:

You can read more about gaze point data, head pose data, user presence, and focused object in the sections below.

Check validity on all data points

The TobiiAPI is implemented using so called ‘lazy initialization’. This means that the API is not initialized until the first call to any of its functions. Because of this, the first time the functions are called they will return values that are invalid (IsValid is false). Depending on how many game loops it takes to initialize the underlying framework, there will be a number of frames where invalid data is returned.

Gaze Point data and Head Pose data can be explicitly initialized by calling TobiiAPI.SubscribeGazePointData or TobiiAPI.SubscribeHeadPoseData respectively. If these functions are called during some appropriate time, during game startup for example, valid data can be available on the first calls to TobiiAPI.GetGazePoint() and TobiiAPI.GetHeadPose().

In most cases it’s also very important to know that you are working with recent data. TobiiAPI.GetGazePoint() and TobiiAPI.GetHeadPose() will return the latest data received from the eye tracker but that can be old. For example, if a user looks away from the monitor. We suggest using IsRecent() method to ensure that data is both valid and recent.

↑ Back to Top

Gaze Point data

GazePoint is the data type returned by TobiiAPI.GetGazePoint(). It represents the point on the screen where the user is looking. More technically it is the point on the screen where the eye tracker has calculated that a line along the user’s eye-gaze intersects with the screen plane.

GazePoint.Viewport returns the gaze point in Viewport coordinates, where (0,0) is the bottom-left and (1,1) is the top-right corner of the UnityEngine.Screen. The values can be higher than 1 and lower than 0 if the user looks a bit outside the physical bounds of the monitor.

GazePoint.Screen returns a Vector2 (x,y) coordinate on the UnityEngine.Screen. This might seem pretty much like getting a mouse pointer coordinate, but please do not make the mistake of using this point out-of-the-box as you would use a mouse pointer coordinate. Eye tracking data is not as precise as mouse pointer data – it is actually physically impossible due to how our eyes and seeing works. Instead, think of a series of GazePoints as representing an area where the user is looking, and take into account that the accuracy and precision of the data varies from user to user.

↑ Back to Top

Head Pose data

HeadPose data can be used to complement GazePoint data to further improve infinite screen experiences like Extended View.

HeadPose is the data type representing the position and orientation of the user’s head. Position is being measured in millimeters relative to the middle of the screen eye tracker is mounted on. The position is the point in space around which the head is rotated.

Rotation represents the rotation of the head of the user, expressed using Quaternion. Use eulerAngles property of the Quaternion to convert it to euler angles.

↑ Back to Top

User Presence

User Presence is a state that indicates if a user is present in front of the eye tracked screen or not. This state can be used to for example pause some feature if there is no user present.

↑ Back to Top

Gaze Focus and GazeAware component

The Tobii Unity SDK has built-in support for mapping eye-gaze data to game-objects. We call this feature Gaze Focus. Rather than just mapping every gaze point to a game-object the idea is that an object that has Gaze Focus is intentionally focused by the user. To do this, we are under the hood using algorithms that take series of gaze points, the history of focused objects and timings in human perception into account.

These gaze to object mapping algorithms were introduced in the 2.0 version of the SDK. The plan is to refine the algorithms continually in future versions of the framework. The goal is to have a fast and robust calculation that works for different eye tracker models with different characteristics in accuracy and precision, but also over a broad set of different eye-gaze characteristics of end-users.

The Gaze Focus system only maps game objects that gaze focusable. In order to make a game object gaze focusable you need to add the GazeAware component to it. This component will register the game object as Gaze Aware at OnEnable and unregister it at OnDisable. In the game object’s Update loop the GazeAware component’s HasGazeFocusproperty can be read to know if the game object is focused or not.

For game algorithms outside of the individual game objects, it is also possible to ask the gaze focus handler which object is currently focused using the static API function TobiiAPI.GetFocusedObject(), and have the game respond to this information. Only one object (or no object) is considered to have gaze focus at the time.

As a developer you should use Gaze Focus as it is out-of-the-box, since any additional filtering done on top of the gaze focus calculation might be a bad fit when the algorithms are refined in future releases. Highlighting of objects and visualisations should use timings related to human perception rather than be adapted to a specific gaze focus algorithm, eye tracker model or a specific user’s characteristic gaze-tracking.

Gaze Focus is only available for 3D game objects with a UnityEngine.Collider. It does not work with UI elements on canvases.

↑ Back to Top