Migrating from Tobii SDKs

Tobii has released multiple SDKs prior to this one, both for analytical use, and for interactive use. This guide tries to make a migration from any of these to the new Tobii Pro SDK as easy as possible.

Migrating from earlier Tobii Pro SDKs

Migrating from Tobii Gaze SDK

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. If, instead, you have been using the Tobii Gaze SDK, please refer to the Migrating from Tobii Gaze SDK guide further down this page.

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, as you have probably noticed, the new Tobii Pro SDK only has a language binding for C, whereas Tobii Pro Analytics SDK 3 had a C++ binding. This means that the object-oriented structure of Tobii Pro Analytics SDK 3 has had to give way to a simpler function-based structure. To make navigation easier, and to increase readability, the interface has been split over several header files. Furthermore, some changes have been made to the structure as well of naming of functions and values.

The purpose of these structure and name 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 your existing code, we do believe that the Pro SDK still will be easier to use, even 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.

Calibrating the eye tracker with a user

One change from the Pro Analytics SDK 3 is that the calibration results now are returned in the form of TobiiResearchCalibrationPoint objects structs each calibration point individually. Each struct contains the location of the point in Active Display Coordinate System coordinates of where it was displayed as well as an array of TobiiResearchCalibrationSample structs collected and calculated for that point.

