Contributions:EyetrackerLoggerEyeLink

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: 6312
• 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.

Installation and Set-Up

Downloading EyeLink software

To best calibrate the EyeLink eye tracker, some of their software has to be downloaded. This can be found online at SR Support Forum. This "Downloads" page is the last accessible page without having an account, however an account is free to make. Register for an account, filling out all the required information. Once this is done, click on "EyeLink Developers Kit / API", then click on "EyeLink Developers Kit / API Downloads (Windows, macOS, Linux)". After this, download the correct "EyeLink Developers Kit" for your operating system.

Physical Set-Up

There are two computers needed, one that runs BCI2000 (Display PC) and one that runs the EyeLink system (Host PC). To set this up, follow steps 1-3 in their Quick Start Guide. The amount of monitors needed can vary, but the ideal set-up would have 3 monitors. Set them up as shown below.

The participant needs to only be in front of the eye tracker and the display monitor that is showing the stimuli. The experimenter will want to be looking at the information from the EyeLink system and also running BCI2000. The EyeLink system will show the real-time video of the eye, so the experimenter will be able to make sure the eye is tracking, and can give the participant feedback if it is not. The experimenter will also want to have the BCI2000 monitor in front of them, so they can track any states they want and just so they are in control of the experiment.

Calibration

Experimental Set-Up

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.

IP address

To connect to the EyeLink eye tracker, the IP address must be configured. In the Control Panel, go to "Change Adapter Settings", then go to the Ethernet's properties, to where "Internet Protocol Version 4 (ICP/IPv4)" is listed. Change the IP address from automatic to 100.1.1.2, then change the Subnet mask to 255.255.255.0. After this is configured, BCI2000 should be able to connect to the Host PC.

Gaze calibration

Once the measurements are set, the eye needs to be calibrated. 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.

The only application that you'll need is called "Track". Open the Start Menu, go to SR Research folder, and click on the Track application. This will allow access of the EyeLink system from your Display PC. The screen should show up on the "Stimuli" screen, as this is the screen that needs to be calibrated. If it shows up on the other screen, you must make the "Stimuli" monitor your main display and restart the Track application. Follow the steps to get to the calibration screen. Once the target is shown in the middle of the screen, you can watch it on the EyeLink display.

Press "Space" to start the calibration, then the targets will be automatically displayed until they are fixated upon. Once the cycle is done, the person's gaze is calibrated. The software can now 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.

The above figure displays the different coordinate systems. The HREF coordinate system records x and y positions at a distance of 15,000 units away from the pupil, the gaze coordinates are relative to the screen resolution, and the pupil position coordinates are in-line with the pupil. Both the HREF and the pupil coordinate systems have arbitrary units, and HREF has an arbitrary (0,0) point. More details can be found in the EyeLink 1000 Plus user manual on page 108.

Parameters

User configurable Parameters

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

LogEyetrackerEyeLink

Set to 0 (uncheck) to disable the eye tracker logger.

EyeLinkHostAddress

The IP address of the Host PC. The standard is 100.1.1.1, but this parameter allows for other configurations.

SaveEDF

Set to 1 (check) to save an EDF file along with the BCI2000 data file. An EDF file is the EyeLink's main file type, and the EDF will record all possible data. This data can be viewed in EyeLink's Data Viewer or in Matlab. However, most of this data is derived from a couple of foundational variables, and recording all of it real-time is unnecessary and could slow down BCI2000. It is recommended to not save to the EDF file, but only record the necessary data with BCI2000. The extra infromation, such as blinks, saccades, and eye velocity, can later be calculated.

GazeScale, GazeOffset (deprecated)

Only included for compatibility 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. The time stamp occurs at the same time that the other sample data is recorded. If processes are slightly delayed, 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). The screen resolution 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 from gaze data.

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 as mentioned in Converting to Signed Values. 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