Jump to content

Contributions:EyetrackerLoggerTobiiPro

From BCI2000 Wiki

Synopsis

An extension that records state information from Tobii Eyetrackers using the Tobii Pro SDK into state variables.

Location

http://www.bci2000.org/svn/trunk/src/contrib/Extensions/EyetrackerLoggerTobiiPro

Versioning

Authors

Markus Adamek (markus.adamek@gmail.com)

Version History

  • 2017-08-29: Initial public release by Markus Adamek (adamek@neurotechcenter.org)
  • 2021-03-19: Updated Tobii Pro SDK to v1.8.0.21 by Alexander Belsten (belsten@neurotechcenter.org)
  • 2023-11-24: Make resolution adjustable through parameters by Jürgen Mellinger (mellinger@neurotechcenter.org)
  • 2026-04-01: Add recording of eye openness by Jürgen Mellinger (mellinger@neurotechcenter.org)

Source Code Revisions

  • Initial development: 5681
  • Tested under: 7762
  • Known to compile under: 7762
  • Broken since: --

Functional Description

Records data collected by a Tobii eye tracker, using the Tobii Pro SDK.

Integration into BCI2000

Compile the extension into your source module by enabling contributed extensions in your CMake configuration, and setting EXTENSIONS_EYETRACKERLOGGERTOBIIPRO=On. Once the extension is built into the source module, enable it by starting the source module with the --LogEyetrackerTobiiPro=1 command line argument.

Usage and Calibration

Make sure the eye tracker is set up according to its user manual, and make sure it is able to connect to the Tobii calibration utility.

Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eye wear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).

Quit the calibration utility before starting BCI2000. When you start the source module, ensure that the --LogEyetrackerTobiiPro=1 command line parameter is set.

NOTE: If the eyetracker is connected via ethernet, and is detected by the calibration utility but not by BCI2000, you probably need to use the calibration utility in order to install an additional library ("Tobii Network Runtime") into your system.

Coordinate System

When properly calibrated, the eye tracker will know about location, orientation, and extent of the display surface, relative to itself. Observing the subject through a camera, the eye tracker will be able to detect eye position and gaze direction, relative to its own position and orientation. Using calibration information, it can then determine gaze location as the intersection of gaze direction, and display surface, and it will transform gaze location into a more convenient coordinate system which is aligned to the display's edges.

To an experimenter, none of the involved coordinate systems is relevant, except for the screen-relative one in which gaze location is reported. Thus, it appears most natural to report eye position in the same screen-relative coordinate system, extended with a Z axis perpendicular to the screen, as illustrated below:

In this coordinate system, gaze position will always have a Z coordinate of 0, and the eye's Z coordinate will be its distance from the screen plane. An eye's position and gaze may thus be expressed by 5 coordinate values,

  • GazeX: X coordinate of gaze position,
  • GazeY: Y coordinate of gaze position,
  • EyePosX: X coordinate of eye,
  • EyePosY: Y coordinate of eye,
  • EyeDist: Z coordinate of eye

in the above coordinate system.

To preserve physical resolution, X, Y, and Z coordinates are multiplied by a an appropriate factor before being saved as integer values.

Recovering original physical dimensions is possible using the EyetrackerData Parameter as explained below, or, more directly, by applying the GazeResolution parameter to the recorded data.

Parameters

User configurable Parameters

The eye tracker is configured in the Source tab within the EyetrackerLogger section.

LogEyetrackerTobiiPro

Set to 0 to disable the eye tracker logger.

GazeScale, GazeOffset (deprecated)

Incoming gaze and position data are transformed by first multiplying with GazeScale, then subtracting GazeOffset. These values may affect the precision in which gaze data is stored, and should always be set to GazeScale=1, GazeOffset=0.

GazeScale and GazeOffset were hacks introduced in the original EyetrackerLogger to address an issue with gaze data being clamped around the edges of the screen. EyetrackerLoggerTobiiPro uses additional bits to avoid issues with values being out of range, so these parameters serve no useful purpose any more, and are kept solely for backward compatibility with the original EyetrackerLogger.

