Contributions:EyetrackerLoggerEyeLink

Synopsis

A filter that records state information from EyeLink Eyetrackers into state variables.

Location

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

Versioning

Authors

William Engelhardt (engelhardt@neurotechcenter.org)

Version History

• 2021-06-15: Initial public release by William Engelhardt (engelhardt@neurotechcenter.org)

Source Code Revisions

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

Functional Description

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

Integration into BCI2000

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

Usage and Calibration

Calibration is done without the use of BCI2000. To calibrate, use the EyeLink system. Set it up according to their Installation Guide, using a Host PC and a Display PC. The eye tracker should be set up in front of the Display PC. Once everything is physically set up, you must enter the dimensions into the EyeLink software. Do this by entering the File Manager (exit EyeLink if you have already started the program), go to the settings by clicking on the "Configuration" button, then click on the "Screen Settings" button. Once here, there are four measurements that should be entered for the set-up. "Screen Dimensions" and "Display Resolution" need to be entered no matter the tracking mode, "Eye-to-Screen" needs to be updated for every mode but the Remote mode, and "Camera-to-Screen" only needs to be updated for the Remote tracking mode. Before continuing, make sure these parameters are correctly set for the current experiment.

Once the measurements are set, the eye needs to be calibrated. Use their software to calibrate to the Display PC. Once calibrated, the subject should take care to limit their movement. If using Remote tracking mode, you must have a calibrating sticker on your forehead, which calibrates your eye relative to the sticker. This method theoretically maintains the calibration with head movement, but to have the most accurate data, re-calibrate whenever the subject has left and returned to the field of view, or if any external conditions have changed.

Once calibrated, the software should be quit and BCI2000 can be started, ensuring that the --LogEyetrackerEyeLink=1 command line parameter is set.

Coordinate System

The EyeLink eye tracker records numerous types of data, as listed below:

• Position: The raw X and Y coordinates recorded by the camera. This is converted to more useful types of data by a successful calibration.
• Head-referenced (HREF): Measures eye rotation angles relative to the head. The X and Y coordinates reflect the line of sight at an arbitrary distance of 15,000 units from the eye. Eye rotation angles can be calculated from the raw data.
• Gaze: The actual X and Y coordinates of the eye position on the display screen. The units are pixels, which coordinate with the screen resolution that was specified.
• Gaze resolution: The X and Y angular resolution of the gaze position, in pixels per degree of visual angle. Unlike the previous 3 coordinate systems, this data is independent of which eye is being used, or if multiple eyes are used.
• Pupil size: The area of the pupil, in arbitrary units. Best recorded as a percent change relative to a baseline.

Parameters

User configurable Parameters

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

LogEyetrackerEyeLink

Set to 0 to disable the eye tracker logger.

EyeLinkHostAddress

The IP address of the Host PC. Is usually 100.1.1.1.1, but can be configured otherwise.

GazeScale, GazeOffset (deprecated)

Only included for compatablility with the EyetrackerLogger and GazeMonitorFilter; is not used in this source code. When used by the other programs, incoming gaze and position data are transformed by first multiplying with GazeScale, then subtracting GazeOffset.

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

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.

EyeLinkInfo

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

• WhichEye: Tells which eye is being recorded. If both eyes are being used, will state "Both eyes".
• Tracker Version: Records which version of the tracker, for future analysis.
• Prescaler: Used to keep a high resolution of data.
• Width: The width of the display, in pixels.
• Height: The height of the display, in pixels.
• FrameRate: The frequency at which data is being collected.

Converting to Signed Values

BCI2000 records its state variables as unsigned bytes, which means that it can't record negative numbers. A signed variable and an unsigned variable with the same amount of bits can contain the same amount of data, but the unsigned range starts at zero, and is double the range of the positive side of the signed variable. For example, a 16 bit signed variable ranges from -32,768 to 32,767, where a 16 bit unsigned variable ranges from 0 to 65,535. To convert the negative values to an unsigned variable, the values had to be pushed up to above 32,767. This way, they wouldn't get mixed in with values that were originally positive.

To convert the data back to negative values, some simple processing is needed. Below is a Matlab function that converts unsigned values to signed:

function s = ToSigned(u)
  dU = double(u);
  iU = (dU > 2^15);
  tempU = dU - iU*2^15;
  s = tempU - 2*tempU.*iU;
end

If you input your data as u, it will be returned as the original, signed data.

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 might differ from the value of SourceTime by more than a sample block duration in milliseconds.

EyetrackerLeftEyePosX, EyetrackerLeftEyePosY, EyetrackerRightEyePosX, EyetrackerRightEyePosY

The raw X and Y coordinates recorded by the camera, kept separately for each eye. Recorded as an unsigned int16 so it must be converted back. It is reported with 200 to 400 units per visual degree. This data is most useful when auto-sequencing calibrations or performing your own calibration.

EyetrackerLeftEyeGazeX, EyetrackerLeftEyeGazeY, EyetrackerRightEyeGazeX, EyetrackerRightEyeGazeY

The actual X and Y coordinates of the eye position on the display screen, kept separately for each eye. Also recorded as an unsigned int16 so it must be converted back. The top left corner is (0,0) and the bottom right corner of the visible screen is (screen width, screen height). These values should have been specified by the user before the calibration. They are also recorded in the parameter "EyeLinkInfo".

EyetrackerLeftEyeHRefX, EyetrackerLeftEyeHRefY, EyetrackerRightEyeHRefX, EyetrackerRightEyeHRefY

Measures eye rotation angles relative to the head for each eye. The X and Y coordinates reflect the line of sight at an arbitrary distance of 15,000 units from the eye. Because of this standardization, the units are independent of system setup. The (0,0) point is also arbitrary, so this data type is best used for looking at data relative to a known eye position. These coordinates may be converted to eye rotation angles, as well as the resolution for the HREF position.

EyetrackerEyeResX, EyetrackerEyeResY

The X and Y angular resolution of the gaze position, in pixels per degree of visual angle. Unlike the previous 3 coordinate systems, this data is independent of which eye is being used. This can be used to compute the velocity.

EyetrackerLeftPupilSize, EyetrackerRightPupilSize

The area of the pupil, in arbitrary units. Typical values range from 100 to 10000 units. Pupil data should be positive, but if there were any negative recorded values, it can be converted back using the same method. It is noise-limited with close than 0.2% of the diameter, which results in a resolution of 0.01 mm for a 5 mm pupil. To compare pupil data across subjects, the data should be converted to percentages of a baseline pupil size for each subject.

EyetrackerLeftEyeValidity, EyetrackerRightEyeValidity

There are 5 states of validity, resulting in a validity being anywhere between 0-31. Each data type is either valid (0) or invalid (1). The data types are combined by using binary, in order to maintain their exclusivity. For example, if the validity was reported as 13, it would be 01101 in binary. This means that the gaze, position, and HRef data are invalid. The invalid values for each data type is shown in the table below.

Values if data is exclusively INVALID

Data type	Validity Number	Binary
Gaze	1	0 0 0 0 1
Pupil Size	2	0 0 0 1 0
Position	4	0 0 1 0 0
Head-ref	8	0 1 0 0 0
Gaze resolution	16	1 0 0 0 0

EyetrackerLoggerEyeLink will report all data, regardless of its validity. If a certain data type is invalid, the most recent valid value will be recorded. Every other data type will continue updating as usual.

See also

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