tobii_research.EyeTracker Class Reference

Provides methods and properties to manage and get data from an eye tracker. More...

Public Member Functions
def	__init__ (self, address)
	Gets an eye tracker object that has the specified URI. More...
def	apply_licenses (self, license_key_ring)
	Sets a key ring of licenses or a single license for unlocking features of the eye tracker. More...
def	clear_applied_licenses (self)
	Clears any previously applied licenses. More...
def	retrieve_calibration_data (self)
	Gets the calibration data used currently by the eye tracker. More...
def	apply_calibration_data (self, calibration_data)
	Sets the provided calibration data to the eye tracker, which means it will be active calibration. More...
def	get_all_gaze_output_frequencies (self)
	Gets a list of gaze output frequencies supported by the eye tracker. More...
def	get_gaze_output_frequency (self)
	Gets the gaze output frequency of the eye tracker. More...
def	set_gaze_output_frequency (self, gaze_output_frequency)
	Sets the gaze output frequency of the eye tracker. More...
def	get_all_eye_tracking_modes (self)
	Gets a tuple of eye tracking modes supported by the eye tracker. More...
def	get_eye_tracking_mode (self)
	Gets the eye tracking mode of the eye tracker. More...
def	set_eye_tracking_mode (self, eye_tracking_mode)
	Sets the eye tracking mode of the eye tracker. More...
def	get_display_area (self)
	Gets the size and corners of the display area. More...
def	set_display_area (self, display_area)
	Sets the display area of the eye tracker. More...
def	set_device_name (self, device_name)
	Changes the device name. More...
def	subscribe_to (self, subscription_type, callback, as_dictionary=False)
	Subscribes to data for the eye tracker. More...
def	unsubscribe_from (self, subscription_type, callback=None)
	Unsubscribes from data for the eye tracker. More...

Detailed Description

Provides methods and properties to manage and get data from an eye tracker.

EyeTracker objects are either created from an address or returned in a tuple from find_all_eyetrackers.

Constructor & Destructor Documentation

def tobii_research.EyeTracker.__init__	(		self,
			address
	)

Gets an eye tracker object that has the specified URI.

import tobii_research as tr

 address = "tet-tcp://10.46.32.51"
eyetracker = tr.EyeTracker(address)

print("Address: " + eyetracker.address)
print("Model: " + eyetracker.model)
print("Name (It's OK if this is empty): " + eyetracker.device_name)
print("Serial number: " + eyetracker.serial_number)

if tr.CAPABILITY_CAN_SET_DISPLAY_AREA in eyetracker.device_capabilities:
    print("The display area can be set on the eye tracker.")
else:
    print("The display area can not be set on the eye tracker.")

if tr.CAPABILITY_HAS_EXTERNAL_SIGNAL in eyetracker.device_capabilities:
    print("The eye tracker can deliver an external signal stream.")
else:
    print("The eye tracker can not deliver an external signal stream.")

if tr.CAPABILITY_HAS_EYE_IMAGES in eyetracker.device_capabilities:
    print("The eye tracker can deliver an eye image stream.")
else:
    print("The eye tracker can not deliver an eye image stream.")

if tr.CAPABILITY_HAS_GAZE_DATA in eyetracker.device_capabilities:
    print("The eye tracker can deliver a gaze data stream.")
else:
    print("The eye tracker can not deliver a gaze data stream.")

if tr.CAPABILITY_CAN_DO_SCREEN_BASED_CALIBRATION in eyetracker.device_capabilities:
    print("The eye tracker can do a screen based calibration.")
else:
    print("The eye tracker can not do a screen based calibration.")

if tr.CAPABILITY_CAN_DO_MONOCULAR_CALIBRATION in eyetracker.device_capabilities:
    print("The eye tracker can do a monocular calibration.")
else:
    print("The eye tracker can not do a monocular calibration.")

if tr.CAPABILITY_HAS_EYE_OPENNESS_DATA in eyetracker.device_capabilities:
    print("The eye tracker can deliver an eye openness data stream.")
else:
    print("The eye tracker can not deliver an eye openness data stream.")

Parameters

address

Address (URI) to the eye tracker.

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
ValueError

Member Function Documentation

def tobii_research.EyeTracker.apply_calibration_data	(		self,
			calibration_data
	)

Sets the provided calibration data to the eye tracker, which means it will be active calibration.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

