Difference between revisions of "Contributions:EyetrackerLoggerTobii3"

From BCI2000 Wiki
Jump to: navigation, search
Line 8: Line 8:
 
===Authors===
 
===Authors===
 
Kristopher Kaleb Goering (kaleb.goering@gmail.com)
 
Kristopher Kaleb Goering (kaleb.goering@gmail.com)
 +
 +
Jürgen Mellinger (mellinger@neurotechcenter.org)
 
===Version History===
 
===Version History===
06/23/2015: Initial public release;
+
*2015-06-23: Initial public release
 +
*2017-08-21:
 +
**adapted code to current version of BCI2000 framework
 +
**rewrote large parts for clarity
 +
**unified coordinate system for eye position, and gaze data
  
 
===Source Code Revisions===
 
===Source Code Revisions===
 
*Initial development: 4879
 
*Initial development: 4879
*Tested under: 4879
+
*Tested under: 5696
*Known to compile under: 4879
+
*Known to compile under: 5696
 
*Broken since: --
 
*Broken since: --
  
Line 21: Line 27:
  
 
==Integration into BCI2000==
 
==Integration into BCI2000==
Compile the extension into your source module by enabling contributed extensions in your CMake configuration.  You can do this by going into your root build folder and deleting <code>CMakeCache.txt</code> and re-running the project batch file, or by running <code>cmake -i</code> and enabling '''BUILD_EYETRACKERLOGGERTOBII3'''. Once the extension is built into the source module, enable it by starting the source module with the <code>--LogEyetrackerTobii3=1</code> command line argument.
+
Compile the extension into your source module by enabling contributed extensions in your CMake configuration, and setting <tt>EXTENSIONS_EYETRACKERLOGGERTOBII3=On</tt>.
 +
Once the extension is built into the source module, enable it by starting the source module with the <code>--LogEyetrackerTobii3=1</code> command line argument.
  
 
==Usage and Calibration==
 
==Usage and Calibration==
Line 40: Line 47:
 
*<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>GazeScale</code> - Scales the incoming gaze data first (deprecated)
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling
+
*<code>GazeOffset</code> - Offsets the incoming gaze data after scaling (deprecated)
 
 
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. Brought from EyetrackerLogger
 
  
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.
+
Note: <tt>GazeScale</tt> and <tt>GazeOffset</tt> were quick hacks introduced in the original [EyetrackerLogger] to address an issue with gaze data being clamped around the edges of the screen. EyetrackerLoggerTobii3 uses additional bits to avoid issues with values being out of range, so these parameters serve no useful purpose any more, but are being kept for backward compatibility.
<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==
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye.  The EyetrackerLogger extension does not support subjects with more than two eyes at the moment.
+
Unless otherwise specified, all states are prefixed with <code>Eyetracker<Left/Right>Eye</code> which corresponds with each individual eye.  The EyetrackerLogger extension does not support eye tracking with multiple subjects.
  
 
===GazeX, GazeY===
 
===GazeX, GazeY===
The eye gaze position (where - on the screen - the subject is looking) is returned from the Tobii SDK as 32 bit floating point numbers which (roughly) range from 0.0 to 1.0.  They are multiplied by 65535 and stored as 16 bit integers in these states if the <code>LogGazeData</code> parameter is enabled.  (0,0) corresponds to the top left of the screen, (65535,65535) corresponds to the right bottom of the screen. -- See [[Contributions:EyetrackerLogger#EyetrackerStatesOK|EyetrackerStatesOK]].
+
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.
  
===PosX, PosY===
+
===PosX, PosY, Dist===
The eye position relative to the camera in 2D space is returned if <code>LogEyePos</code> is enabled.  Again, these are returned from the library as floating point numbers from 0.0 to 1.0 and are scaled to 16 bit integer values from 0 to 65535.  (0,0) corresponds to the top left of the camera's view, and (65535,65535) corresponds to the bottom right of the camera's view.
+
Eye position in the same screen-relative coordinate system used for GazeX and GazeY, extended by a Z axis normal to the screen plane, 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.
  
 
===PupilSize===
 
===PupilSize===
The pupil size in mm is saved in this state if <code>LogPupilSize</code> is enabled.  It corresponds to the length of the longest chord drawn from one side of the pupil to the other.  The size will change depending on the eye position and distance from the screen.  Although it is given in mm, it would be best to use this as a relative measurement.
+
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).
 
 
===EyeDist===
 
The distance between the screen and the eyes in mm is saved in this state if <code>LogEyeDist</code> is enabled. This measurement is an approximation.  The actual measurement will depend on whether or not the test subject is wearing glasses or not.
 
  
 
===EyeValidity===
 
===EyeValidity===
Line 97: Line 93:
 
|}
 
|}
  
It'd probably be wise to remove all data points with a validity state of 2 or higher while running your analysis.
+
EyetrackerLoggerTobii3 will record <tt>EyeValidity</tt> for all data received from the eye tracker but will ignore any gaze and position data for <tt>EyeValidity >= 2</tt>.  
  
 
===EyetrackerTimeStamp===
 
