Contributions:EyetrackerLogger - Revision history

Mellinger: /* Synopsis */

2025-07-01T13:10:23Z

Synopsis

← Older revision		Revision as of 13:10, 1 July 2025
Line 1:		Line 1:
	==Synopsis==		==Synopsis==
	A ~~filter~~ that records state information from ''Tobii Eyetrackers'' into state variables.		A logger extension that records state information from ''Tobii Eyetrackers'' into state variables.

	==Location==		==Location==

Wengelhardt: /* Usage and Calibration */

2021-06-10T17:29:31Z

Usage and Calibration

← Older revision		Revision as of 17:29, 10 June 2021
Line 34:		Line 34:
	Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).		Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).

	BCI2000 does not provide any way to calibrate the eyetracker. This should be done using the Tobii SDK sample application. The SDK can be obtained here: http://www.tobii.com/analysis-and-research/global/products/software/tobii-software-development-kit/. The 2.0 or Beta 3.0 SDK can be used to calibrate the device. When installed, open <code>C:\Program Files\Tobii\Tobii Eye Tracker SDK 2.0.1\samples\<\code> for the 2.0.1 SDK or <code>C:\Program Files\Tobii\SDK\Samples\</code> for the 3.0 Beta SDK and find the "Eye Tracker Components C++" or "EyetrackerComponents.Cpp" sample project. There should be a pre-built executable in this directory or a "prebuild" directory which can be used to run a calibration. Use the network address from the Eyetracker Browser and follow the instructions to calibrate and test your device. When you're done you can close the calibration utility and run BCI2000 - which will use the calibration saved on the device.		BCI2000 does not provide any way to calibrate the eyetracker. This should be done using the Tobii SDK sample application. The SDK can be obtained here: http://www.tobii.com/analysis-and-research/global/products/software/tobii-software-development-kit/. The 2.0 or Beta 3.0 SDK can be used to calibrate the device. When installed, open <code>C:\Program Files\Tobii\Tobii Eye Tracker SDK 2.0.1\samples\</code> for the 2.0.1 SDK or <code>C:\Program Files\Tobii\SDK\Samples\</code> for the 3.0 Beta SDK and find the "Eye Tracker Components C++" or "EyetrackerComponents.Cpp" sample project. There should be a pre-built executable in this directory or a "prebuild" directory which can be used to run a calibration. Use the network address from the Eyetracker Browser and follow the instructions to calibrate and test your device. When you're done you can close the calibration utility and run BCI2000 - which will use the calibration saved on the device.

	If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.		If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.

Gmilsap: /* EyetrackerStatesOK */ Clarified how GazeOffset and GazeScale relate to EyetrackerStatesOK

2011-06-15T13:06:18Z

EyetrackerStatesOK: Clarified how GazeOffset and GazeScale relate to EyetrackerStatesOK

← Older revision		Revision as of 13:06, 15 June 2011
Line 110:		Line 110:

	===EyetrackerStatesOK===		===EyetrackerStatesOK===
	Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data.		Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data. Use the "GazeOffset" and "GazeScale" parameters to avoid clamping. Those parameters scale and offset the data so that when it does go out of range, it can still be fit into the 16 bit state.

	==See also==		==See also==

Gmilsap: /* Usage and Calibration */

2011-06-14T13:12:00Z

Usage and Calibration

