Contributions:EyetrackerLoggerEyeLink - Revision history

Mellinger at 13:28, 1 July 2025

2025-07-01T13:28:50Z

← Older revision		Revision as of 13:28, 1 July 2025
Line 1:		Line 1:
	An BCI2000 extension that records synchronized physiological data, such as gaze position, pupil size, and blinks, from ''EyeLink Eyetrackers'' into state variables.		A BCI2000 extension that records synchronized physiological data, such as gaze position, pupil size, and blinks, from ''EyeLink Eyetrackers'' into state variables.

	[[File:Eyelink.png\|right\|thumb\| An image of the EyeLink 1000 Plus eye tracker]]		[[File:Eyelink.png\|right\|thumb\| An image of the EyeLink 1000 Plus eye tracker]]

Wengelhardt: /* See also */

2024-09-03T18:03:17Z

Wengelhardt at 20:23, 19 November 2021

2021-11-19T20:23:26Z

← Older revision		Revision as of 20:23, 19 November 2021
Line 20:		Line 20:

	==Video Overview==		==Video Overview==
	<youtube alignment="center">https://youtu.be/MYie72oDVnI</youtube>		<br>
			<youtube alignment="center" dimensions="900">https://youtu.be/MYie72oDVnI</youtube>
			<br>

	==Functional Description==		==Functional Description==

Wengelhardt: Added tutorial video

2021-11-19T17:32:53Z

Added tutorial video

← Older revision		Revision as of 17:32, 19 November 2021
Line 15:		Line 15:
	===Source Code Revisions===		===Source Code Revisions===
	*Initial development: 6309		*Initial development: 6309
	*Tested under: ~~6309~~		*Tested under: 6433
	*Known to compile under: ~~6328~~		*Known to compile under: 6433
	*Broken since: --		*Broken since: --

			==Video Overview==
			<youtube alignment="center">https://youtu.be/MYie72oDVnI</youtube>

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

	==Integration into BCI2000==		==Integration into BCI2000==