GazeResolution

The physical value corresponding to one step in gaze related state variables. Must be given in meters, with optional SI prefix. Default is 0.1mm.

PupilResolution

The physical value corresponding to one step in pupil size state variables. Must be given in meters, with optional SI prefix. Default is 0.01mm. If EyeOpenness is being recorded (see below), the PupilResolution applies to that as well.

Descriptive Parameters

These parameters are used by the eye tracker logger in order to store information about the eye tracker's configuration, and to help interpretation of logged data in data analysis. NOTE: When viewed in the Operator's configuration window, these parameters will not contain any data, instead they are set to auto. This is correct. In the written file, they will contain valid data.

EyetrackerInfo

A list-valued parameter with a variable number of named entries, providing information about the eye tracker's properties and configuration.

Depending on eye tracker model and setup, the following entries may be present:

  • SerialNumber, Model, Generation, FirmwareVersion
  • UnitName (if set by the user)
  • FrameRate (if available)
  • IlluminationMode (if available)
  • LowBlinkMode (if available)

LegacyCorrectionFactor

A list-valued parameter with four entries, corresponding to x, y, z, and pupil size coordinates.

Apply this factor to the respective state values in order to obtain those values as they were in previous versions of the EyetrackerLogger. E.g., this is used by the GazeMonitorFilter for compatibility reasons.

LegacyCorrectionOffset

A list-valued parameter with four entries, corresponding to x, y, z, and pupil size coordinates.

Subtract this offset from the respective state values prior to applying the legacy correction factor in order to obtain those values as they were in previous versions of the EyetrackerLogger. E.g., this is used by the GazeMonitorFilter for compatibility reasons.

EyetrackerData

A matrix-valued parameter with two columns, and one row for each state variable written by the eye tracker logger, containing information required to recover the original physical units associated with eye tracker data when reading a data file.

For each row, its label matches the name of a BCI2000 state variable holding eye tracker data.

The row's first column contains a data type of the form [u]int<N> where N is the number of bits, and a u prefix indicates that a value is to be interpreted as unsigned rather than signed. (For signed values, the most significant bit represents sign, and must be specially taken account for.)

In the second column, the data elements of a PhysicalUnit object are present, separated with spaces, and in the following order:

  • offset in raw units,
  • gain,
  • symbol (of an SI unit, without prefix),
  • raw minimum (typically 0, but may indicate an estimated raw data minimum if different from raw maximum),
  • raw maximum (typically 0, but may indicate an estimated raw data maximum if different from raw minimum).

Examples: EyetrackerData may contain a row labeled EyetrackerRightEyeGazeX with a data type of "int18" and a physical unit of "-6.3 1e-5 m 0 0". At some sample offset, the value of the EyetrackerRightEyeGazeX state may be read as 2345. To recover the right gaze point's distance from the screen's left edge in original units, you may proceed as follows:

  • interpret 2345 as a signed 18 bit number -> 2345
  • subtract -6.3 -> 2345-(-6.3) = 2351.3
  • multiply with 1e-5 -> 0.023513
  • concatenate with "m" -> 0.023513m = 23.513mm.

At another sample offset, the value of the EyetrackerRightEyeGazeX state may be read as 262138:

  • interpret 262138 as a signed 18 bit number -> -6
  • subtract -6.3 -> -6-(-6.3) = 0.3
  • multiply with 1e-5 -> 0.000003
  • concatenate with "m" -> 0.000003m = 0.03mm.

Extending the sign bit: In order to interpret a positive 32-bit integer value as a signed N bit integer with N<32, bits 18 to 31 must be set to the same value (1 or 0) as the sign bit. In Matlab, this may be achieved as follows: 

x = ...
idx = find(x >= 2^(N-1));
x(idx) = 2^N - x(idx);

In C or C++, one may write 

int32_t x = ...
uint32_t mask = ~((1<<N)-1);
if(x & mask)
  x |= mask;

State Variables

EyetrackerTime

