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
  • Check validity on all data points
• Gaze Point data
• Head Pose data
• User Presence
• G2OM and GazeAware component

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:

• TobiiAPI.GetGazePoint()
• TobiiAPI.GetHeadPose()
• TobiiAPI.GetUserPresence()
• TobiiAPI.GetFocusedObject()

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.

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.

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.

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.

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.

G2OM and GazeAware component

Trying to determine what the user is looking at is not a trivial problem and most solutions come with a list of drawbacks. We have experienced these drawbacks first-hand which is the reason we built Tobii G2OM (Gaze-2-Object-Mapping).

Tobii G2OM is a machine-learned selection algorithm, accurately predicting what the user is looking at. It helps developers focus on creating great eye tracking experiences, while also giving users a more consistent experience.

Tobii G2OM comes bundled in our Tobii Unity SDK for Desktop and is built from years of experience working with eye tracking, trained on millions of data points.

The G2OM 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 HasGazeFocus property can be read to know if the game object is focused or not.

G2OM system has to be initialized at the scene startup. The easiest way to do that is by adding the Tobii Initializer prefab to your scene. This prefab initializes eye tracking with the appropriate settings. Alternatively, you can call  TobiiAPI.Start() function at the scene startup.

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 G2OM 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 visualizations 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.

Read more about Tobii G2OM here.