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:
• Tested under:
• Known to compile under:
• 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.

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

Eye position in the same screen-relative coordinate system used for gaze data, 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.

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.

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

There are 5 states of validity, resulting in a validity being anywhere between 0-15.

EyetrackerLoggerEyeLink 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, only that respective state variable will keep its previous value.

See also

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