Line 197:		Line 200:
	EyeLink is fully functional with [[Contributions:GazeMonitorFilter \| 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:		EyeLink is fully functional with [[Contributions:GazeMonitorFilter \| 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 <code>VisualizeGazeMonitorFilter</code> (in the GazeMonitor section of the application tab) and <code>VisualizeApplicationWindow</code> (in the Application Window section of the Visualize tab) are both on		*To visualize any data, make sure that <code>VisualizeGazeMonitorFilter</code> (in the GazeMonitor section of the application tab) and <code>VisualizeApplicationWindow</code> (in the Application Window section of the Visualize tab) are both on
	*To visualize gaze data, <code>--LogGazeData=1</code> must additionally be specified in the batch file, appended after <code>--LogEyetrackerEyeLink=1</code>
	*[[Contributions:GazeMonitorFilter \| 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 [[Contributions:GazeMonitorFilter \| 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.		*[[Contributions:GazeMonitorFilter \| 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 [[Contributions:GazeMonitorFilter \| 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.

Wengelhardt at 01:20, 17 November 2021

2021-11-17T01:20:20Z

← Older revision		Revision as of 01:20, 17 November 2021
Line 35:		Line 35:
	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 [https://www.sr-support.com/attachment.php?aid=576 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.		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 [https://www.sr-support.com/attachment.php?aid=576 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.

	[[File:EyeLinkSetUp.png\|700px\|Image: 700 pixels]]		[[File:EyeLinkSetUp.png\|700px\|Image: 700 pixels\|center]]

	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.		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.
Line 76:		Line 76:
	*''Pupil size'': The area of the pupil, in arbitrary units. Best recorded as a percent change relative to a baseline.		*''Pupil size'': The area of the pupil, in arbitrary units. Best recorded as a percent change relative to a baseline.

	[[File:EyeLinkCoordinateSystem.png]]		[[File:EyeLinkCoordinateSystem.png\|center]]

	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.		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==		==Parameters==

			[[File:EyeLinkParameters.PNG\|center]]

	===User configurable Parameters===		===User configurable Parameters===
	The eye tracker is configured in the Source tab within the EyetrackerLogger section.		The eye tracker is configured in the Source tab within the EyetrackerLogger section.
Line 87:		Line 90:
	Set to 0 (uncheck) to disable the eye tracker logger. This should be set in your batch file by appending <code>--LogEyetrackerEyeLink=1</code> to the source module <tt>start executable</tt> command.		Set to 0 (uncheck) to disable the eye tracker logger. This should be set in your batch file by appending <code>--LogEyetrackerEyeLink=1</code> to the source module <tt>start executable</tt> command.

	====~~EyeLinkHostAddress~~====		====DataType====
	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~~.		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====		====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.		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====		====ExperimentParams====
Line 152:		Line 158:
	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.		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~~===		===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.		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.

Wengelhardt at 00:02, 13 November 2021

2021-11-13T00:02:17Z

← Older revision		Revision as of 00:02, 13 November 2021
Line 35:		Line 35:
	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 [https://www.sr-support.com/attachment.php?aid=576 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.		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 [https://www.sr-support.com/attachment.php?aid=576 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.

	[[File:EyeLinkSetUp.png]]		[[File:EyeLinkSetUp.png\|700px\|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.		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.

Wengelhardt: Added implementation for specifying which eye

2021-10-22T19:00:19Z

Added implementation for specifying which eye

← Older revision		Revision as of 19:00, 22 October 2021
Line 24:		Line 24:
	==Integration into BCI2000==		==Integration into BCI2000==
	To enable the extension in your CMake configuration, enable <tt>EXTENSIONS_EYETRACKERLOGGEREYELINK=On</tt> 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 <tt>BCI2000FrameworkSigSrcModule</tt>, and then rebuild any signal source module you want to use the extension with.		To enable the extension in your CMake configuration, enable <tt>EXTENSIONS_EYETRACKERLOGGEREYELINK=On</tt> 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 <tt>BCI2000FrameworkSigSrcModule</tt>, 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 <code>--LogEyetrackerEyeLink=1</code> to the source module <tt>start executable</tt> command in your batch file.		Once the extension is built into the source module, you can enable it by appending <code>--LogEyetrackerEyeLink=1</code> to the source module <tt>start executable</tt> command in your batch file.

			You can also optionally add <code>--WhichEye=</code>, where you can specify left eye: <code>Left</code> or <code>0</code> or right eye: <code>Right</code> or <code>1</code>. 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==		==Installation and Set-Up==

Wengelhardt at 19:54, 24 September 2021

2021-09-24T19:54:30Z

← Older revision		Revision as of 19:54, 24 September 2021
Line 36:		Line 36:

	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.		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====		====IP address====
Line 125:		Line 127:
	function s = ToSigned(u)		function s = ToSigned(u)
	dU = double(u);		dU = double(u);
	iU = (dU > 2^15);		iU = (dU >= 2^15);
	tempU = dU - iU*2^15;		tempU = dU - iU*(2^15-1);
	s = tempU - 2tempU.iU;		s = tempU - 2tempU.iU;
	end		end

Wengelhardt: Added picture

2021-07-26T19:21:58Z

Added picture

← Older revision		Revision as of 19:21, 26 July 2021
Line 1:		Line 1:
	An BCI2000 extension that records synchronized physiological data, such as gaze position, pupil size, and blinks, from ''EyeLink Eyetrackers'' into state variables.		An BCI2000 extension that records synchronized physiological data, such as gaze position, pupil size, and blinks, from ''EyeLink Eyetrackers'' into state variables.

			[[File:Eyelink.png\|right\|thumb\| An image of the EyeLink 1000 Plus eye tracker]]

	==Location==		==Location==

Wengelhardt: Additional detail for software set-up

2021-07-09T15:42:52Z

Additional detail for software set-up

← Older revision		Revision as of 15:42, 9 July 2021
Line 40:		Line 40:
	===Software Set-Up===		===Software Set-Up===
	====Experimental Set-Up====		====Experimental Set-Up====
	Before continuing, make sure everything is set-up as previously mentioned.		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''====		====''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.		The “Display Resolution” parameter is taken from “WindowHeight” and “WindowWidth” in the Application tab. All the other configurable settings are located in the parameter <code>ExperimentParams</code>. Look at the parameter definition below for details in measurements.
	====''Without BCI2000''====		====''Without BCI2000''====
	# Open the EyeLink File Manager		# Open the EyeLink File Manager

← Older revision		Revision as of 18:03, 3 September 2024
Line 207:		Line 207:
	[[User Reference:Logging Input]], [[Contributions:Extensions]], [[Contributions:EyetrackerLogger]], [[Contributions:EyetrackerLoggerTobiiPro]]		[[User Reference:Logging Input]], [[Contributions:Extensions]], [[Contributions:EyetrackerLogger]], [[Contributions:EyetrackerLoggerTobiiPro]]

	[[Category:Contributions]][[Category:Extension]]		[[Category:Contributions]][[Category:Extension]][[Category:Video]]