filename = "saved_calibration.bin"

# Save the calibration to file.
with open(filename, "wb") as f:
    calibration_data = eyetracker.retrieve_calibration_data()

    # None is returned on empty calibration.
    if calibration_data is not None:
        print("Saving calibration to file for eye tracker with serial number {0}.".format(eyetracker.serial_number))
        f.write(eyetracker.retrieve_calibration_data())
    else:
        print("No calibration available for eye tracker with serial number {0}.".format(eyetracker.serial_number))

# Read the calibration from file.
with open(filename, "rb") as f:
    calibration_data = f.read()

    # Don't apply empty calibrations.
    if len(calibration_data) > 0:
        print("Applying calibration on eye tracker with serial number {0}.".format(eyetracker.serial_number))
        eyetracker.apply_calibration_data(calibration_data)

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError
ValueError

def tobii_research.EyeTracker.apply_licenses	(		self,
			license_key_ring
	)

Sets a key ring of licenses or a single license for unlocking features of the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

import tobii_research as tr

print("Applying license from {0}.".format(license_file_path))
with open(license_file_path, "rb") as f:
    license = f.read()

failed_licenses_applied_as_list_of_keys = eyetracker.apply_licenses([tr.LicenseKey(license)])
failed_licenses_applied_as_list_of_bytes = eyetracker.apply_licenses([license])
failed_licenses_applied_as_key = eyetracker.apply_licenses(tr.LicenseKey(license))
failed_licenses_applied_as_bytes = eyetracker.apply_licenses(license)

if len(failed_licenses_applied_as_list_of_keys) == 0:
    print("Successfully applied license from list of keys.")
else:
    print("Failed to apply license from list of keys. Validation result: {0}.".
          format(failed_licenses_applied_as_list_of_keys[0].validation_result))

if len(failed_licenses_applied_as_list_of_bytes) == 0:
    print("Successfully applied license from list of bytes.")
else:
    print("Failed to apply license from list of bytes. Validation result: {0}.".
          format(failed_licenses_applied_as_list_of_bytes[0].validation_result))

if len(failed_licenses_applied_as_key) == 0:
    print("Successfully applied license from single key.")
else:
    print("Failed to apply license from single key. Validation result: {0}.".
          format(failed_licenses_applied_as_key[0].validation_result))

if len(failed_licenses_applied_as_bytes) == 0:
    print("Successfully applied license from bytes object.")
else:
    print("Failed to apply license from bytes object. Validation result: {0}.".
          format(failed_licenses_applied_as_bytes[0].validation_result))

Parameters

license_key_ring

List of LicenseKey objects, list of bytes, LicenseKey object or bytes object.

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
AttributeError
TypeError

Returns

Tuple of FailedLicense objects for licenses that failed. Empty tuple if all licenses were successfully applied.

def tobii_research.EyeTracker.clear_applied_licenses

(

self

)

Clears any previously applied licenses.

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

def tobii_research.EyeTracker.get_all_eye_tracking_modes

(

self

)

Gets a tuple of eye tracking modes supported by the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_eye_tracking_mode = eyetracker.get_eye_tracking_mode()

print("The eye tracker's initial eye tracking mode is {0}.".format(initial_eye_tracking_mode))

try:
    for eye_tracking_mode in eyetracker.get_all_eye_tracking_modes():
        eyetracker.set_eye_tracking_mode(eye_tracking_mode)
        print("Eye tracking mode set to {0}.".format(eye_tracking_mode))
finally:
    eyetracker.set_eye_tracking_mode(initial_eye_tracking_mode)
    print("Eye tracking mode reset to {0}.".format(initial_eye_tracking_mode))

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

Tuple of strings with available eye tracking modes.

def tobii_research.EyeTracker.get_all_gaze_output_frequencies

(

self

)

Gets a list of gaze output frequencies supported by the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_gaze_output_frequency = eyetracker.get_gaze_output_frequency()

print("The eye tracker's initial gaze output frequency is {0} Hz.".format(initial_gaze_output_frequency))

try:
    for gaze_output_frequency in eyetracker.get_all_gaze_output_frequencies():
        eyetracker.set_gaze_output_frequency(gaze_output_frequency)
        print("Gaze output frequency set to {0} Hz.".format(gaze_output_frequency))
finally:
    eyetracker.set_gaze_output_frequency(initial_gaze_output_frequency)
    print("Gaze output frequency reset to {0} Hz.".format(initial_gaze_output_frequency))

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