Time stamp of eye data as reported by the eye tracker, and converted into time units compatible with the SourceTime data time stamp. Eye tracker data will be sample-aligned using this time stamp if possible, but may appear delayed in a data file if transmission from the eye tracker is late. In this case, the value of EyetrackerTime will differ from the value of SourceTime by more than a sample block duration in milliseconds.

EyetrackerLeftEyeGazeX, EyetrackerLeftEyeGazeY, EyetrackerRightEyeGazeX, EyetrackerRightEyeGazeY

Screen position where the subject is looking at. Point (0,0) corresponds to the top left of the screen. Multiply each value by the unit given in the GazeResolution parameter in order to obtain the physical location relative to the screen's top left.

EyetrackerLeftEyePosX, EyetrackerLeftEyePosY, EyetrackerLeftEyeDist, EyetrackerRightEyePosX, EyetrackerRightEyePosY, EyetrackerRightEyeDist

Eye position in the same screen-relative coordinate system used for gaze data, extended by a Z axis normal to the screen plane, pointing towards the subject. As for gaze data, multiply by GazeResolution to obtain the physical position relative to the screen's top left.

This measurement is an approximation. The actual measurement may depend on whether or not the test subject is wearing glasses or not.

EyetrackerLeftPupilSize, EyetrackerRightPupilSize

Pupil diameter as estimated by the eye tracker. Multiply by the value of the PupilResolution parameter to obtain the physical size of the pupil diameter.

EyetrackerLeftEyeValidity, EyetrackerRightEyeValidity

This state will be equal to four if the eye tracker is unable to acquire data for a given eye (such as an eyeblink), otherwise it will be zero. EyetrackerLoggerTobiiPro will ignore any eye data that is not valid but will report time stamp and validity value for that data point nevertheless. When eye data are being ignored, all respective state variables will keep their previous values.

EyetrackerLeftEyeOpenness, EyetrackerRightEyeOpenness

The diameter of the largest circle that fits between the upper and lower eyelid, as estimated by the eyetracker. Multiply by the value of the PupilResolution parameter to obtain the physical diameter of the eye openness circle.

These values are only recorded with eyetracker hardware that supports eye openness (Tobii Pro Fusion, Tobii Pro Spectrum).

EyetrackerLeftEyeOpennessValidity, EyetrackerRightEyeOpennessValidity

This state will be equal to four if the eye tracker is unable to obtain eye openness, otherwise it will be zero. EyetrackerLoggerTobiiPro will ignore any eye data that is not valid but will report a validity value for that data point nevertheless. When eye openness data are being ignored, the respective state variables will keep their previous values.

State variables in legacy files

You can tell legacy files from current files by looking at the LegacyCorrectionFactor parameter. If this parameter is missing, you have a legacy file.

In legacy files, the meaning of some state variables is different. These are listed below.

EyetrackerLeftEyeGazeX, EyetrackerLeftEyeGazeY, EyetrackerRightEyeGazeX, EyetrackerRightEyeGazeY

Screen position where the subject is looking at, rescaled such that, in raw state values, point (0,0) corresponds to the top left of the screen, and (65535, 65535) corresponds to the bottom right of the screen.

EyetrackerLeftEyePosX, EyetrackerLeftEyePosY, EyetrackerLeftEyeDist, EyetrackerRightEyePosX, EyetrackerRightEyePosY, EyetrackerRightEyeDist

Eye position in the same screen-relative coordinate system used for gaze data, extended by a Z axis normal to the screen plane, pointing towards the subject. Unlike X and Y coordinates, the Z coordinate's raw state value is not normalized but represents screen distance in millimeters.

EyetrackerLeftPupilSize, EyetrackerRightPupilSize

Pupil diameter as estimated by the eye tracker, scaled such that the raw state value represents the pupil diameter in tenths of millimeters (0.1mm).

See also

User Reference:Logging Input, Contributions:Extensions, Contributions:EyetrackerLogger

Retrieved from "http://www.bci2000.org/mediawiki/index.php?title=Contributions:EyetrackerLoggerTobiiPro&oldid=12381"