.NET - 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 object implementing the IEyeTracker interface. Please refer to the reference library for more details about the IEyeTracker interface 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 IEyeTracker interface, 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 a collection of CalibrationSamples collected and calculated for that point.

Read more about how a calibration works in the Calibration section and the ScreenBasedCalibration class in the .NET 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 DeviceTimeStamp) or the computer clock time stamp (called SystemTimeStamp) 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.EyeTracking.IO Tobii.Research
Class Member Type Class Member Type
Calibration Class CalibrationData Class
Calibration Class CalibrationResult Class
Plot Property (read only) CalibrationPoints Property (read only)
CalibrationPlotItem Class CalibrationPoint Class
TruePosition Property PostitionOnDisplayArea Property (read only)
No equivalent - Changed structure N/A CalibrationSamples Property (read only)
No equivalent - Changed structure N/A CalibrationSample Class
No equivalent - Changed structure N/A LeftEye Property (read only)
No equivalent - Changed structure N/A RightEye Property (read only)
No equivalent - Changed structure N/A CalibrationEyeData Class
LeftMapPosition Property PositionOnDisplayArea (LeftEye) Property
LeftStatus Property Validity (LeftEye) Property
LeftMapPosition Property PositionOnDisplayArea (RightEye) Property
RightStatus Property Validity (RightEye) Property
Clock Class No equivalent - Changed structure N/A
Time Property (read only) No equivalent - See GetSystemTimeStamp in EyeTrackingOperations N/A
Resolution Property (read only) No equivalent - See GetSystemTimeStamp in EyeTrackingOperations N/A
EyeTrackerBrowser Class EyeTrackingOperations Static Class
StartBrowsing Method No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
StopBrowsing Method No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
IsStarted Property (read only) No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
EyeTrackerFound Event No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
EyeTrackerUpdated Event No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
EyeTrackerRemoved Event No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
EyeTrackerRemoved Event No equivalent - See FindAllEyeTrackers and FindAllEyeTrackersAsync (methods) N/A
No equivalent - Changed structure N/A FindAllEyeTrackers Method
No equivalent - Changed structure N/A FindAllEyeTrackersAsync Method
EyeTrackerFactory Class (EyeTrackingOperations) (Static Class)
CreateFactoryInfoByIPAdress Method GetEyeTracker Method
No equivalent - Changed structure N/A GetSystemTimeStamp Method
EyeTrackerInfo Class IEyeTracker Interface
Factory Property (read only) No equivalent N/A
Generation Property (read only) No equivalent N/A
Model Property (read only) Model Property (read only)
ProductId Property (read only) SerialNumber Property (read only)
GivenName Property (read only) DeviceName Property (read only)
Version Property (read only) FirmwareVersion Property (read only)
No equivalent - Changed structure N/A Address Property (read only)
IEyeTracker Interface IEyeTracker Interface
EnumerateFrameRates Method GetAllGazeOutputFrequencies Method
EnumerateIlluminationModes Method GetAllEyeTrackingModes Method
GetCalibration Method RetrieveCalibrationData Method
GetFrameRate Method GetGazeOutputFrequency Method
GetTrackBox Method GetTrackBox Method
GetIlluminationMode Method GetEyeTrackingMode Method
GetLowBlinkMode Method No equivalent - See GetEyeTrackingMode N/A
GetUnitInfo Method No equivalent - Changed functionality N/A
GetUnitName Method DeviceName Property
GetXConfiguration Method GetDisplayArea Method
SetCalibration Method ApplyCalibrationData Method
SetFrameRate Method SetGazeOutputFrequency Method
SetIlluminationMode Method SetEyeTrackingMode Method
SetLowBlinkMode Method No equivalent - See GetEyeTrackingMode N/A
SetUnitName Method SetDeviceName Method
SetXConfiguration Method Functionality moved - Use the Eye Tracker Manager N/A
StartTracking Method No equivalent - Changed functionality N/A
StopTracking Method No equivalent - Changed functionality N/A
DumpImages Method Functionality moved - Use the Eye Tracker Manager N/A
EnableExtension Method No equivalent - Removed functionality N/A
AuthorizeChallenge Method No equivalent - Removed functionality N/A
GetAvailableExtensions Method No equivalent - Removed functionality N/A
GetDiagnosticReport Method Functionality moved - Use the 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
RealTimeGazeData Property No equivalent - Changed functionality N/A
No equivalent - New functionality N/A TryApplyLicense Method
AddCalibrationPointCompleted Event No equivalent - Changed functionality N/A
CalibrationStarted Event CalibrationModeEntered Event
CalibrationStopped Event CalibrationModeLeft Event
ComputeCalibrationCompleted Event No equivalent - Changed functionality N/A
ConnectionError Event ConnectionLost, ConnectionRestored Event
FrameRateChanged Event GazeOutputFrequencyChanged Event
GazeDataReceived Event GazeDataReceived Event
TrackBoxChanged Event TrackBoxChanged Event
XConfigurationChanged Event DisplayAreaChanged Event
No equivalent - New functionality N/A TimeSynchronizationReferenceReceived Event
No equivalent - New functionality N/A EyeImageReceived Event
No equivalent - New functionality N/A ExternalSignalReceived Event
No equivalent - New functionality N/A EventErrorOccurred Event
IEyeTracker Interface ScreenBasedCalibration Class
AddCalibrationPoint Method CollectData Method
AddCalibrationPointAsync Method CollectDataAsync Method
ClearCalibration Method No equivalent - Removed functionality (See EnterCalibrationMode) N/A
ComputeCalibration Method ComputeAndApply Method
ComputeCalibrationAsync Method ComputeAndApplyAsync Method
RemoveCalibrationPoint Method DiscardData Method
StartCalibration Method EnterCalibrationMode (equivalent to StartCalibration + ClearCalibration) Method
StartCalibration Method LeaveCalibrationMode Method
IClock Class No equivalent - Changed functionality N/A
ITrackerFactory Class No equivalent - Removed functionality (See EyeTrackingOperations) N/A
IGazeDataItem Interface GazeDataEventArgs Class
LeftEyePosition3D Property (read only) Left.GazeOrigin.PositionInUserCoordinates Property (read only)
LeftEyePosition3DRelative Property (read only) Left.GazeOrigin.PositionInTrackBoxCoordinates Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Left.GazeOrigin.Validity Property (read only)
LeftGazePoint2D Property (read only) Left.GazePoint.PositionOnDisplayArea Property (read only)
LeftGazePoint3D Property (read only) Left.GazePoint.PositionInUserCoordinates Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Left.GazePoint.Validity Property (read only)
LeftPupilDiameter Property (read only) Left.Pupil.PupilDiameter Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Left.Pupil.Validity Property (read only)
LeftValidity Property (read only) No equivalent - Changed functionality (See GazeOrigin.Validity, GazePoint.Validity and PupilData.Validity. Also more info in Validity codes.) N/A
RightEyePosition3D Property (read only) Right.GazeOrigin.PositionInUserCoordinates Property (read only)
RightEyePosition3DRelative Property (read only) Right.GazeOrigin.PositionInTrackBoxCoordinates Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Right.GazeOrigin.Validity Property (read only)
RightGazePoint2D Property (read only) Right.GazePoint.PositionOnDisplayArea Property (read only)
RightGazePoint3D Property (read only) Right.GazePoint.PositionInUserCoordinates Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Right.GazePoint.Validity Property (read only)
RightPupilDiameter Property (read only) Right.Pupil.PupilDiameter Property (read only)
No equivalent - Changed functionality (See Validity codes) N/A Right.Pupil.Validity Property (read only)
RightValidity Property (read only) No equivalent - Changed functionality (See GazeOrigin.Validity, GazePoint.Validity and PupilData.Validity. Also more info in Validity codes.) N/A
TimeStamp Property (read only) DeviceTimeStamp Property (read only)
No equivalent - New functionality N/A SystemTimeStamp Property (read only)
TryGetExtensionValue Method No equivalent - Removed functionality N/A
IProgressReporter Interface Functionality moved - Use the Eye Tracker Manager N/A
ISyncManager Interface No equivalent - Changed functionality N/A
Library Class No equivalent - Changed functionality N/A
UpgradeManager Class Functionality moved - Use the Eye Tracker Manager N/A