Migrating from earlier Tobii Pro Analytics SDKs

This guide assumes that you previously have used Tobii Pro Analytics SDK Release 3.0. If you instead have been using an earlier version of that SDK, we recommend that you refer to the documentation for the Tobii Pro Analytics SDK Release 3.0 about changes between that and previous versions before aiming to migrate to the Tobii Pro SDK.

A general introduction to the differences between the Tobii Pro SDK and Tobii Pro Analytics SDK 3 can be found at Changes from Tobii Pro Analytics SDK 3 and should be read before any attempt to migrate is made.

Read before coding

The general functionality in the old and the new SDK is the same. However, some changes have been made to the structure as well of naming of classes and methods. The purpose of these changes is to make the SDK more futureproof as well as easier to use for new users. While migrating from the previous SDK to the Pro SDK does require some modifications to the code, we do believe that the Pro SDK also will be easier to use for users who have previously been using the Pro Analytics SDK. In the following sections we have listed the changes that will have direct impact on your code and needs to be updated in order to migrate from previous SDK to the Pro SDK.

Working with an eye tracker

Some changes have been made in the Pro SDK to how a connection to an eye tracker is established compared to the Pro Analytics SDK 3.

Finding an eye tracker locally or on a network

Instead of having to subscribe to notifications for whenever an eye tracker appears or disappears from the network or local connection which was the case in the Pro Analytics SDK 3, the Pro SDK instead provides a list of connected eye trackers upon request. This simplifies initial detection of eye trackers, but requires the implementation of a regular check if the network or connection to the eye trackers is unstable.

Interacting with an eye tracker

While you previously had to interact with instances of two different classes in order to get info about and do something with an eye tracker in the Pro Analytics SDK 3 you can now, in the Pro SDK, do the same with only one EyeTracker object. Please refer to the reference library for more details about the EyeTracker object or Getting started for information about how to start using it.

Calibrating the eye tracker with a user

While information about the eye tracker and some interaction with it is now done using the EyeTracker class, the act of calibration as well as the calibration data created are now handled using an object from the new ScreenBasedCalibration class.

Another change from the Pro Analytics SDK 3 is that the calibration results now are returned in the form of CalibrationPoint objects representing each calibration point individually. Each object contains the location of the point in Active Display Coordinate System coordinates of where it was displayed as well as tuple of CalibrationSample objects collected and calculated for that point.

Read more about how a calibration works in the Calibration section and the ScreenBasedCalibration class in the Python reference library.

Timing and synchronization

In order to be able to interpret the data collected by the eye tracker in the context of something else, e.g. presented stimuli or data from other sources such as EEG, it is important that the data is synced in time with whatever it is going to be analysed in conjunction with. When collecting the data, there are generally two different clocks involved: the clock inside the eye tracker and the clock in the computer where the SDK application is running. Both are represented in the time stamps put on the eye tracking data collected.

In the Pro Analytics SDK 3, the responsibility for making sure the time stamps of the two clocks were true, i.e. that the system compensated for drift between the clocks, were put on the developer using the SDK. In the Pro SDK, this has instead been implemented in a way that does the synchronization automatically on a regular basis and only sends notification events when the synchronization is done. This means that when interpreting the data later, it does not matter if the eye tracker clock time stamp (called device_time_stamp) or the computer clock time stamp (called system_time_stamp) is used to align data from different data sources- both time stamps are equally trustworthy.

Validity

In previous SDKs, a value between 0 to 4 was used to signify either the certainty of which eye the data was collected from or if there was any data at all in a gaze data package. In the Pro SDK all different data types, e.g. gaze point, gaze origin and pupil data, had its own validity field telling if the data is valid or not. To learn more about this, please refer to the section Validity codes on this site.

Name changes to classes and methods

Here you find the largest visible difference compared with previous SDKs. The aim has been to find names of classes, methods, functions and parameters that would feel natural for any developer. In previous SDKs, definitions primarily used by developers within Tobii were also included in the public SDK which sometimes led to confusion and inability to use the SDK to its full potential. Hence, in the Tobii Pro SDK steps have been taken to select self explanatory names, but also to avoid including things not useful for a public audience.

