- 1 Synopsis
- 2 Location
- 3 Versioning
- 4 Functional Description
- 5 Integration into BCI2000
- 6 Usage and Calibration
- 7 Parameters
- 8 State Variables
- 8.1 EyetrackerTime
- 8.2 EyetrackerLeftEyeGazeX, EyetrackerLeftEyeGazeY, EyetrackerRightEyeGazeX, EyetrackerRightEyeGazeY
- 8.3 EyetrackerLeftEyePosX, EyetrackerLeftEyePosY, EyetrackerLeftEyeDist, EyetrackerRightEyePosX, EyetrackerRightEyePosY, EyetrackerRightEyeDist
- 8.4 EyetrackerLeftPupilSize, EyetrackerRightPupilSize
- 8.5 EyetrackerLeftEyeValidity, EyetrackerRightEyeValidity
- 9 See also
A filter that records state information from Tobii Eyetrackers using the Tobii SDK 3.0 into state variables.
Kristopher Kaleb Goering (email@example.com)
Jürgen Mellinger (firstname.lastname@example.org)
- 2015-06-23: Initial public release
- 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: --
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.
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.
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.
Time stamp of eye data as reported by the eye tracker, and converted into time units compatible with 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 in milliseconds.
EyetrackerLeftEyeGazeX, EyetrackerLeftEyeGazeY, EyetrackerRightEyeGazeX, EyetrackerRightEyeGazeY
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.
EyetrackerLeftEyePosX, EyetrackerLeftEyePosY, EyetrackerLeftEyeDist, EyetrackerRightEyePosX, EyetrackerRightEyePosY, EyetrackerRightEyeDist
Eye position in the same screen-relative coordinate system used for gaze data, 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.
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).
A number ranging between 0 and 4, representing the eyetracker's confidence to have identified the eye in question. As suggested in the Tobii3 SDK's manual, EyetrackerLoggerTobii3 will ignore any _eye_data_ with an associated validity value greater or equal to 2, but will report time stamp and validity value for that data point nevertheless. When eye data are being ignored, all respective state variables will keep their previous values.