Contributions:EyetrackerLoggerTobii3

Synopsis

A filter that records state information from Tobii Eyetrackers using the Tobii SDK 3.0 into state variables.

Location

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

Versioning

Authors

Kristopher Kaleb Goering (kaleb.goering@gmail.com)

Jürgen Mellinger (mellinger@neurotechcenter.org)

Version History

• 2015-06-23: Initial public release
• 2017-08-21:
  • adapted code to current version of BCI2000 framework
  • rewrote large parts for clarity
  • unified coordinate system for eye position, and gaze data

Source Code Revisions

• Initial development: 4879
• Tested under: 5696
• Known to compile under: 5696
• Broken since: --

Functional Description

Records data collected by a Tobii eye tracker, using version 3 of the Tobii SDK.

Integration into BCI2000

Compile the extension into your source module by enabling contributed extensions in your CMake configuration, and setting EXTENSIONS_EYETRACKERLOGGERTOBII3=On. Once the extension is built into the source module, enable it by starting the source module with the --LogEyetrackerTobii3=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 --LogEyetrackerTobii3=1 command line parameter is set.

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.

For the experimenter's convenience, X and Y coordinates are also normalized to a fixed range such that the Active Display Area's bottom right corner has coordinates (65535, 65535, 0) when expressed in raw recorded values. For compatibility reasons, eye position coordinates use the same normalized raw units as gaze position does in X and Y directions, but uses raw steps of 1mm for its Z coordinate.

Recovering original physical dimensions is possible using the EyetrackerData Parameter as explained below.

Parameters

User configurable Parameters

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

LogEyetrackerTobii3

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. EyetrackerLoggerTobii3 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.

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.

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)

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, 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. 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, scaled such that the raw state value represents the pupil diameter in tenths of millimeters (0.1mm).

EyetrackerLeftEyeValidity, EyetrackerRightEyeValidity

A number ranging between 0 and 4, representing the eye tracker's confidence to have identified the eye in question. As suggested in the Tobii3 SDK's manual, EyetrackerLoggerTobii3 will ignore any eye data with an associated validity value greater or equal to 2, 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.

See also

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