tobii_research.EyeTracker Class Reference

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

Inherits object.

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_track_box (self)
	Gets the track box of the eye tracker. More...
def	get_display_area (self)
	Gets the size and corners of the display area. 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...

Data Fields
	address
	Gets the address (URI) of the eye tracker device.
	device_name
	Gets the name of the eye tracker.
	serial_number
	Gets the serial number of the eye tracker. More...
	model
	Gets the model of the eye tracker.
	firmware_version
	Gets the firmware version of the eye tracker.
	device_capabilities
	Gets a tuple with the capabilities of the device. 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://12.13.14.15"
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.")

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.

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)

Exceptions

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

(

self

)

Gets the track box of the eye tracker.

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

track_box = eyetracker.get_track_box()

print "Got track box from tracker with serial number {0} with corners:".format(eyetracker.serial_number)

print "Back Lower Left: {0}".format(track_box.back_lower_left)
print "Back Lower Right: {0}".format(track_box.back_lower_right)
print "Back Upper Left: {0}".format(track_box.back_upper_left)
print "Back Upper Right: {0}".format(track_box.back_upper_right)
print "Front Lower Left: {0}".format(track_box.front_lower_left)
print "Front Lower Right: {0}".format(track_box.front_lower_right)
print "Front Upper Left: {0}".format(track_box.front_upper_left)
print "Front Upper Right: {0}".format(track_box.front_upper_right)

Exceptions

EyeTrackerConnectionFailedError
EyeTrackerInternalError
EyeTrackerLicenseError

Returns

Track box in the user coordinate system as a TrackBox object.

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_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_GAZE_DATA, EYETRACKER_NOTIFICATION_CONNECTION_LOST, EYETRACKER_NOTIFICATION_CONNECTION_RESTORED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_ENTERED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_LEFT, EYETRACKER_NOTIFICATION_TRACK_BOX_CHANGED, EYETRACKER_NOTIFICATION_DISPLAY_AREA_CHANGED, EYETRACKER_NOTIFICATION_GAZE_OUTPUT_FREQUENCY_CHANGED, EYETRACKER_TIME_SYNCHRONIZATION_DATA or EYETRACKER_STREAM_ERRORS.

import time
import tobii_research as tobii_eyetracking

global_gaze_data = None


def gaze_data_callback(gaze_data):
    global global_gaze_data
    global_gaze_data = gaze_data


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(tobii_eyetracking.EYETRACKER_GAZE_DATA, gaze_data_callback, as_dictionary=True)

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

    eyetracker.unsubscribe_from(tobii_eyetracking.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_GAZE_DATA, EYETRACKER_NOTIFICATION_CONNECTION_LOST, EYETRACKER_NOTIFICATION_CONNECTION_RESTORED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_ENTERED, EYETRACKER_NOTIFICATION_CALIBRATION_MODE_LEFT, EYETRACKER_NOTIFICATION_TRACK_BOX_CHANGED, EYETRACKER_NOTIFICATION_DISPLAY_AREA_CHANGED, EYETRACKER_NOTIFICATION_GAZE_OUTPUT_FREQUENCY_CHANGED, EYETRACKER_TIME_SYNCHRONIZATION_DATA or EYETRACKER_STREAM_ERRORS.

import time
import tobii_research as tobii_eyetracking

global_gaze_data = None


def gaze_data_callback(gaze_data):
    global global_gaze_data
    global_gaze_data = gaze_data


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(tobii_eyetracking.EYETRACKER_GAZE_DATA, gaze_data_callback, as_dictionary=True)

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

    eyetracker.unsubscribe_from(tobii_eyetracking.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.

Field Documentation

tobii_research.EyeTracker.device_capabilities

Gets a tuple with the capabilities of the device.

Valid values in the tuple are CAPABILITY_CAN_SET_DISPLAY_AREA, CAPABILITY_HAS_EXTERNAL_SIGNAL and CAPABILITY_HAS_EYE_IMAGES.

tobii_research.EyeTracker.serial_number

Gets the serial number of the eye tracker.

All physical eye trackers have a unique serial number.