Tuple of floats with all gaze output frequencies.

def tobii_research.EyeTracker.get_display_area

(

self

)

Gets the size and corners of the display area.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

from tobii_research import DisplayArea

display_area = eyetracker.get_display_area()

print("Got display area from tracker with serial number {0}:".format(eyetracker.serial_number))

print("Bottom Left: {0}".format(display_area.bottom_left))
print("Bottom Right: {0}".format(display_area.bottom_right))
print("Height: {0}".format(display_area.height))
print("Top Left: {0}".format(display_area.top_left))
print("Top Right: {0}".format(display_area.top_right))
print("Width: {0}".format(display_area.width))

# To set the display area it is possible to either use a previously saved instance of
# the class Display area, or create a new one as shown bellow.
new_display_area_dict = dict()
new_display_area_dict['top_left'] = display_area.top_left
new_display_area_dict['top_right'] = display_area.top_right
new_display_area_dict['bottom_left'] = display_area.bottom_left

new_display_area = DisplayArea(new_display_area_dict)

eyetracker.set_display_area(new_display_area)

Exceptions

EyeTrackerFeatureNotSupportedError
EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

Display area in the user coordinate system as a DisplayArea object.

def tobii_research.EyeTracker.get_eye_tracking_mode

(

self

)

Gets the eye tracking mode of the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_eye_tracking_mode = eyetracker.get_eye_tracking_mode()

print("The eye tracker's initial eye tracking mode is {0}.".format(initial_eye_tracking_mode))

try:
    for eye_tracking_mode in eyetracker.get_all_eye_tracking_modes():
        eyetracker.set_eye_tracking_mode(eye_tracking_mode)
        print("Eye tracking mode set to {0}.".format(eye_tracking_mode))
finally:
    eyetracker.set_eye_tracking_mode(initial_eye_tracking_mode)
    print("Eye tracking mode reset to {0}.".format(initial_eye_tracking_mode))

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

String with the current eye tracking mode.

def tobii_research.EyeTracker.get_gaze_output_frequency

(

self

)

Gets the gaze output frequency of the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_gaze_output_frequency = eyetracker.get_gaze_output_frequency()

print("The eye tracker's initial gaze output frequency is {0} Hz.".format(initial_gaze_output_frequency))

try:
    for gaze_output_frequency in eyetracker.get_all_gaze_output_frequencies():
        eyetracker.set_gaze_output_frequency(gaze_output_frequency)
        print("Gaze output frequency set to {0} Hz.".format(gaze_output_frequency))
finally:
    eyetracker.set_gaze_output_frequency(initial_gaze_output_frequency)
    print("Gaze output frequency reset to {0} Hz.".format(initial_gaze_output_frequency))

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

Float with the current gaze output frequency.

def tobii_research.EyeTracker.retrieve_calibration_data

(

self

)

Gets the calibration data used currently by the eye tracker.

This data can be saved to a file for later use. See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

filename = "saved_calibration.bin"

# Save the calibration to file.
with open(filename, "wb") as f:
    calibration_data = eyetracker.retrieve_calibration_data()

    # None is returned on empty calibration.
    if calibration_data is not None:
        print("Saving calibration to file for eye tracker with serial number {0}.".format(eyetracker.serial_number))
        f.write(eyetracker.retrieve_calibration_data())
    else:
        print("No calibration available for eye tracker with serial number {0}.".format(eyetracker.serial_number))

# Read the calibration from file.
with open(filename, "rb") as f:
    calibration_data = f.read()

    # Don't apply empty calibrations.
    if len(calibration_data) > 0:
        print("Applying calibration on eye tracker with serial number {0}.".format(eyetracker.serial_number))
        eyetracker.apply_calibration_data(calibration_data)

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

def tobii_research.EyeTracker.set_device_name	(		self,
			device_name
	)

Changes the device name.

This is not supported by all eye trackers. See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

import tobii_research as tr

print("The current name of the eye tracker is {0}".format(eyetracker.device_name))

try:
    eyetracker.set_device_name("A new name")
    print("The eye tracker changed name to {0}".format(eyetracker.device_name))
except tr.EyeTrackerFeatureNotSupportedError:
    print("This eye tracker doesn't support changing the device name.")
