Contributions:EyetrackerLoggerEyeLink

From BCI2000 Wiki
Jump to navigation Jump to search

An BCI2000 extension that records synchronized physiological data, such as gaze position, pupil size, and blinks, from EyeLink Eyetrackers into state variables.

An image of the EyeLink 1000 Plus eye tracker

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: 6433
  • Known to compile under: 6433
  • Broken since: --

Video Overview



Functional Description

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

Integration into BCI2000

To enable the extension in your CMake configuration, enable EXTENSIONS_EYETRACKERLOGGEREYELINK=On in the Extensions folder of the CMake GUI and then generate the BCI2000 Visual Studio solution in CMake. Next, open the solution with Visual Studio and rebuild the BCI2000FrameworkSigSrcModule, and then rebuild any signal source module you want to use the extension with. Once the extension is built into the source module, you can enable it by appending --LogEyetrackerEyeLink=1 to the source module start executable command in your batch file.

You can also optionally add --WhichEye=, where you can specify left eye: Left or 0 or right eye: Right or 1. The specified eye much match the eye that EyeLink is recording. If EyeLink is not recording the desired eye, this must be changed in the EyeLink software. If "Which Eye" is not specified, BCI2000 will show states from both eyes.

Installation and Set-Up

Downloading EyeLink software

To best calibrate the EyeLink eye tracker, some of EyeLink's 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 number of monitors needed can vary, but the ideal set-up would have 3 monitors. If only 2 monitors are available, the "EyeLink Display" can be taken out. The "EyeLink Display" shows the lens's image of the eye and the eye's gaze on the "Stimuli" monitor. This is nice for validation that the eye is tracking, however is not necessary for data collection. The ideal example set-up is shown below.

Image: 700 pixels

The participant should be positioned in front of the eye tracker and the display monitor that will be showing the stimuli. The experimenter will want to be looking at the information from the EyeLink system and also be running BCI2000. The EyeLink system will show the real-time video of the eye, so the experimenter will be able to verify the eye is tracking throughout the experiment, and can give the participant feedback if it is not. By viewing the BCI2000 monitor, the experimenter will be able to monitor the status of the experiment, as well as the electrophysiological recordings.

Important Note: The EyeLink lens does NOT autofocus! If the image is blurry, you must physically adjust the lens to focus on your eye.

IP address