Read more about how a calibration works in the Calibration section and the tobii_research_calibration.h header file in the C 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/prefix
tobii.sdk.cpp tobii_research
Class Member Type Header file Member Type
Clock Class No equivalent - Changed structure N/A
getResolution Method No equivalent - See get_system_time_stamp N/A
getTime 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
SyncState Class No equivalent - Changed structure N/A
getSyncPoints Method No equivalent - Removed functionality N/A
getSyncStateFlag Method No equivalent - Removed functionality N/A
SyncManager Class No equivalent - See TimeSynchronizationData N/A
localToRemote Method No equivalent - Changed structure N/A
remoteToLocal Method No equivalent - Changed structure N/A
getSyncState Method No equivalent - Changed structure N/A
addSyncStateChangedListener Method No equivalent - Changed structure N/A
EyeTracker tobii_research_eyetracker.h
No equivalent N/A tobii_research_apply_licenses Function
getCalibration Method tobii_research_retrieve_calibration_data Function
setCalibration Method tobii_research_apply_calibration_data Function
enumerateFramerates Method tobii_research_get_all_gaze_output_frequencies Function
enumerateIlluminationModes Method tobii_research_get_all_eye_tracking_modes Function
getFramerate Method tobii_research_get_gaze_output_frequency Function
getTrackBox Method tobii_research_get_track_box Function
getIlluminationMode Method tobii_research_get_eye_tracking_mode Function
getLowblinkMode Method Merged functionality - See tobii_research_get_eye_tracking_mode N/A
getUnitInfo Method No equivalent - Changed functionality N/A
getUnitName Method tobii_research_get_device_name Function
getXConfiguration Method tobii_research_get_display_area Function
setFramerate Method tobii_research_set_gaze_output_frequency Function
setIlluminationMode Method tobii_research_set_eye_tracking_mode Function
setLowblinkMode Method Merged functionality - See tobii_research_set_eye_tracking_mode N/A
setUnitName Method tobii_research_set_device_name Function
setXConfiguration Method Functionality moved - Use the Eye Tracker Manager N/A
startTracking Method tobii_research_streams.h tobii_research_subscribe_to_gaze_data Function
stopTracking Method tobii_research_unsubscribe_from_gaze_data Function
addGazeDataReceivedListener Method Changed functionality - See tobii_research_subscribe_to_gaze_data N/A
addFrameRateChangedListener Method No equivalent - See tobii_research_subscribe_to_notifications N/A
addTrackboxChangedListener Method No equivalent - See tobii_research_subscribe_to_notifications N/A
addCalibrationStartedListener Method No equivalent - See tobii_research_subscribe_to_notifications N/A
addCalibrationStoppedListener Method No equivalent - See tobii_research_subscribe_to_notifications N/A
Eyetracker (special methods) Class No equivalent - Use Eye Tracker Manager
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 tobii_research_calibration.h Header file
addCalibrationPoint Method tobii_research_screen_based_calibration_collect_data Function
addCalibrationPointAsync Method No equivalent - see tobii_research_screen_based_calibration_collect_data N/A
clearCalibration Method No equivalent - Removed functionality (see enter_calibration_mode) N/A
computeCalibration Method tobii_research_screen_based_calibration_compute_and_apply Function
computeCalibrationAsync Method No equivalent - see tobii_research_screen_based_calibration_compute_and_apply N/A
removeCalibrationPoint Method tobii_research_screen_based_calibration_discard_data Function
startCalibration Method tobii_research_screen_based_calibration_enter_calibration_mode (equivalent to StartCalibration + ClearCalibration) Function
stopCalibration Method tobii_research_screen_based_calibration_leave_calibration_mode Function
Calibration Class tobii_research_calibration.h Header file
getPlotData Method Merged functionality - see tobii_research_screen_based_calibration_compute_and_apply N/A
getRawData Method Functionality moved - see tobii_research_retrieve_calibration_data Function
EyetrackerInfo Class tobii_research_eyetracker.h Header file
getProductId Method tobii_research_get_serial_number Function
getGivenName Method tobii_research_get_device_name Function
getModel Method tobii_research_get_model Function
getGeneration Method No equivalent - Removed functionality N/A
getVersion Method tobii_research_get_firmware_version Function
getStatus Method No equivalent - Removed functionality N/A
getFactoryInfo Property No equivalent - Removed functionality N/A
No equivalent - New functionality N/A tobii_research_get_capabilities Function
EyetrackerBrowser Class tobii_research.h Header file
start Method tobii_research_find_all_eyetrackers Function
stop No equivalent - See tobii_research_find_all_eyetrackers N/A
addEventListener Method No equivalent - See tobii_research_find_all_eyetrackers N/A
GazeDataItem Class tobii_research_streams.h TobiiResearchGazeData Struct
timestamp TobiiResearchGazeData device_time_stamp int64_t
leftEyePosition3D left_eye.gaze_origin position_in_user_coordinates TobiiResearchPoint3D
leftEyePosition3DRelative left_eye.gaze_point position_in_track_box_coordinates TobiiResearchNormalizedPoint3D
leftGazePoint2D left_eye.gaze_point position_on_display_area TobiiResearchNormalizedPoint2D
leftGazePoint3D left_eye.gaze_point position_in_user_coordinates TobiiResearchPoint3D
leftPupil left_eye.pupilData diameter float
leftValidity left_eye.pupilData validity  TobiiResearchValidity
rightEyePosition3D right_eye.gaze_origin position_in_user_coordinates TobiiResearchPoint3D
rightEyePosition3DRelative right_eye.gaze_origin position_in_track_box_coordinates TobiiResearchNormalizedPoint3D
rightGazePoint2D right_eye.gaze_point position_on_display_area TobiiResearchNormalizedPoint2D
rightGazePoint3D right_eye.gaze_point position_in_user_coordinates TobiiResearchPoint3D
rightPupil right_eye.pupilData pupil diameter float
rightValidity right_eye.pupilData pupil validity TobiiResearchValidity
tryGetExtensionValue Method Functionality moved - see tobii_research_subscribe_to_external_signal_data
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
EyeTrackerBrowserFactory Functionality moved - see tobii_research_find_all_eyetrackers N/A
createBrowser Method Functionality moved - see tobii_research_find_all_eyetrackers N/A
createFactoryInfoByIpAddress Method Functionality moved - see tobii_research_get_eyetracker N/A
createFactoryInfoByName Method No equivalent - Removed functionality N/A
EyeTrackerFactory Functionality moved - see tobii_research_find_all_eyetrackers N/A
getRepresentation Method Functionality moved - see tobii_research_get_address N/A
createEyeTracker Method Functionality moved - see tobii_research_find_all_eyetrackers N/A
createSyncManager Method No equivalent - Removed functionality N/A

Migrating from Tobii Gaze SDK

Read this guide if you have previously been using Tobii Gaze SDK.

Read before coding

The general functionality of the Gaze SDK and the new Tobii Pro SDK is the same. In the following sections we have listed the changes that will have direct impact on your code and what you will need to update in order to migrate from Tobii Gaze SDK to Tobii Pro SDK.

Working with an eye tracker

The functionality for discovery of eye trackers is the same between the Gaze SDK and the Pro SDK however the method name and signature has changed. See the table below. There is no api methods in the Pro SDK to connect or disconnect to different eye trackers, this is handled automatically by the Pro SDK.

Threading

In contrast to the Gaze SDK, the Pro SDK does not have any api methods for event loops. Instead the Pro SDK will start internal threads, polling data received from the eye tracker, when needed. Thus, there is no need to start threads of your own to poll for gaze, or any other, data.

Validity