except tr.EyeTrackerLicenseError:
    print("You need a higher level license to change the device name.")

Parameters

device_name

The eye tracker's desired name.

Exceptions

EyeTrackerFeatureNotSupportedError
EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

def tobii_research.EyeTracker.set_display_area	(		self,
			display_area
	)

Sets the display area of the eye tracker.

It is strongly recommended to use Eye Tracker Manager to calculate the display area coordinates as the origin of the User Coordinate System differs between eye tracker models. See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

from tobii_research import DisplayArea

display_area = eyetracker.get_display_area()

print("Got display area from tracker with serial number {0}:".format(eyetracker.serial_number))

print("Bottom Left: {0}".format(display_area.bottom_left))
print("Bottom Right: {0}".format(display_area.bottom_right))
print("Height: {0}".format(display_area.height))
print("Top Left: {0}".format(display_area.top_left))
print("Top Right: {0}".format(display_area.top_right))
print("Width: {0}".format(display_area.width))

# To set the display area it is possible to either use a previously saved instance of
# the class Display area, or create a new one as shown bellow.
new_display_area_dict = dict()
new_display_area_dict['top_left'] = display_area.top_left
new_display_area_dict['top_right'] = display_area.top_right
new_display_area_dict['bottom_left'] = display_area.bottom_left

new_display_area = DisplayArea(new_display_area_dict)

eyetracker.set_display_area(new_display_area)

Parameters

display_area

The eye tracker's desired display_area as a DisplayArea object.

Exceptions

EyeTrackerFeatureNotSupportedError
EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

def tobii_research.EyeTracker.set_eye_tracking_mode	(		self,
			eye_tracking_mode
	)

Sets the eye tracking mode of the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_eye_tracking_mode = eyetracker.get_eye_tracking_mode()

print("The eye tracker's initial eye tracking mode is {0}.".format(initial_eye_tracking_mode))

try:
    for eye_tracking_mode in eyetracker.get_all_eye_tracking_modes():
        eyetracker.set_eye_tracking_mode(eye_tracking_mode)
        print("Eye tracking mode set to {0}.".format(eye_tracking_mode))
finally:
    eyetracker.set_eye_tracking_mode(initial_eye_tracking_mode)
    print("Eye tracking mode reset to {0}.".format(initial_eye_tracking_mode))

Parameters

eye_tracking_mode

The eye tracking mode as a string.

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError
ValueError

def tobii_research.EyeTracker.set_gaze_output_frequency	(		self,
			gaze_output_frequency
	)

Sets the gaze output frequency of the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object.

initial_gaze_output_frequency = eyetracker.get_gaze_output_frequency()

print("The eye tracker's initial gaze output frequency is {0} Hz.".format(initial_gaze_output_frequency))

try:
    for gaze_output_frequency in eyetracker.get_all_gaze_output_frequencies():
        eyetracker.set_gaze_output_frequency(gaze_output_frequency)
        print("Gaze output frequency set to {0} Hz.".format(gaze_output_frequency))
finally:
    eyetracker.set_gaze_output_frequency(initial_gaze_output_frequency)
    print("Gaze output frequency reset to {0} Hz.".format(initial_gaze_output_frequency))

Parameters

gaze_output_frequency

The gaze output frequency as a float value.

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError
ValueError

def tobii_research.EyeTracker.subscribe_to	(		self,
			subscription_type,
			callback,
			as_dictionary = False
	)

Subscribes to data for the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object. You can subscribe to EYETRACKER_EXTERNAL_SIGNAL, EYETRACKER_EYE_IMAGES, EYETRACKER_GAZE_DATA, EYETRACKER_USER_POSITION_GUIDE, EYETRACKER_NOTIFICATION_CONNECTION_LOST, EYETRACKER_NOTIFICATION_CONNECTION_RESTORED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_ENTERED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_LEFT, EYETRACKER_NOTIFICATION_CALIBRATION_CHANGED, EYETRACKER_NOTIFICATION_DISPLAY_AREA_CHANGED, EYETRACKER_NOTIFICATION_GAZE_OUTPUT_FREQUENCY_CHANGED, EYETRACKER_NOTIFICATION_EYE_TRACKING_MODE_CHANGED, EYETRACKER_NOTIFICATION_DEVICE_FAULTS, EYETRACKER_NOTIFICATION_DEVICE_WARNINGS, EYETRACKER_NOTIFICATION_STREAM_BUFFER_OVERFLOW EYETRACKER_TIME_SYNCHRONIZATION_DATA or EYETRACKER_STREAM_ERRORS.

