Python - Migrating from earlier Tobii Pro Analytics SDKs

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 Tobii Pro SDK does require some modifications to the code, we do believe that the Tobii 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 Tobii Pro SDK.

Working with an eye tracker

Some changes have been made in the Tobii 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 Tobii 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 Tobii 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 Tobii 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 Tobii 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		`set_display_area`	Method
	`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 Tobii Pro 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 Tobii Pro 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 Tobii Pro Eye Tracker Manager	N/A
	`begin_upgrade`	Method		Functionality moved - Use the Tobii Pro Eye Tracker Manager	N/A
	`package_is_compatible_with_device`	Method		Functionality moved - Use the Tobii Pro 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

Migrating from earlier Tobii Pro Analytics SDKs