Please review the table below to see if you need to update your code regarding names or uses of classes and functions.

Tobii Analysis SDK 3

Tobii Pro SDK

Namespace Namespace
tobii.eye_tracking_io tobii_research
Class Member Type Class Member Type
Clock Class No equivalent - Changed structure N/A
get_resolution Method No equivalent - See get_system_time_stamp N/A
get_time Method No equivalent - See get_system_time_stamp N/A
Mainloop Class No equivalent - Changed structure N/A
quit Method No equivalent - Changed functionality N/A
run Method No equivalent - Changed functionality N/A
MainloopThread Class No equivalent - Changed structure N/A
start Method No equivalent - Changed functionality N/A
stop Method No equivalent - Changed functionality N/A
State Class No equivalent - Changed structure N/A
get_error_approximation Method No equivalent - Removed functionality N/A
points_in_use Method No equivalent - Removed functionality N/A
state_flag Method No equivalent - Removed functionality N/A
SyncManager Class No equivalent - See TimeSynchronizationData N/A
convert_from_local_to_remote Method No equivalent - Changed structure N/A
convert_from_remote_to_local Method No equivalent - Changed structure N/A
SyncManager Class No equivalent - See TimeSynchronizationData N/A
EyeTracker EyeTracker
No equivalent N/A apply_licenses Method
GetCalibration Method retrieve_calibration_data Method
SetCalibration Method apply_calibration_data Method
EnumerateFramerates Method get_all_gaze_output_frequencies Method
EnumerateIlluminationModes Method get_all_eye_tracking_modes Method
GetFramerate Method get_gaze_output_frequency Method
GetTrackBox Method get_track_box Method
GetIlluminationMode Method get_eye_tracking_mode Method
GetLowblinkMode Method Merged functionality - See get_eye_tracking_mode N/A
GetUnitInfo Method No equivalent - Changed functionality N/A
GetUnitName Method No equivalent - See EyeTracker.device_name Property
GetXConfiguration Method get_display_area Method
SetFramerate Method set_gaze_output_frequency Method
SetIlluminationMode Method set_eye_tracking_mode Method
SetLowblinkMode Method Merged functionality - See set_eye_tracking_mode N/A
SetUnitName Method set_device_name Method
SetXConfiguration Method Functionality moved - Use the Eye Tracker Manager N/A
StartTracking Method subscribe_to EYETRACKER_GAZE_DATA Callback
StopTracking Method unsubscribe_from EYETRACKER_GAZE_DATA Method
get_gaze_data_column Method No equivalent - See GazeData.left_eye and right_eye N/A
has_gaze_data_column Method No equivalent - Removed functionality N/A
create_async Method No equivalent - Removed functionality N/A
DumpImages Method Functionality moved - Use Eye Tracker Manager N/A
EnableExtension Method No equivalent - Removed functionality N/A
GetAuthorizeChallenge Method No equivalent - Removed functionality N/A
GetAvailableExtensions Method No equivalent - Removed functionality N/A
GetDiagnosticReport Method Functionality moved- Use Eye Tracker Manager N/A
GetEnabledExtensions Method No equivalent - Removed functionality N/A
GetPayperuseInfo Method No equivalent - Removed functionality N/A
ValidateChallengeResponse Method No equivalent - Removed functionality N/A
EyeTracker Class ScreenBasedCalibration Class
AddCalibrationPoint Method collect_data Method
ClearCalibration Method No equivalent - Removed functionality (see enter_calibration_mode) N/A
ComputeCalibration Method compute_and_apply Method
RemoveCalibrationPoint Method discard_data Method
StartCalibration Method enter_calibration_mode (equivalent to StartCalibration + ClearCalibration) Method
StopCalibration Method leave_calibration_mode Method
EyetrackerInfo EyeTracker
product_id Property serial_number Property
given_name Property device_name Property
model Property model Property
generation Property No equivalent - Removed functionality N/A
firmware_version Property firmware_version Property
status Property No equivalent - Removed functionality N/A
factory_info Property No equivalent - Removed functionality N/A
EyetrackerBrowser Class
start Method find_all_eyetrackers Method
stop No equivalent - See find_all_eyetrackers N/A
No equivalent class EyeTracker.subcribe_to Method
OnCalibrationStarted EYETRACKER_NOTIFICATION_CALIBRATION_MODE_ENTERED Callback
OnCalibrationStopped EYETRACKER_NOTIFICATION_CALIBRATION_MODE_LEFT Callback
EyetrackerEvents EyeTracker.subcribe_to Method
OnFramerateChanged EYETRACKER_NOTIFICATION_GAZE_OUTPUT_FREQUENCY_CHANGED Callback
OnTrackBoxChanged EYETRACKER_NOTIFICATION_TRACK_BOX_CHANGED Callback
OnXConfigurationChanged EYETRACKER_NOTIFICATION_DISPLAY_AREA_CHANGED Callback
OnGazeDataReceived EYETRACKER_GAZE_DATA Callback
OnError EYETRACKER_STREAM_ERRORS Callback
No equivalent - Changed functionality N/A EYETRACKER_EXTERNAL_SIGNAL Callback
No equivalent - New functionality N/A EYETRACKER_EYE_IMAGES Callback
No equivalent - New functionality N/A EYETRACKER_NOTIFICATION_CONNECTION_LOST Callback
No equivalent - New functionality N/A EYETRACKER_NOTIFICATION_CONNECTION_RESTORED Callback
No equivalent - New functionality N/A EYETRACKER_TIME_SYNCHRONIZATION_DATA Callback
 No equivalent CalibrationEyeData
