Time Synchronization

If millisecond accuracy is important to your use case, this section will give you an understanding of why you need time synchronization and how to do it. To take full advantage of time synchronization you need a Tobii Ocumen license.

Table of Contents


Glossary

Term Description
Stream Engine API (SE) An API used by all Tobii SDKs to communicate with a Tobii Eye Tracker.
Device In SE and most high level Tobii SDKs, device refers to the eye tracker. A device timestamp is a timestamp from the clock used by the eye tracker.
Host System The system hosting the application that uses SE. This is not necessarily* the same system that hosts the eye tracker calculations. Host System is most often referred to as only System.
Monotonic Clock A clock that always moves forward in time. If a time synchronization causes a time source to report a lower timestamp than it reported before the time synchronization, the time source can not be considered monotonic.
Synchronization Point Two timestamps from two different clocks that refer to the same instance in time.

* Some eye trackers share a common device and system clock, so time synchronization is not needed. However, we still recommend reading and applying this section to ensure correct timing information across all devices.

Introduction

In many advanced eye tracking use cases, blinks, fixations or pupil dilation need to be correlated with non-gaze events such as user input, the depiction of a visual stimulus, or EEG readings. To accurately correlate these events, the time when the event occurred is needed, not when the application received the information about it. The sources of these events may use different clocks to timestamp their data.

When an eye tracker sensor readout happens to produce an advanced data package, a timestamp is produced at the time of capture. In SE this is referred to as a device timestamp. In many eye trackers this timestamp is read from an internal clock accessible only to the eye tracker. To convert this timestamp to something useful on the host system, a synchronization point between the eye tracker clock and the host system clock needs to be created. This process is called a time sync.

The remainder of this section gives an overview of how to perform this synchronization.

Time Sync

As mentioned, the purpose of a time sync operation is to establish a synchronization point between two clocks. For our purposes this means the eye tracker clock and the host system clock. The SE internally calculates a system timestamp using information from the last time sync operation, and adds it to the advanced data package.

Since SE does not have a background thread or the ability to schedule time sync operations asynchronously, SE does not perform time sync for you automatically. However, higher level SDKs using SE may do that for you.

A time sync operation consists of these steps:

  1. A timestamp ST1 is read from host system clock and saved in a time sync package.
  2. The time sync package is sent to the eye tracker and a timestamp ET2 from the eye tracker clock is added to the time sync package.
  3. The time sync package is sent back to the host system and a second timestamp ST3 from the host system clock is added.

With this time sync data, a synchronization point can be created. A synchronization point contains two timestamps that show the same point in time from two different clocks. To create a synchronization point from a time sync package:

  1. Calculate the round trip time (RTT) for the time sync operation: RTT = ST3-ST1. For USB connected eye trackers this is usually less than 1 ms but can be higher during high system loads.
  2. Since we cannot measure how much of the RTT was to send the package to the eye tracker and how much was for the eye tracker to send it back, we assume sending took half of the RTT: send time = RTT / 2.
  3. We now have a synchronization point where eye tracker time ET2 represents the same time as host system time ST1 + send time.

See Cristian’s algorithm for more details.

The RTT determines the accuracy of the time sync operation. The higher the RTT, the larger the potential time sync error (estimated send time - actual send time). To minimize the risk of high RTT you should consider making four time sync operations in quick succession and only keep the result of the operation with the lowest RTT.

Every time a time sync operation is performed, no matter if the result is used or not, a synchronization point is saved internally in the SE and used to improve the calculation of system timestamps.

Clock drift

All clocks drift over time. Often several milliseconds per hour. To correctly correlate data captured over a period of time with different clocks multiple synchronization points are needed. How often such a point is needed depends on the use case, but one per minute is a good start.

For higher accuracies either more synchronization points are created or a clock drift compensation function is used. Clock drift can also cause two monotonic clocks to yield an extrapolated timestamp that is not monotonic.

Extrapolation

If a real-time synchronization of the eye tracker clock and host system clock is needed, the only option is to extrapolate the system timestamps from previous synchronization points. There are two options:

  1. Use the system timestamps calculated for you by SE
  2. Create your own extrapolation function and calculate system timestamps from device timestamps

The function used internally by SE to calculate system timestamps from device timestamps is deliberately minimal and does NOT compensate for clock drift and does NOT guarantee monotonic timestamps. In use cases where this is not acceptable, a custom extrapolation function using saved synchronization points must be used. We will not present an example of how to write this function, but read the example below on how to interpolate system timestamps to get you started.

Interpolation

If no real-time synchronization of both clocks are needed, the best accuracy for system timestamps can be achieved by calculating them via interpolation from device timestamps and synchronization points in a post-processing step.

Here is an example to illustrate a list of synchronization points (times in microseconds):

Index Eye tracker time (ET2) System time (ST1 + send time) Round trip time (RTT)
0 31324564 56363235478 612
1 32324523 56364235543 822
2 33324453 56365235985 4412
3 34324938 56366235194 542
4 35324129 56367235037 2612

Given this list, a device timestamp from recorded gaze data can be interpolated between the closest timestamps in that list of synchronization points to get an accurate timestamp in system time.

Example:

  • You have a recorded gaze data packet that has a device timestamp value of ETx = 33654613. This puts it between the synchronization point 2 and 3.
  • The linear interpolation for system timestamp STx is then (ETx - ET2) / (ET3 - ET2) = 0.33.
  • To get the host system timestamp you interpolate between the corresponding host system timestamps: STx = ST2 + 0.33 * (ST3 - ST2) = 56365565724.

Note that this example assumes linear clock drift, while in reality clocks may not drift linearly.