To connect to the EyeLink eye tracker, the IP address of the BCI2000 PC 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.X, where X is an integer between 0-255 (and not equal to the EyeLink's IP address - usually 100.1.1.1). Then change the Subnet mask to 255.255.255.0. After this is configured, BCI2000 should be able to connect to the Host PC. If not, verify the ethernet connection.

Software Set-Up

Experimental Set-Up

Before continuing, make sure everything is set-up as previously mentioned. The next step can either be done with or without BCI2000. If using BCI2000, all the parameters are set remotely. The only parameter that can't be set remotely is the Lens Type, which can either be 16mm or 25mm. If this is changed, you must go into the EyeLink software and change it manually. Every other parameter can be either set from BCI2000 or the EyeLink software, as described below:

With BCI2000

The “Display Resolution” parameter is taken from “WindowHeight” and “WindowWidth” in the Application tab. All the other configurable settings are located in the parameter ExperimentParams. Look at the parameter definition below for details in measurements.

Without BCI2000

  1. Open the EyeLink File Manager
    1. If the EyeLink eye tracking program has already been started, you must click on the “Offline” button, then click on the “Exit EyeLink”
  2. Click on the “Configuration” button
  3. Click on the "Screen Settings" button
  4. Enter the applicable settings:
    1. “Screen Dimensions” and “Display Resolution” always need to be entered.
    2. “Eye-to-Screen”: For all non-remote tracking modes.
    3. “Camera-to-Screen”: Only for remote tracking mode. Both the distance and the lens type should be checked.

Gaze calibration

Once the measurements are set, the EyeLink needs to be calibrated. If using Remote tracking mode, you must have a calibrating sticker on your forehead, which tracks your head movements via the sticker. This method theoretically maintains the calibration, 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.exe". If missing, follow steps from "Downloading EyeLink software". To open this application, open the Start Menu on the Display PC, go to SR Research folder, and click on "Track". 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 in the window's display settings 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" or "Enter" 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.

Upon opening and closing the “Track” software, it will ask you to save to a file. When opening, you must accept that you will save to a file. However, when closing, you can press cancel and not save anything. Unless you record data with this application, the saving of the file is useless.

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. See page 108-109 in the EyeLink User Manual for additional information.
  • Gaze: The actual X and Y coordinates of the eye position on the display screen. The units are pixels, with maximum width and height specified by “Display Resolution” (i.e. 1920 x 1080).
  • 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.
EyeLinkCoordinateSystem.png

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

EyeLinkParameters.PNG

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. This should be set in your batch file by appending --LogEyetrackerEyeLink=1 to the source module start executable command.

DataType

The data type that will be recorded. The default is GAZE. In 99% of the cases, the gaze data will be desired. However for the 1% of cases, the hREF data can be recorded instead. When hREF is selected, the GazeMonitorFilter can't be used.

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, such as blinks, saccades, and eye velocity. This data can be viewed in EyeLink's Data Viewer or in Matlab. However, most of this additional data is derived from the foundational variables that BCI2000 records, so recording to the EDF file is unnecessary and could slow down BCI2000. The additional extra physiological data contained in the EDF file can be calculated from the foundational data BCI2000 records during offline analysis. Thus, it is not recommended to save the EDF file during experiments. However, it is useful for validating the data BCI2000 records during experiment testing.

EyeLinkHostAddress

The IP address of the Host PC. The standard is 100.1.1.1, but this parameter allows for other configurations in case the IP of the Host PC needs to be changed.

ExperimentParams

An array of parameters that are specific to the experimental set-up:

  • Use: 1 to use the following parameters, 0 to ignore parameters listed. If 0, EyeLink will use the values that are listed in its software.
  • Remote: 1 for Remote tracking mode, 0 for any other mode. If 1, “EyeToTop” and “EyeToBottom” will not be used. If 0, “LensToScreen” will not be used.
  • PhysX: The physical width of the visible part of the screen (mm).
  • PhysY: The physical height of the visible part of the screen (mm).
  • EyeToTop: The distance from the subject’s eye to the top of the screen (mm).
  • EyeTo Bottom: The distance from the subject’s eye to the bottom of the screen (mm).
  • LensToScreen: The distance from the lens to the screen (mm). This is most accurately measured from the base of the lens to the front of the visible part of the screen.

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. The gaze data is divided by this prescaler and then multiplied again before writing to the link or to the EDF. Useful for troubleshooting if gaze data is off by some factor.
  • 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

The gaze states and HRef states routinely need to record negative values (pupil size and position data occasionally do as well), but BCI2000 states only record unsigned (positive) values. To encode negative numbers to the states, potentially negative numbers are written in signed magnitude representation, where the most significant bit denotes the sign of the value (1 for negative, 0 for positive).

To convert the data back to signed (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-1);
  s = tempU - 2*tempU.*iU;
end

Where your input is u, the raw unsigned state variables, and the returned value s is 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.

EyetrackerLeftEyePupilSize, EyetrackerRightEyePupilSize

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 abnormally high values (above 2^15 in this case), that means there are negative values. These 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.

GazeMonitorFilter Implementation

EyeLink is fully functional with GazeMonitorFilter which allows you to set fixation points and view the gaze data with BCI2000. To use, implement the filter, following the steps in the wiki. Here are some important notes:

  • To visualize any data, make sure that VisualizeGazeMonitorFilter (in the GazeMonitor section of the application tab) and VisualizeApplicationWindow (in the Application Window section of the Visualize tab) are both on
  • GazeMonitorFilter can get rid of the need of a third monitor. By visualizing the gaze data on the "BCI2000" monitor, there is not a big need for the "EyeLink display" monitor. The only information that GazeMonitorFilter doesn't contain is the image of the eye (which helps with focusing the lens). This problem can be overcome by using the "Track" application to initially focus the lens on the eye. With these two additions, there is no need for the "EyeLink display" for most experimental runs.

See also

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