position_on_display_area Property
validity Property
 No equivalent CalibrationPoint
position_on_display_area Property
calibration_samples (CalibrationSample) Property
 No equivalent N/A CalibrationResult Class
status Property
calibration_points (CalibrationPoint) Property
 No equivalent N/A CalibrationSample
left_eye (CalibrationEyeData) Property
right_eye (CalibrationEyeData) Property
EyetrackerException Exceptions
error No equivalent - See class Exception N/A
No equivalent N/A EyeTrackerConnectionFailedError Class
No equivalent N/A EyeTrackerFeatureNotSupportedError Class
No equivalent N/A EyeTrackerInternalError Class
No equivalent N/A EyeTrackerInvalidOperationError Class
No equivalent N/A EyeTrackerLicenseError Class
No equivalent N/A EyeTrackerOperationFailedError Class
No equivalent N/A EyeTrackerUnavilableError Class
No equivalent N/A EyeTrackerDisplayAreaNotValidError Class
No equivalent N/A EyeTrackerSavedLicenseFailedToApplyError Class
GazeDataItem
Timestamp GazeData device_time_stamp Property
LeftEyePosition3D GazeOrigin left_eye position_in_user_coordinates Property
LeftEyePosition3DRelative GazeOrigin left_eye position_in_track_box_coordinates Property
LeftGazePoint2D GazePoint left_eye position_on_display_area Property
LeftGazePoint3D GazePoint left_eye position_in_user_coordinates Property
LeftPupil PupilData left_eye pupil diameter Property
LeftValidity PupilData left_eye pupil validity  Property
RightEyePosition3D GazeOrigin right_eye position_in_user_coordinates Property
RightEyePosition3DRelative GazeOrigin right_eye position_in_track_box_coordinates Property
RightGazePoint2D GazePoint right_eye position_on_display_area Property
RightGazePoint3D GazePoint right_eye position_in_user_coordinates Property
RightPupil PupilData right_eye pupil diameter Property
RightValidity PupilData right_eye pupil validity Property
TrigSignal See ExternalSignalData
Upgrade Functionality moved - Use the Eye Tracker Manager N/A
begin_upgrade Method Functionality moved - Use the Eye Tracker Manager N/A
package_is_compatible_with_device Method Functionality moved - Use the Eye Tracker Manager N/A
No equivalent N/A DisplayArea
bottom_left Property
bottom_right Property
height Property
top_left Property
top_right Property
width Property
No equivalent N/A TimeSynchronizationData
system_request_time_stamp Property
device_time_stamp Property
system_response_time_stamp Property
No equivalent N/A ExternalSignalData
change_type Property
value Property
device_time_stamp Property
system_time_stamp Property