View source for Contributions:EyetrackerLoggerTobiiX

==Synopsis==
An extension that records state information from ''Tobii Eyetrackers Eye X'' into state variables.

==Location==
http://{{SERVERNAME}}/svn/trunk/src/contrib/Extensions/EyetrackerLoggerTobiiX

==Versioning==
===Authors===
Kristopher Kaleb Goering (kaleb.goering@gmail.com)
===Version History===
: Initial public release;
2015/07/01 
===Source Code Revisions===
*Initial development: 4880
*Tested under: 4880
*Known to compile under: 4880
*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.  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_EYETRACKERLOGGERTOBIIX'''.  Once the extension is built into the source module, enable it by starting the source module with the <code>--LogEyetrackerTobiiX=1</code> 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 an USB 3.0 port.  When you start the source module, ensure that the <code>--LogEyetrackerTobiiX=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. 

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. Upon connecting the eyetracker to the computer via USB port, it should ask for calibration. '''Note''' - the Tobii Eyetracker Eye X requires SS USB 3.0 port to communicate. It cannot use USB 2.0 ports.

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:

*<code>LogEyetrackerTobiiX</code>   - Enables/Disables logging of Eyetracker states
*<code>LogGazeData</code> - Enables/Disables logging of gaze data
*<code>LogEyePos</code> - Enables/Disables logging of eye position (as seen from the camera)
*<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>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. 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.
<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==
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.

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

===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. 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==
[[User Reference:Logging Input]], [[Contributions:Extensions]], [[Contributions:EyetrackerLogger]]

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