TobiiAPI
static class in Tobii.Gaming
namespace
The TobiiAPI is a static API that provides direct access to the most common and useful functionality of the Tobii Unity SDK framework.
Description
TobiiAPI
is a static class with static methods to easily access data from a connected Tobii eye tracker.
To get access to TobiiAPI
, import the Tobii Unity SDK into your project and add the following using (at the top of the script file where you want to use the Tobii API):
using Tobii.Gaming;
TobiiAPI
provides simplified and straightforward access to eye tracker data and can be used for the most common use cases.
TobiiAPI
also provides information about which UnityEngine.GameObject
the user focuses using eye-gaze. Only gaze aware objects will be considered for gaze focus detection (G2OM). The way to make an object gaze-aware is to add the GazeAware
component to it. Start()
function has to be called before using G2OM system. The easiest way to do it is by adding the Tobii Initializer prefab to the scene. This prefab initializes eye tracking with the appropriate settings.
Static Functions and Properties
Name | Description |
---|---|
GetDisplayInfo | Gets info about the eye tracked display monitor. |
GetFocusedObject | Gets the game object with gaze focus. |
GetGazePoint | Gets the last (newest) GazePoint . |
GetGazePointsSince | Gets the gaze points since a given GazePoint . |
GetHeadPose | Gets the last (newest) HeadPose |
GetHeadPosesSince | Gets the head poses since a given HeadPose . |
GetUserPresence | Gets the user presence status. |
IsConnected | Returns true if Tobii Eye Tracker is connected. |
SetCurrentUserViewPointCamera | Sets the camera used for gaze focus detection (G2OM). |
Start | Starts G2OM and the gaze data provider. |
↑ Back to top |
TobiiAPI.GetDisplayInfo
static function on TobiiAPI
public static
DisplayInfo
GetDisplayInfo()
Returns
Type | Description |
---|---|
DisplayInfo | Value object with information about the eye tracked display monitor. Can be invalid, check IsValid before using. |
Description
Gets a DisplayInfo
value object with information about the eye tracked display monitor.
↑ Back to top |
TobiiAPI.GetFocusedObject
static function on TobiiAPI
public static UnityEngine.GameObject GetFocusedObject()
→ View related entry in Manual
Returns
Type | Description |
---|---|
UnityEngine.GameObject | The object the user is focused on by looking at it. Can be null if no object is focused. |
Description
Gets the game object with gaze focus, or returns null if there is no game object with gaze focus.
Only game objects that are gaze-aware will be considered for gaze focus detection. The easiest way to make a game object gaze-aware is to add the GazeAware
component to it. Another way is to implement your own custom gaze-aware component, see IGazeFocusable
.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
GameObject focusedObject = TobiiAPI.GetFocusedObject();
if (null != focusedObject)
{
print("The focused game object is: " + focusedObject.name + " (ID: " + focusedObject.GetInstanceID() + ")");
}
}
}
↑ Back to top |
TobiiAPI.GetGazePoint
static function on TobiiAPI
public static
GazePoint
GetGazePoint()
→ View related entry in Manual
Returns
Type | Description |
---|---|
GazePoint | Where on the screen the user is looking. Can be invalid, check GazePoint.IsValid before using or use GazePoint.IsRecent() function to ensure that it’s both valid and recent. |
Description
Gets the last GazePoint
.
The TobiiAPI
class is initialized lazily. This means that the data provider is started at the first call to this function (or the TobiiAPI.GetFocusedObject()
function), and the function will return an invalid value for some frames until valid data is received from the eye tracker.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
GazePoint gazePoint = TobiiAPI.GetGazePoint();
if (gazePoint.IsRecent()) // Use IsValid property instead to process old but valid data
{
// Note: Values can be negative if the user looks outside the game view.
print("Gaze point on Screen (X,Y): " + gazePoint.Screen.x + ", " + gazePoint.Screen.y);
}
}
}
↑ Back to top |
TobiiAPI.GetGazePointsSince
static function on TobiiAPI
public static IEnumerable<GazePoint> GetGazePointsSince(
GazePoint
gazePoint)
Parameters
Name | Type | Description |
---|---|---|
gazePoint | GazePoint | Typically an already handled gaze point. The function will return all gaze points newer than this gaze point, but at most 500 ms old. An invalid gaze point as parameter will return all data points newer than 500 ms. |
Returns
Type | Description |
---|---|
IEnumerable<GazePoint> | All the GazePoint s that have been received from the eye tracker since the supplied gaze point. |
Description
Gets all GazePoint
s that have been received from the eye tracker since the supplied gaze point, but no older than 500 ms.
This function is useful when you want to do your own advanced filtering of the gaze point data and include all received gaze points in the calculation. If you use GetGazePoint()
you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.
You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.
using System.Collections.Generic;
...
public class ExampleClass : MonoBehaviour
{
private GazePoint _lastHandledPoint = GazePoint.Invalid;
Update()
{
IEnumerable<GazePoint> pointsSinceLastHandled = TobiiAPI.GetGazePointsSince(_lastHandledPoint);
foreach (point in pointsSinceLastHandled)
{
// handle each point that has arrived since previous Update()
// ...
}
_lastHandledPoint = pointsSinceLastHandled.Last();
}
}
↑ Back to top |
TobiiAPI.GetHeadPose
static function on TobiiAPI
public static
HeadPose
GetHeadPose()
→ View related entry in Manual
Returns
Type | Description |
---|---|
HeadPose | Where on the screen the user is looking. Can be invalid, check HeadPose.IsValid before using or HeadPose.IsRecent() to check that it’s both valid and recent. |
Description
Gets the last HeadPose
.
The TobiiAPI
class is initialized lazily. This means that the data provider is started at the first call to this function, and the function will return an invalid value for some frames until valid data is received from the eye tracker.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
HeadPose headPose = TobiiAPI.GetHeadPose();
if (headPose.IsRecent())
{
print("HeadPose Position (X,Y,Z): " + headPose.Position.x + ", " + headPose.Position.y + ", " + headPose.Position.z);
print("HeadPose Rotation (X,Y,Z): " + headPose.Rotation.eulerAngles.x + ", " + headPose.Rotation.eulerAngles.y + ", " + headPose.Rotation.eulerAngles.z);
}
}
}
↑ Back to top |
TobiiAPI.GetHeadPosesSince
static function on TobiiAPI
public static IEnumerable<HeadPose> GetHeadPosesSince(
HeadPose
headPose)
Parameters
Name | Type | Description |
---|---|---|
headPose | HeadPose | Typically an already handled head pose. The function will return all head poses newer than this head pose, but at most 500 ms old. An invalid head pose as parameter will return all data points newer than 500 ms. |
Returns
Type | Description |
---|---|
IEnumerable<HeadPose> | All the HeadPose s that have been received from the eye tracker since the supplied head pose. |
Description
Gets all HeadPose
s that have been received from the eye tracker since the supplied head pose, but no older than 500 ms.
This function is useful when you want to do your own advanced filtering of the head pose data and include all received head poses in the calculation. If you use GetHeadPose()
you will likely miss some points from the eye tracker, since the game and the eye tracker will probably not run in the exact same frequency.
You can save your last handled data point in the Update loop, and use it as a parameter for this function in the next Update loop to retrieve all new data points. For the first iteration, when the data point is invalid, the function will return all points received within the last 500 ms.
using System.Collections.Generic;
...
public class ExampleClass : MonoBehaviour
{
private HeadPose _lastHandledPoint = HeadPose.Invalid;
Update()
{
IEnumerable<HeadPose> pointsSinceLastHandled = TobiiAPI.GetHeadPosesSince(_lastHandledPoint);
foreach (point in pointsSinceLastHandled)
{
// handle each point that has arrived since previous Update()
// ...
}
_lastHandledPoint = pointsSinceLastHandled.Last();
}
}
↑ Back to top |
TobiiAPI.GetUserPresence
static function on TobiiAPI
public static
UserPresence
GetUserPresence()
Returns
Type | Description |
---|---|
UserPresence | User presence status, indicating if there is a user in front of the eye tracker. |
Description
Get the user presence, which indicates if there is a user present in front of the screen/eye tracker.
The UserPresence
extension method IsUserPresent()
returns true if the system detects a user in front of the eye tracker. It is false if the system cannot detect a user in front of the eye tracker, but it is also false if the user presence status is UserPresence.Unknown
. This means that this property can give false negatives if the user presence status is unknown. For example during initializing, or if eye tracking has been disabled by the user, the user can be in front of the eye tracker but IsUserPresent()
returns false. If you need to avoid false negatives for these special cases, check enum value instead.
using Unity.Engine;
using Tobii.Gaming;
public class ExampleClass : MonoBehaviour
{
void Update()
{
UserPresence userPresence = TobiiAPI.GetUserPresence();
if (userPresence.IsUserPresent())
{
print("A user is present in front of the screen.");
}
print("User presence status is: " + userPresence);
}
}
↑ Back to top |
TobiiAPI.IsConnected
static property on TobiiAPI
public static
bool
IsConnected
Returns
Type | Description |
---|---|
bool | Result is true if Tobii eye tracker is connected to the system and false otherwise. |
↑ Back to top |
TobiiAPI.SetCurrentUserViewPointCamera
static function on TobiiAPI
public static void SetCurrentUserViewPointCamera(Camera camera)
Parameters
Name | Type | Description |
---|---|---|
camera | UnityEngine.Camera | The camera that defines the user’s current view point. |
Description
Sets the camera that defines the user’s current view point. The camera is used for gaze focus detection.
By default Camera.main
is used for gaze focus detection to decide which game object the user’s eye-gaze is focused on. If the main camera is not the camera that defines the user’s current view point, this function can be used to override the main camera with a custom camera.
To decide which camera corresponds to the user’s view point, it should fulfill the following:
- given the current
GazePoint gazePoint
- when calling
camera.ScreenPointToRay(gazePoint.Screen)
- the resulting ray into world space should be a continuation of the “ray” from the user’s eyes to the gaze point on the display monitor
↑ Back to top |
TobiiAPI.Start
static function on TobiiAPI
public static void Start(TobiiSettings settings = null)
Parameters
Name | Type | Description |
---|---|---|
settings | TobiiSettings | Settings for G2OM system. Those include layer mask etc. Can be null for default settings. |
Description
Starts G2OM and the gaze data provider. This function has to be called before using the gaze focus (G2OM) system.
If null
is passed, default settings will be used.
↑ Back to top |
COMPONENTS
This section describes components that can be used out-of-the-box to add eye-gaze features to game objects.
GazeAware
class in Tobii.Gaming
namespace / Inherits from: UnityEngine.MonoBehaviour
/ Implements: IGazeFocusable
→ View related entry in Manual
Description
Makes the game object it is attached to gaze-aware, meaning aware of the user’s eye-gaze on it.
The HasGazeFocus
property indicates if the user is currently looking at the game object or not. Which gaze-aware game object that currently has gaze focus can also be queried by calling TobiiAPI.GetFocusedObject()
. Only game objects with the GazeAware
component or some other component that implements the IGazeFocusable
interface can get gaze focus.
Properties
Name | Type | Description |
---|---|---|
HasGazeFocus | bool | True if the game object it is attached to has gaze focus, false otherwise. |
↑ Back to top |
DATA TYPES AND ENUMS
This section describes the data types and enums used with the TobiiAPI
.
DisplayInfo
value type in Tobii.Gaming
namespace
Description
The DisplayInfo
struct contains information about the eye-tracked display monitor.
Properties
Name | Type | Description |
---|---|---|
DisplayWidthMm | float | The width in millimeters of the eye-tracked display monitor. |
DisplayHeightMm | float | The height in millimeters of the eye-tracked display monitor. |
IsValid | float | True if the info object is valid, false otherwise. |
Static properties
Name | Description |
---|---|
Invalid | Creates a value representing an invalid DisplayInfo instance. |
↑ Back to top |
GazePoint
value type in Tobii.Gaming
namespace
→ View related entry in Manual
Description
A GazePoint
represents a point on the screen where the user is looking (or where the user’s eye-gaze intersects with the screen plane).
Always check if a GazePoint
is valid before using it, checking IsValid
property or use IsRecent()
function to ensure that it’s both valid and recent. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetGazePoint()
for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.
The PreciseTimestamp
can be used to compare the timestamps between two GazePoint
s with high accuracy.
Properties
Name | Type | Description |
---|---|---|
GUI | Vector2 | Gaze point in GUI space (where (0,0) is upper left corner). |
IsValid | bool | True if the point is valid, false otherwise. |
PreciseTimestamp | long | Precise timestamp of the gaze point. |
Screen | Vector2 | Gaze point in screen space (where (0,0) is lower left corner). |
Timestamp | float | Time.unscaledTime timestamp of the gaze point. |
Viewport | Vector2 | Gaze point in viewport space. |
Static properties
Name | Description |
---|---|
Invalid | Creates a value representing an invalid GazePoint |
↑ Back to top |
Functions
Name | Description |
---|---|
IsRecent | Returns true if the point is valid and recent, false otherwise. |
IsRecent(float maxAge) | Returns true if the point is valid and no older than maxAge seconds, false otherwise. |
HeadPose
value type in Tobii.Gaming
namespace
→ View related entry in Manual
Description
A HeadPose
represents the head position and rotation of the user’s head.
Always check if a HeadPose
is valid before using it. Invalid points will be returned by the Tobii Unity SDK framework during startup and shutdown, a few frames after calling TobiiAPI.GetHeadPose()
for the first time, and if the data provider is stopped for some reason. Invalid points will always be returned on unsupported standalone platforms, currently Mac and Linux.
The PreciseTimestamp
can be used to compare the timestamps between two HeadPose
s with high accuracy.
Properties
Name | Type | Description |
---|---|---|
IsValid | bool | True if the head pose is valid, false otherwise. |
Position | Vector3 | (X, Y, Z) position of the head of the user, in millimeters from the center of the eye tracked display monitor’s screen area. |
PreciseTimestamp | long | The precise timestamp of the head pose. |
Rotation | Quaternion | Rotation of the head of the user, expressed using Quternion . Use eulerAngles property of the Quaternion to convert it to euler angles. |
Timestamp | float | The Time.unscaledTime timestamp of the gaze point. |
Static properties
Name | Description |
---|---|
Invalid | Creates a value representing an invalid HeadPose |
Functions
Name | Description |
---|---|
IsRecent | Returns true if the head pose is valid and recent, false otherwise. |
IsRecent(float maxAge) | Returns true if the head pose is valid and no older than maxAge seconds, false otherwise. |
↑ Back to top |
UserPresence
enum in Tobii.Gaming
namespace
Description
Describes possible user presence statuses. See also TobiiAPI.GetUserPresence()
.
Values
Name | Description |
---|---|
Unknown | User presence is unknown, the system might for example be initializing |
Present | User is present |
NotPresent | User is not present |
↑ Back to top |
Extension Method
IsUserPresent
extension method for UserPresence
public static bool IsUserPresent(this UserPresence userPresence)
Returns true if UserPresence
is UserPresence.Present
, false otherwise.
IsUserPresent()
can give false negatives for example during initialization when the user presence status is UserPresence.Unknown
.