Matlab - 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 MATLAB 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

Class Member Type Class Member Type
tetio_init Method No equivalent N/A
tetio_cleanup Method No equivalent N/A
No equivalent EyeTrackerService Class
tetio_getTrackers Method find_all_eyetrackers Method
tetio_connectTracker Method No equivalent - Changed functionality N/A
tetio_disconnectTracker Method No equivalent - Changed functionality N/A
No equivalent EyeTracker Class
tetio_enumerateFrameRates Method get_all_output_frequencies Method
tetio_setFrameRate Method set_output_frequency Method
tetio_getFrameRate Method get_output_frequency Method
No equivalent N/A get_all_eye_tracking_modes Method
No equivalent N/A set_eye_tracking_mode  Method
No equivalent N/A get_eye_tracking_mode Method
No equivalent - Changed functionality N/A retrieve_calibration_data Method
No equivalent - Changed functionality N/A apply_calibration_data Method
tetio_startTracking Method No equivalent N/A
tetio_stopTracking Method No equivalent N/A
tetio_readGazeData Method get_gaze_data Method
No equivalent N/A stop_gaze_data Method
No equivalent - Changed functionality N/A get_time_sync_data Method
No equivalent N/A stop_time_sync_data Method
No equivalent - New functionality N/A apply_licenses Method
No equivalent - New functionality N/A get_display_area Method
No equivalent N/A get_track_box Method
No equivalent N/A ScreenBasedCalibration Class
tetio_addCalibPoint Method collect_data Method
tetio_removeCalibPoint Method discard_data Method
tetio_clearCalib Method No equivalent - See enter_calibration_mode
tetio_computeCalib Method compute_and_apply Method
tetio_getCalibPlotData Method No equivalent - Changed functionality N/A
tetio_startCalib + tetio_clearCalib Method enter_calibration_mode Method
tetio_stopCalib Method leave_calibration_mode Method
tetio_clockSyncState Method No equivalent - Changed functionality N/A
tetio_localClockResolution Method No equivalent - Changed functionality N/A
tetio_localTimeNow Method No equivalent - Changed functionality N/A
tetio_localToRemoteTime Method No equivalent - Changed functionality N/A
tetio_remoteToLocalTime Method No equivalent - Changed functionality N/A
EyeTrackerInfoStruct Struct (EyeTracker) Class
ProductId Property SerialNumber Property (readonly)
Model Property Model Property (readonly)
GivenName Property Name Property (readonly)
Generation Property No equivalent - Removed functionality N/A
FirmwareVersion Property FirmwareVersion Property (readonly)
Status Property No equivalent - Changed functionality N/A
No equivalent N/A Address Property (readonly)
CalibrationPlotArray CalibrationResult Class
truePosition (.x/.y) Field CalibrationPoint.PositionOnDisplayArea Property (readonly)
leftMapPosition (.x/.y) Field LeftEye.PositionOnDisplayArea Property (readonly)
leftStatus Field LeftEye.Validity Property (readonly)
rightMapStatus (.x/.y) Field RightEye.PositionOnDisplayArea Property (readonly)
rightStatus Field RightEye.Validity Property (readonly)
GazeDataArray GazeData Class
Left eye data Field LeftEye Property (readonly)
Right eye data Field RightEye Property (readonly)
Eye tracker time stamp Field DeviceTimeStamp Property (readonly)
No equivalent N/A SystemTimeStamp Property (readonly)
trigSignal Field See ExternalSignalData
EyeArray EyeData Class
EyePosition3D (.x/.y/.z) Field GazeOrigin.InUserCoordinateSystem Property (readonly)
EyePosition3DRelative (.x/.y/.z) Field GazeOrigin.InTrackBoxCoordinateSystem Property (readonly)
GazePoint2D (.x/.y) Field GazePoint.OnDisplayArea Property (readonly)
GazePoint3D(.x/.y/.z) Field GazePoint.InUserCoordinateSystem Property (readonly)
PupilDiameter Field Pupil.Diameter Property (readonly)
Validity Field No equivalent - Changed functionality N/A
No equivalent  N/A  DisplayArea Class
No equivalent N/A bottom_left Property (readonly)
No equivalent N/A bottom_right Property (readonly)
No equivalent N/A height Property (readonly)
No equivalent N/A top_left Property (readonly)
No equivalent N/A top_right Property (readonly)
No equivalent N/A width Property (readonly)
No equivalent N/A TimeSynchronizationData Class
No equivalent N/A system_request_time_stamp Property (readonly)
No equivalent N/A device_time_stamp Property (readonly)
No equivalent N/A system_response_time_stamp Property (readonly)
No equivalent N/A ExternalSignalData Class
No equivalent N/A change_type Property (readonly)
No equivalent N/A value Property (readonly)
No equivalent N/A device_time_stamp Property (readonly)
No equivalent N/A system_time_stamp Property (readonly)