===EyetrackerTimeStamp===
With the update to the 3.0 SDK, the added functionality of a time stamp on the frame of data is gathered from the eye tracker. It is then normalized to match the BCI2000 SourceTime. With this added state, you can check the input signals with the gaze direction of the subject or any other state. It is stored in ms like SourceTime.
+
Time stamp of eye data as reported by the eye tracker, and converted into the time units used to  
 
+
represent the [SourceTime] data time stamp.
===EyetrackerStatesOK===
+
Eye tracker data will be sample-aligned using this time stamp if possible, but may appear delayed
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.
+
in a data file if transmission from the eye tracker is late.
 +
In this case, the value of <tt>EyetrackerTimeStamp</tt> will differ from the value of [SourceTime] by more than a sample block duration.  
  
 
==See also==
 
==See also==

Revision as of 14:57, 22 August 2017

Synopsis

A filter that records state information from Tobii Eyetrackers using the Tobii SDK 3.0 into state variables.

Location

http://www.bci2000.org/svn/trunk/src/contrib/Extensions/EyetrackerLoggerTobii3

Versioning

Authors

Kristopher Kaleb Goering (kaleb.goering@gmail.com)

Jürgen Mellinger (mellinger@neurotechcenter.org)

Version History

  • 2015-06-23: Initial public release
  • 2017-08-21:
    • adapted code to current version of BCI2000 framework
    • rewrote large parts for clarity
    • unified coordinate system for eye position, and gaze data

Source Code Revisions

  • Initial development: 4879
  • Tested under: 5696
  • Known to compile under: 5696
  • Broken since: --

Functional Description

In many cases, an experiment may require data about where the participant is looking. In these experiments, an eyetracker is the only way to gather data relating to gaze position and eye location. There are many eyetracking methods currently on the market, but many of these require the subject to hold their head steady -- often while strapped to a structure of some sort. The Tobii eyetrackers require no such restriction so they were a natural choice when it came to interfacing with BCI2000.

Integration into BCI2000

Compile the extension into your source module by enabling contributed extensions in your CMake configuration, and setting EXTENSIONS_EYETRACKERLOGGERTOBII3=On. Once the extension is built into the source module, enable it by starting the source module with the --LogEyetrackerTobii3=1 command line argument.

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 --LogEyetrackerTobii3=1 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.

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.Calibration.exe program which came on the thumb drive with the eyetracker. It can be found in Setup/InstallationGuide. Run the executable and follow the onscreen instructions to calibrate.

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

The eyetracker is configured in the Source tab within the EyetrackerLogger section. The configurable parameters are:

  • LogEyetrackerTobii3 - Enables/Disables logging of Eyetracker states
  • LogGazeData - Enables/Disables logging of gaze data
  • LogEyePos - Enables/Disables logging of eye position (as seen from the camera)
  • LogPupilSize - Enables/Disables logging of pupil size (very rough)
  • LogEyeDist - Enables/Disables logging of the distance from the screen to the eyes (again, rough)
  • GazeScale - Scales the incoming gaze data first (deprecated)
  • GazeOffset - Offsets the incoming gaze data after scaling (deprecated)

Note: GazeScale and GazeOffset were quick hacks introduced in the original [EyetrackerLogger] to address an issue with gaze data being clamped around the edges of the screen. EyetrackerLoggerTobii3 uses additional bits to avoid issues with values being out of range, so these parameters serve no useful purpose any more, but are being kept for backward compatibility.

State Variables

Unless otherwise specified, all states are prefixed with Eyetracker<Left/Right>Eye which corresponds with each individual eye. The EyetrackerLogger extension does not support eye tracking with multiple subjects.

GazeX, GazeY

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.

PosX, PosY, Dist

Eye position in the same screen-relative coordinate system used for GazeX and GazeY, extended by a Z axis normal to the screen plane, 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.

PupilSize

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).

EyeValidity

This state is a number from 0 to 4 and is documented in the Tobii SDK manual. It is repeated here for convenience.

  • 0 - The eye tracker is certain that the data for this eye is right. There is no risk of confusing data from the other eye.
  • 1 - The eye tracker has only recorded one eye and made some assumptions and estimations regarding which is the left and which is the right eye. However, it is still very likely that the assumption made is correct. The validity code for the other eye is in this case always set to 3.
  • 2 - The eye tracker has only recorded one eye, and has no way of determining which one is the left eye and which one is the right eye. The validity code for both eyes is set to 2.
  • 3 - The eye tracker is fairly confident that the actual gaze data belongs to the other eye. The other eye will always have validity code 1.
  • 4 - The actual gaze data is missing or definitely belonging to the other eye.
Code (Right - Left) Description
0 - 0 Both eyes found. Data is valid for both eyes.
0 - 4 or 4 - 0 One eye found. Gaze data is the same for both eyes.
1 - 3 or 3 - 1 One eye found. Gaze data is the same for both eyes.
2 - 2 One eye found. Gaze data is the same for both eyes.
4 - 4 No eye found. Gaze data for both eyes are invalid.

EyetrackerLoggerTobii3 will record EyeValidity for all data received from the eye tracker but will ignore any gaze and position data for EyeValidity >= 2.

EyetrackerTimeStamp

Time stamp of eye data as reported by the eye tracker, and converted into the time units used to represent 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 EyetrackerTimeStamp will differ from the value of [SourceTime] by more than a sample block duration.

See also

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