In the Gaze SDK, a value between 0 to 6 was used to signify the certainty of which eye the data was collected from and 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, have their own validity fields telling if the data is valid or not. To learn more about this, please refer to the section Validity codes on this site, or see the data type structs in tobii_research_streams.h.

Name changes to methods

Here you find the largest visible difference compared with the Gaze SDK. Please review the table below to see how you need to update your code regarding names or uses of classes and functions.

Tobii Gaze SDK

Tobii Pro SDK

Namespace/prefix Namespace/prefix
tobiigaze tobii_research
Header file Member Type Header file Member Type
tobiiigaze.h tobiigaze_create Method tobii_research.h No equivalent N/A
tobiigaze_destroy Method No equivalent N/A
tobiigaze_register_error_callback Method tobii_research_streams.h tobii_research_subscribe_to_stream_errors Method
tobiigaze_get_version Method tobii_research.h tobii_research_get_sdk_version Method
tobiigaze_set_logging Method tobii_research_logging_subscribe Method
tobiigaze_set_standard_output_logging Method No equivalent N/A
tobiigaze_connect_async Method No equivalent N/A
tobiigaze_connect Method No equivalent N/A
tobiigaze_disconnect_async Method No equivalent N/A
tobiigaze_disconnect Method No equivalent N/A
tobiigaze_run_event_loop Method No equivalent N/A
tobiigaze_run_event_loop_on_internal_thread Method No equivalent N/A
tobiigaze_break_event_loop Method No equivalent N/A
tobiigaze_start_tracking_async Method tobii_research_streams.h tobii_research_subscribe_to_gaze_data Method
tobiigaze_start_tracking Method tobii_research_subscribe_to_gaze_data Method
tobiigaze_stop_tracking_async Method tobii_research_unsubscribe_from_gaze_data Method
tobiigaze_stop_tracking Method tobii_research_unsubscribe_from_gaze_data Method
tobiigaze_get_device_info_async Method tobii_research_eyetracker.h Functionality moved - See tobii_research_get_serial_number, tobii_research_get_model, tobii_research_get_firmware_version N/A
tobiigaze_get_device_info Method Functionality moved - See tobii_research_get_serial_number, tobii_research_get_model, tobii_research_get_firmware_version N/A
tobiigaze_get_track_box_async Method tobii_research_get_track_box Method
tobiigaze_get_track_box Method tobii_research_get_track_box Method
tobiigaze_get_geometry_mounting_async Method No equivalent N/A
tobiigaze_register_key_provider Method tobii_research_apply_licenses Method
tobiigaze_get_url Method tobii_research_get_address Method
tobiigaze_is_connected Method No equivalent N/A
tobiigaze_get_error_message Method No equivalent N/A
tobiigaze_calibration.h tobiigaze_calibration_start_async Method tobii_research_calibration.h tobii_research_screen_based_calibration_enter_calibration_mode Method
tobiigaze_calibration_stop_async Method tobii_research_screen_based_calibration_leave_calibration_mode Method
tobiigaze_calibration_add_point_async Method tobii_research_screen_based_calibration_collect_data Method
tobiigaze_calibration_remove_point_async Method tobii_research_screen_based_calibration_discard_data Method
tobiigaze_calibration_clear Method No equivalent N/A
tobiigaze_calibration_compute_and_set_async Method tobii_research_screen_based_calibration_compute_and_apply Method
tobiigaze_get_calibration_async Method tobii_research_eyetracker.h tobii_research_retrieve_calibration_data Method
tobiigaze_set_calibration_async Method tobii_research_apply_calibration_data Method
tobiigaze_get_calibration Method tobii_research_retrieve_calibration_data Method
tobiigaze_set_calibration Method tobii_research_apply_calibration_data Method
tobiigaze_get_calibration_point_data_items Method No equivalent - See tobii_research_retrieve_calibration_data Method
tobiigaze_discovery.h tobiigaze_list_usb_eye_trackers Method tobii_research.h tobii_research_find_all_eyetrackers Method
tobiigaze_get_connected_eye_tracker Method tobii_research_get_eyetracker Method
tobiigaze_get_connected_eye_trackers Method tobii_research_find_all_eyetrackers Method
tobiigaze_display_area.h tobiigaze_get_display_area_async Method tobii_research_eyetracker.h tobii_research_get_display_area Method
tobiigaze_set_display_area_async Method No equivalent - Use Eye Tracker Manager Method
tobiigaze_get_display_area Method tobii_research_get_display_area Method
tobiigaze_set_display_area Method No equivalent - Use Eye Tracker Manager Method