Eyelink
The Eyelink series of eye trackers, produced by SR Research, are one of the most commonly used eye trackers in psychological research. SR Research provides Python bindings for the Eyelink, which are used by the OpenSesame Eyelink plug-ins. The license of the Eyelink Python bindings is incompatible with the license used by OpenSesame. For that reason, the Eyelink does not work out of the box with the official distribution of OpenSesame.
To use OpenSesame with the Eyelink, there are two options:
- Easy: Use the Python portable-based OpenSesame package (link), which runs OpenSesame with Eyelink support out of the box.
-
Advanced: Install all dependencies per the instructions below.
- Running in dummy mode
- SR Research forum
- System requirements
- Step 1: Installing OpenSesame from source
- Step 2: Installing the Python Imaging Library
- Step 3: Installing Eyelink display software
- Step 4: Installing PyLink
- Step 5: Installing the OpenSesame Eyelink plug-ins
- Step 6: Running OpenSesame with Eyelink support!
- Documentation, examples and function overview
Running in dummy mode
You need to walk through the steps below only for the computer to which the Eyelink is actually attached. You can easily install the OpenSesame eyelink plug-ins on your own computer, as per step 5, without having to install anything or having to run OpenSesame from source. Obviously, you can only run the plug-in in ‘dummy mode’ in this case, but this is very convenient while developing and testing your experiment.
SR Research forum
You will need to download some software from the SR Research forum. This is a closed forum, but you can register free of charge.
System requirements
This tutorial has been written primarily for Windows XP 32-bit, for the simple reason that our own Eyelink PC uses this OS. Instructions for Ubuntu are also provided, but have not been tested extensively. You may still find this tutorial a useful resource when trying to install the OpenSesame Eyelink plug-ins on a different OS, but things will obviously work a little differently.
Step 1: Installing OpenSesame from source
Windows XP
The Windows binary of OpenSesame comes with its own Python environment and can only make use of the modules that have been included (PyGame, NumPy, etc.). Since PyLink is not included, and due to licensing restrictions probably never will be included, with OpenSesame, you will have to run OpenSesame from source. The following tutorial describes how to set-up the environment necessary for running OpenSesame from source:
- </getting-opensesame/running-from-source>
Ubuntu
Under Linux, you can simply install OpenSesame as described here.
Step 2: Installing the Python Imaging Library
Windows XP
The Python Imaging Library is used to do some juggling between various image formats. You can download it here (make sure you download the most recent version for Python 2.6):
Ubuntu
The Python imaging library is probably installed already. If not, run the following command in a terminal:
sudo apt-get install python-imaging
Step 3: Installing Eyelink display software
Windows XP
The Eyelink display software provides the libraries that are required to communicate with the Eyelink PC. You can find it here:
Add the following directory to the Path (this may have been added to the path automatically, but check to make sure):
C:\Program Files\SR Research\EyeLink\libs
You can do this by opeing “My Computer”, clicking on “View system information”, opening the “Advanced” tab, clicking on “Environment Variables” and appending ;C:\Program Files\SR Research\EyeLink\libs to the Path variable (under System variables).
Ubuntu
There is a repository with the Eyelink display software available for Ubuntu Linux. To add this repository to your software sources, type the following in a terminal:
sudo nano /etc/apt/sources.list
This will open the software sources in a simple text editor. At the bottom of the file, add the following lines for 32 bit systems:
# Eyelink repository (32bit)
deb http://download.sr-support.com /
For 64 bit, add the following lines:
# Eyelink repository (64bit)
deb http://download.sr-support.com/x64 /
Save the file (Control+O, Enter) and exit (Control+X). Now reload the software sources, and install the Eyelink display software (the version number might vary, at the time of writing it is 1.9):
sudo apt-get update
sudo apt-get install eyelink-display-software1.9
For more information, please visit:
- <https://www.sr-support.com/showthread.php?16-Linux-Display-Software-Package>
Step 4: Installing PyLink
PyLink is a Python wrapper around the display software.
Windows XP
There are two versions of PyLink: one with custom SDL and one without custom SDL. The reason that SR Research has changed some functionality in SDL (the Simple DirectMedia Layer, which is a set of libraries used to control the display etc.) is to improve timing accuracy. This is nice, but in the case of OpenSesame it is only relevant if you use the legacy (pygame) back-end: xpyriment and psycho have excellent timing regardless of which pylink version is used. The downside of pylink’s custom SDL is that you may encounter compatibility issues.
The bottom line: Initially, you may want to use the with SDL version of pylink, because this is the default version. However, if you encounter weird issues (such as sound not working), you may want to try the without SDL version of pylink.
Pylink with custom SDL
You can find it here:
Download the pylink_win32.zip package and (assuming that you have installed Python to c:\Python26) copy the pylink26 folder in its entirety to
c:\Python26\Lib\site-packages
and rename the folder to pylink.
Pylink without custom SDL
You can find it here:
Copy the pylink folder in its entirety to
c:\Python26\Lib\site-packages
Ubuntu
Download the correct PyLink for your distribution from here (make sure that you have the correct Python version, usually 2.7, and chipset, x64 for 64 bit and x32 for 32 bit):
Extract it to a location of your choice and rename the pylink27 folder to pylink.
Step 5: Installing the OpenSesame Eyelink plug-ins
All platforms
You can download the latest Eyelink plug-ins from GitHub:
Extract the archive and put all the folders (eyelink_calibrate, etc.) directly into the plugins folder of OpenSesame, as per these instructions:
Step 6: Running OpenSesame with Eyelink support!
Windows XP
You’re done! If you have installed the with SDL version of PyLink, you need to start OpenSesame with the --pylink command line argument (again, assuming that Python is installed in c:\Python26):
c:\Python26\python.exe opensesame --pylink
If you start OpenSesame now, you should see the Eyelink plug-ins appear as additional items in the item toolbar (as in the screenshot below). You can drag and drop these items into your experiment!
Ubuntu
You can start OpenSesame in the usual way from the applications menu, or by running the following command in a terminal:
opensesame
Documentation, examples and function overview
You can find a tutorial for using the OpenSesame Eyelink plug-ins here (PDF).
The following experiment, kindly provided by Daniel Schreij, shows how to use the OpenSesame Eyelink plug-ins from the graphical interface:
Schreij, D., Owens, C., & Theeuwes, J. (2008). Abrupt onsets capture attention independent of top-down control settings. Perception & Psychophysics, 70(2), 208-218.
The example below shows how to display the trajectory of an eye movement immediately after every trial, using Python inline code. I created this as a demonstration of saccadic curvature for a class of students.
You can also access the Eyelink using python in an inline_script item. The eyelink class is a property of the experiment class, which (in an inline_script item) you can access like this:
exp.eyelink
So, for example, you can do the following:
exp.eyelink.log("Message for the EDF")
time, start_pos = exp.eyelink.wait_for_saccade_start()
time, start_pos, end_pos = exp.eyelink.wait_for_saccade_end()
x, y = exp.eyelink.sample()
Below is the full list of available functions. It is also possible to use the PyLink API directly, but I recommend using the libeyelink functions, which are considerably easier to use.
Function overview:
__init__
calibrate
close
connected
drift_correction
fix_triggered_drift_correction
get_eyelink_clock_async
log
log_var
manual_drift_correction
prepare_backdrop
prepare_drift_correction
pupil_size
sample
send_command
set_backdrop
set_eye_used
start_recording
status_msg
stop_recording
wait_for_blink_end
wait_for_blink_start
wait_for_event
wait_for_fixation_end
wait_for_fixation_start
wait_for_saccade_end
wait_for_saccade_start
Arguments:
experiment → The experiment object.
resolution → A (width, height) tuple.
Keyword arguments:
data_file → The name of the EDF file. (default=u'default.edf')
fg_color → The foreground color for the calibration screen. (default=255,255,255)
bg_color → The background color for the calibration screen. (default=0,0,0)
saccade_velocity_threshold → The velocity threshold used for saccade detection. (default=35)
saccade_acceleration_threshold → The acceleration threshold used for saccade detection. (default=9500)
force_drift_correct → Indicates whether drift correction should be enabled. This is useful only for Eyelink 1000 models, for which drift correction is disabled by default. (default=False)
Returns:
True on connection success and False on connection failure.
Keyword arguments:
beep → Indicates whether or not the calibration target should beep when jumping. (default=True)
target_size → The size of the calibration target. (default=16)
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
True if connected, False otherwise.
Note: This function is simply a wrapper around `fix_triggered_drift_correction()` and `manual_drift_correction()`.
Keyword arguments:
pos → The coordinates (x,y tuple) for drift correction or None for the display center. (default=None)
fix_triggered → A boolean indicating whether drift correction should be fixation triggered, rather than spacebar triggered. (default=False)
Returns:
True on success, False on failure.
Exceptions:
Raises an exceptions.runtime_error on error.
Keyword arguments:
pos → The coordinate (x,y tuple) for drift correction or None for the display center. (default=None)
min_samples → The minimum nr of stable samples that should be acquired. (default=30)
max_dev → The maximum allowed deviation. (default=60)
reset_threshold → The maximum allowed deviation from one sample to the next (default=10)
Returns:
True on success, False on failure.
Exceptions:
Raises an exceptions.runtime_error on error or on confirming 'abort experiment'.
Returns:
The tracker time minus experiment time.
Arguments:
msg → The message to be logged.
Arguments:
var → The variable name.
val → The value.
Keyword arguments:
pos → The coordinate (x,y tuple) for drift correction dot or None for the display center. (default=None)
Returns:
True on success, False on failure.
Exceptions:
Raises an exceptions.runtime_error on error or on confirming 'abort experiment'.
Arguments:
canvas → An openexp.canvas.
Returns:
A (image, width, height) tuple, where image is a pygame.surfarray.array2d.
Arguments:
pos → The reference point.
Exceptions:
Raises an exceptions.runtime_error on error.
Returns:
A float corresponding to the pupil size (in arbitrary units). The value -1 indicates missing data.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A tuple (x, y) containing the coordinates of the sample. The value (-1, -1) indicates missing data.
Exceptions:
Raises an exceptions.runtime_error on failure.
Arguments:
cmd → The eyelink command to be executed.
WARNING: this function can take between 10-50 ms to complete, depending on the resolution of the image and the cpu power of your machine. Do not use during time critical phases of your experiment.
Arguments:
backdrop → An openexp.canvas or a tuple representation as returned by prepare_backdrop().
Returns:
The amount of time in ms the function took to complete.
Exceptions:
Raises an exceptions.runtime_error on failure.
Exceptions:
Raises an exceptions.runtime_error on failure.
Arguments:
msg → The status message.
Returns:
A timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Arguments:
event → An EyeLink event, such as pylink.STARTSACC.
Returns:
A tuple (timestamp, event). The event is in float_data format. The timestamp is in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A (timestamp, start_pos, end_pos) tuple with timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A (timestamp, start_pos) tuple with timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A (timestamp, start_pos, end_pos) tuple with timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
Returns:
A (time, start_pos) tuple with timestamp in experiment time.
Exceptions:
Raises an exceptions.runtime_error on failure.
