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.
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.
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 Tobii Pro SDK does require some modifications to your existing code, we do believe that the Tobii 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 Tobii Pro SDK.
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.
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.
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.
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.
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.
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 | |
tobii_research_set_display_area |
Function |
|
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 Tobii Pro Eye Tracker Manager | ||
|
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 | 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 |
diameter |
float | |
|
rightValidity |
right_eye.pupilData |
validity |
TobiiResearchValidity | |
|
tryGetExtensionValue |
Method | |
Functionality moved - see tobii_research_subscribe_to_external_signal_data |
|
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 |
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 |
Read this guide if you have previously been using Tobii Gaze SDK.
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.
The functionality for discovery of eye trackers is the same between the Gaze SDK and the Tobii Pro SDK however the method name and signature has changed. See the table below. There is no api methods in the Tobii Pro SDK to connect or disconnect to different eye trackers, this is handled automatically by the Tobii Pro SDK.
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 Tobii 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
.
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 Tobii Pro Eye Tracker Manager | Method | ||
tobiigaze_get_display_area |
Method | tobii_research_get_display_area |
Method | ||
tobiigaze_set_display_area |
Method | No equivalent - Use Tobii Pro Eye Tracker Manager | Method |