← Older revision		Revision as of 13:12, 14 June 2011
Line 30:		Line 30:

	==Usage and Calibration==		==Usage and Calibration==
	Set up the eyetracker as detailed in the documentation that came with your device. The device will connect to your machine and communicate through the ethernet port. As such, it'd be wise to disconnect and turn off any other networking devices while using the eyetracker. It is possible that your network request could go out over a different network interface if you're not careful which makes for a troubleshooting nightmare. When you start the source module, ensure that the </code>--LogEyetracker=1<code> command line parameter is set. Run the Eyetracker Browser utility which came with your eyetracker drivers and use it to locate the device on your local network. Copy the network address to the clipboard and paste it in the <code>NetworkLocation</code> parameter within BCI2000. If the listed port is different, put that in the <code>Port</code> parameter in the BCI2000 operator.		Set up the eyetracker as detailed in the documentation that came with your device. The device will connect to your machine and communicate through the ethernet port. As such, it'd be wise to disconnect and turn off any other networking devices while using the eyetracker. It is possible that your network request could go out over a different network interface if you're not careful which makes for a troubleshooting nightmare. When you start the source module, ensure that the <code>--LogEyetracker=1</code> command line parameter is set. Run the Eyetracker Browser utility which came with your eyetracker drivers and use it to locate the device on your local network. Copy the network address to the clipboard and paste it in the <code>NetworkLocation</code> parameter within BCI2000. If the listed port is different, put that in the <code>Port</code> parameter in the BCI2000 operator.

	Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).		Calibration can now occur. Calibration should be done per subject per sitting. Re-calibration is not necessary between runs, but any time that the subject changes eyewear, makeup, or position, or if the lighting conditions change it should be re-calibrated. A good rule of thumb would be to recalibrate at the start of every session. Once a calibration is performed, it is saved in the Tobii device until the next calibration (even if there's a power loss).
Line 38:		Line 38:
	If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.		If you're using an T60/T120 or any future Tobii eyetracker with an attached display, you'll probably have it in a dual screen setup showing different things on both monitors - either extended or dualview. Typically, the Tobii monitor is used to present the task to the subject and the other monitor is used for the experimenter to control BCI2000 from. This can present a bit of a problem when calibrating because the sample application will only run on your "primary display" which may or may not be your Tobii monitor. Either set your primary display to be the Tobii screen or temporarily set the screen configuration into "clone" mode. A different screen resolution or aspect ratio does not impact the Tobii calibration process.

	Once the device is calibrated, it can be used reliably in BCI2000. The logger will report information about eye validity in a text visualization window and feed states into the system.		Once the device is calibrated, it can be used reliably in BCI2000. The logger will report information about eye validity in a text visualization window and feed states into the system.

	==Parameters==		==Parameters==

Gmilsap: /* Parameters */ - Added quick code snippet which transforms states

2011-06-14T12:55:14Z

Parameters: - Added quick code snippet which transforms states

← Older revision		Revision as of 12:55, 14 June 2011
Line 54:		Line 54:

	Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.		Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

			The following code retreives the actual ~(0.0-1.0) range that the eyetracker outputs directly (assuming you've scaled and offset the signal to avoid clipping) from each eye and averages it to find a gaze position.
			<pre>
			float x = State( "EyetrackerLeftEyeGazeX" ) + State( "EyetrackerRightEyeGazeX" ); x /= ( 2.0f * 65535.0f );
			float y = State( "EyetrackerLeftEyeGazeY" ) + State( "EyetrackerRightEyeGazeY" ); y /= ( 2.0f * 65535.0f );
			x -= ( float )Parameter( "GazeOffset" ); x /= ( float )Parameter( "GazeScale" );
			y -= ( float )Parameter( "GazeOffset" ); y /= ( float )Parameter( "GazeScale" );
			</pre>

	==State Variables==		==State Variables==

Gmilsap: /* Versioning */

2011-06-10T18:52:43Z

Versioning

← Older revision		Revision as of 18:52, 10 June 2011
Line 10:		Line 10:
	===Version History===		===Version History===
	06/09/2011: Initial public release;		06/09/2011: Initial public release;
			06/10/2011: Hacked in scale and offset for gaze data;

	===Source Code Revisions===		===Source Code Revisions===

Gmilsap: /* Parameters */ - Addition of two new parameters for scaling gaze data

2011-06-10T18:51:57Z

Parameters: - Addition of two new parameters for scaling gaze data

← Older revision		Revision as of 18:51, 10 June 2011
Line 49:		Line 49:
	*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)		*<code>LogPupilSize</code> - Enables/Disables logging of pupil size (very rough)
	*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)		*<code>LogEyeDist</code> - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
			*<code>GazeScale</code> - Scales the incoming gaze data first
			*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling

			Note: GazeScale and GazeOffset are quick hacks to address an issue with gaze data being clamped around the edges of the screen. The eyetracker gives back values which are between 0.0 and 1.0 for onscreen gaze but supports looking slightly offscreen by allowing gaze data returned to go above 1.0 and below 0.0. BCI2000 needs this scaled between 0.0 and 1.0 before the gaze data is multiplied by 65535 for storage in the 16 bit state. These two parameters account for this scaling and offset and prevents the clamping from happening as often as it would otherwise. These parameters will be removed once BCI2000 supports typed states.

	==State Variables==		==State Variables==

Gmilsap: /* EyetrackerStatesOK */

2011-06-10T15:34:06Z

EyetrackerStatesOK

← Older revision		Revision as of 15:34, 10 June 2011
Line 97:		Line 97:

	===EyetrackerStatesOK===		===EyetrackerStatesOK===
	Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data.		Early versions of the extension didn't take into account that the library may return a number greater than 1.0 or less than 0.0. This resulted in "pac-man" style wrap around of gaze coordinates in 2.0 and crashes in 3.0. If the output from the library is out of bounds, it is clamped to the boundaries and the "EyetrackerStatesOK" parameter is changed. A value of "1" corresponds to valid gaze data, a value of "0" corresponds to invalid "clamped" gaze data.

	==See also==		==See also==

Gmilsap: /* EyeValidity */ -- suggestion

2011-06-10T15:33:29Z

EyeValidity: -- suggestion

← Older revision		Revision as of 15:33, 10 June 2011
Line 93:		Line 93:
	\| No eye found. Gaze data for both eyes are invalid.		\| No eye found. Gaze data for both eyes are invalid.
	\|}		\|}

			It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.

	===EyetrackerStatesOK===		===EyetrackerStatesOK===

Gmilsap: /* Versioning */

2011-06-10T15:32:40Z

Versioning

← Older revision		Revision as of 15:32, 10 June 2011
Line 10:		Line 10:
	===Version History===		===Version History===
	06/09/2011: Initial public release;		06/09/2011: Initial public release;
	~~===Todo===~~
	*Upgrade SDK version to 3.0 (once it's out of beta)
	*Include a fixation/monitor filter
	*Maybe a Qt calibration app

	===Source Code Revisions===		===Source Code Revisions===
Line 20:		Line 16:
	*Known to compile under: 3318		*Known to compile under: 3318
	*Broken since: --		*Broken since: --

			===Todo===
			*Upgrade SDK version to 3.0 (once it's out of beta)
			*Include a fixation/monitor filter
			*Maybe a Qt calibration app

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