import logging
import time
import tobii_research as tr

global_gaze_data = None


def gaze_data_callback(gaze_data):
    global global_gaze_data
    global_gaze_data = gaze_data


def buffer_overflow_notifications_callback(notification_data):
    logging.error(
        f"Buffer overflow occurred at system time: {notification_data['system_time_stamp']}"
    )


def gaze_data(eyetracker):
    global global_gaze_data

    print("Subscribing to gaze data for eye tracker with serial number {0}.".format(eyetracker.serial_number))
    eyetracker.subscribe_to(tr.EYETRACKER_GAZE_DATA, gaze_data_callback, as_dictionary=True)

    # listen for buffer overflow notifications (to see e.g. if the gaze callback is too slow)
    eyetracker.subscribe_to(
        tr.EYETRACKER_NOTIFICATION_STREAM_BUFFER_OVERFLOW,
        buffer_overflow_notifications_callback,
        as_dictionary=True
    )

    # Wait while some gaze data is collected.
    time.sleep(2)

    eyetracker.unsubscribe_from(tr.EYETRACKER_GAZE_DATA, gaze_data_callback)
    print("Unsubscribed from gaze data.")

    print("Last received gaze package:")
    print(global_gaze_data)

Parameters

subscription_type	Type of data to subscribe to.
callback	Callback receiveing the data. See documentation of subscription types for details.
as_dictionary	If True, the callback will receive a dictionary with values instead of a custom object.

def tobii_research.EyeTracker.unsubscribe_from	(		self,
			subscription_type,
			callback = None
	)

Unsubscribes from data for the eye tracker.

See find_all_eyetrackers or EyeTracker.__init__ on how to create an EyeTracker object. You can unsubscribe from EYETRACKER_EXTERNAL_SIGNAL, EYETRACKER_EYE_IMAGES, EYETRACKER_GAZE_DATA, EYETRACKER_USER_POSITION_GUIDE, EYETRACKER_NOTIFICATION_CONNECTION_LOST, EYETRACKER_NOTIFICATION_CONNECTION_RESTORED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_ENTERED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_LEFT, EYETRACKER_NOTIFICATION_CALIBRATION_CHANGED, EYETRACKER_NOTIFICATION_DISPLAY_AREA_CHANGED, EYETRACKER_NOTIFICATION_GAZE_OUTPUT_FREQUENCY_CHANGED, EYETRACKER_NOTIFICATION_EYE_TRACKING_MODE_CHANGED, EYETRACKER_NOTIFICATION_DEVICE_FAULTS, EYETRACKER_NOTIFICATION_DEVICE_WARNINGS, EYETRACKER_NOTIFICATION_STREAM_BUFFER_OVERFLOW EYETRACKER_TIME_SYNCHRONIZATION_DATA or EYETRACKER_STREAM_ERRORS.

import logging
import time
import tobii_research as tr

global_gaze_data = None


def gaze_data_callback(gaze_data):
    global global_gaze_data
    global_gaze_data = gaze_data


def buffer_overflow_notifications_callback(notification_data):
    logging.error(
        f"Buffer overflow occurred at system time: {notification_data['system_time_stamp']}"
    )


def gaze_data(eyetracker):
    global global_gaze_data

    print("Subscribing to gaze data for eye tracker with serial number {0}.".format(eyetracker.serial_number))
    eyetracker.subscribe_to(tr.EYETRACKER_GAZE_DATA, gaze_data_callback, as_dictionary=True)

    # listen for buffer overflow notifications (to see e.g. if the gaze callback is too slow)
    eyetracker.subscribe_to(
        tr.EYETRACKER_NOTIFICATION_STREAM_BUFFER_OVERFLOW,
        buffer_overflow_notifications_callback,
        as_dictionary=True
    )

    # Wait while some gaze data is collected.
    time.sleep(2)

    eyetracker.unsubscribe_from(tr.EYETRACKER_GAZE_DATA, gaze_data_callback)
    print("Unsubscribed from gaze data.")

    print("Last received gaze package:")
    print(global_gaze_data)

Parameters

subscription_type	Type of data to unsubscribe from.
callback	Callback sent to subscribe_to or None to unsubscribe all subscriptions of this type.