06-25-2021, 05:46 AM
PsychoPy is a Python based stimulus presentation solution. The PyLink library for Python, which is a fully-featured wrapper for the EyeLink C API, provides full support for EyeLink eye trackers in PsychoPy. In order to use PyLink with PsychoPy, the EyeLink Developers Kit must be installed on the same computer as PsychoPy. Once the EyeLink Developers Kit is installed you should have full access to all of the available API functions.
Programming in PsychoPy is accomplished either via a drag and drop, GUI-based Builder environment and/or via a Coder environment that allows you to view/edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of EyeLink GUI components that provide EyeLink integration functionality. These GUI components will appear in the Eyetracking section of the Components panel after it has been installed.
The second method within the Builder is to communicate with the EyeLink system via Code components in the Builder, using calls to the Pylink module at various points in the experiment. We provide an example set for each of these two methods -- we provide an example set that shows how to use the EyeLink Plugin for PsychoPy and another example set that show how to perform EyeLink integration in the Builder using code components.
Within the Coder, EyeLink integration involves calls to the PyLink module directly. We also provide an example set showing how to perform EyeLink integration from straight-Coder built experiments.
See below for pointers to the example sets described above.
One of the advantages of PsychoPy, though, is that you can "compile" a Builder experiment to the Coder. This essentially means you can use several different ways of integration with the EyeLink system in isolation or in combination. You can use EyeLink Plugin components to do fully featured EyeLink integration. Or, if you prefer, you can also/additionally make Pylink callls from the Builder's Code components or from the Coder directly.
Installation instructions
Templates / Example Experiments
An example set for the EyeLink Plugin for PsychoPy can be found at the link below:
EyeLinkPluginForPsychoPy_Examples.zip (Size: 3.46 MB / Downloads: 89)
There is a detailed, step-by-step walkthrough for using the EyeLink Plugin for PsychoPy in Chapter 3 of the
The EyeLink Developers Kit includes an example set for the Builder (using Code Component method described above) and an example set for the Coder. These example sets can be found in the following locations after the EyeLink Developers Kit has been installed.
PsychoPy_Builder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.95 MB / Downloads: 27)
PsychoPy_Builder_Examples_For_Versions_2023.2.x.zip (Size: 3.77 MB / Downloads: 21)
PsychoPy_Builder_Examples_For_Versions_2023.1.3_And_Earlier.zip (Size: 3.88 MB / Downloads: 128)
If you are using Coder, the user dialog changes introduced in 2024.1.0 required our examples to be edited (e.g., to handled the EDF file dialog). The examples provided below include that EDF dialog fix:
PsychoPy_Coder_Examples_For_Versions_2024.1.0_And_Later.zip (Size: 3.14 MB / Downloads: 35)
To test your installation please run the picture.py coder example script described below. Open the script in PsychoPy's coder window, and click the run button.
There is a detailed, step-by-step walkthrough for Coder integration following the picture example in Section 5 of the Getting Started with Python and Pylink guide (see below for the location of the PDF).
The following table lists all the example scripts that is provided with the EyeLink Developers Kit:
EyeLinkCoreGraphicsPsychoPy.py
Each of the Builder (Code Component method) and Coder example scripts contains an additional script named EyeLinkCoreGraphicsPsychoPy.py. It contains a set of callback functions for tracker calibration an drift-correction etc. These functions have been implemented with native PsychoPy functions, and they are called by the EyeLink API to draw the calibration targets at appropriate locations. When developing your own tasks in PsychoPy it is important that you include this library with your experimental script, as per the example scripts. If you are using the EyeLink Plugin for PsychoPy then you don't have to worry about this -- the appropriate EyeLinkCoreGraphicsPsychoPy.py file will be installed along with the plugin.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your experiment, in addition to sending messages to the EyeLink data file (i.e., EDF file) that log the timing of events within your task, it's typically a good idea to send special messages that allow integration with Data Viewer. If you use the EyeLink Plugin for PsychoPy then it will handle this Data Viewer integration for the most part automatically (please see the EyeLink Plugin for PsychoPy User Manual for detailed information on how to use it). The Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to send special messages to the EDF to convey important information to Data Viewer, like trial starting/ending times, trial variable values, trial stimulus information, and more. You can find a webinar at the following link that covers the formatting of these messages in detail:
Documentation
You can learn about how to install and use the EyeLink Plugin for PsychoPy in its User Manual:
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 227)
This video tutorial provides an overview of the basics of integrating EyeLink systems via PsychoPy Coder, and a detailed walkthrough of the picture.py template
EyeLink / PsychoPy Integration Video Tutorial
PsychoPy uses the PyLink wrapper of the EyeLink Developers Kit: PyLink is fully featured and all of its functions are documented in the PyLink API User Guide which is packaged with the EyeLink Developers Kit. A very useful Getting Started with Python and PyLink PDF file can also be found in the same locations:
Programming in PsychoPy is accomplished either via a drag and drop, GUI-based Builder environment and/or via a Coder environment that allows you to view/edit the full Python code of your experiments.
Within the Builder, there are two options for interacting with EyeLink systems. First, you can use the EyeLink Plugin for PsychoPy, which provides a set of EyeLink GUI components that provide EyeLink integration functionality. These GUI components will appear in the Eyetracking section of the Components panel after it has been installed.
The second method within the Builder is to communicate with the EyeLink system via Code components in the Builder, using calls to the Pylink module at various points in the experiment. We provide an example set for each of these two methods -- we provide an example set that shows how to use the EyeLink Plugin for PsychoPy and another example set that show how to perform EyeLink integration in the Builder using code components.
Within the Coder, EyeLink integration involves calls to the PyLink module directly. We also provide an example set showing how to perform EyeLink integration from straight-Coder built experiments.
See below for pointers to the example sets described above.
One of the advantages of PsychoPy, though, is that you can "compile" a Builder experiment to the Coder. This essentially means you can use several different ways of integration with the EyeLink system in isolation or in combination. You can use EyeLink Plugin components to do fully featured EyeLink integration. Or, if you prefer, you can also/additionally make Pylink callls from the Builder's Code components or from the Coder directly.
Installation instructions
- Configure your Display PC's network connection to communicate with the EyeLink Host PC.
- Download and install the latest version of the EyeLink Developers Kit
- Download and install the latest version of PsychoPy
- Replace the PyLink library included in PsychoPy with the latest version. The PyLink library included in PsychoPy may be slightly older than the ones included in the EyeLink Developers Kit. To be sure that you have the most up to date version, please replace the pylink folder that comes with PsychoPy with the appropriate version from the EyeLink Developers Kit.
- Windows (64-bit): Copy the pylink folder from C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64\3.8\ and paste it to:
C:\Program Files\PsychoPy\Lib\site-packages\
- MacOS: Copy the pylink folder from /Applications/EyeLink/SampleExperiments/Python/3.8/ and paste it to:
/Applications/PsychoPy.app/Contents/Resources/lib/python3.8/
or
/Applications/PsychoPy.app/Contents/Resources/lib/python3.10/
- Ubuntu: To move the correct pylink folder to PsychoPy enter the following code in terminal:
sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.8/pylink /usr/lib/python3/dist-packages/or
sudo cp -r /usr/share/EyeLink/SampleExperiments/Python/64/3.10/pylink /usr/lib/python3/dist-packages/(depending on the version of Python your PsychoPy is using)
To check if PyLink is properly installed in PsychoPy, enter the following code in the PsychoPy Coder shell. If no error message comes up, you are all set.import pylink
- Windows (64-bit): Copy the pylink folder from C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\64\3.8\ and paste it to:
- If you will be using the EyeLink Plugin for PsychoPy, then additionally follow the steps described in section 1.3 of the EyeLink Plugin for PsychoPy User Manual, which you can get at the link below:
EyeLinkPluginForPsychoPyUserManual_1.0.pdf (Size: 1.71 MB / Downloads: 227)
Templates / Example Experiments
An example set for the EyeLink Plugin for PsychoPy can be found at the link below:

There is a detailed, step-by-step walkthrough for using the EyeLink Plugin for PsychoPy in Chapter 3 of the
The EyeLink Developers Kit includes an example set for the Builder (using Code Component method described above) and an example set for the Coder. These example sets can be found in the following locations after the EyeLink Developers Kit has been installed.
- Windows: C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\examples\Psychopy_examples
- macOS: /Applications/Eyelink/SampleExperiments/Python/examples/Psychopy_examples
- Linux: /usr/share/EyeLink/SampleExperiments/Python/examples/Psychopy_examples



If you are using Coder, the user dialog changes introduced in 2024.1.0 required our examples to be edited (e.g., to handled the EDF file dialog). The examples provided below include that EDF dialog fix:

To test your installation please run the picture.py coder example script described below. Open the script in PsychoPy's coder window, and click the run button.
There is a detailed, step-by-step walkthrough for Coder integration following the picture example in Section 5 of the Getting Started with Python and Pylink guide (see below for the location of the PDF).
The following table lists all the example scripts that is provided with the EyeLink Developers Kit:
Template | Description |
---|---|
picture | This is a basic example, which shows how to connect to and disconnect from the tracker, how to open and close data files, how to start / stop recording, and the standard messages for integration with the Data Viewer software. We show four pictures one-by-one on each trial, and a trial terminates upon a keypress response or until 3 secs have elapsed. |
pursuit | This example script shows how to record the target position in a smooth pursuit task. This script also shows how to record dynamic interest area and target position information to the EDF data file so Data Viewer can recreate the interest area and playback the target movement. |
saccade | This example script shows how to retrieve eye events (saccades) during testing. A visual target appears on the left side, or right side of the screen and the participant is required to quickly shift gaze to look at the target (pro-saccade) or a mirror location on the opposite side of the central fixation (anti-saccade). |
fixationWindow_fastSamples | This is a basic example, which shows how to implement a gaze-based trigger. First a fixation cross is shown at the center of the screen. The trial moves on only when gaze has been directed to the fixation cross. |
GC_window | This script shows how to manipulate visual stimuli based on real-time gaze data. A mask is shown at the current gaze position in the "mask" condition; in the "window" condition, the image is masked, and a window at the current gaze position will reveal the image hidden behind the mask. |
MRI_demo | This is a basic example illustrating how to do continuous eye tracker recording through a block of trials (e.g., in an MRI setup), and how to synchronize the presentation of trials with a sync signal from the MRI. With a long recording, we start and stop recording at the beginning and end of a testing session (run), rather than at the beginning and end of each experimental trial. We still send the TRIALID and TRIAL_RESULT messages to the tracker, and Data Viewer will still be able to segment the long recording into small segments (trials). |
video | A simple video demo. In each trial eye movements are recorded while a video stimulus is presented on the screen. Integration messages allow the video to play back in Data Viewer |
EyeLinkCoreGraphicsPsychoPy.py
Each of the Builder (Code Component method) and Coder example scripts contains an additional script named EyeLinkCoreGraphicsPsychoPy.py. It contains a set of callback functions for tracker calibration an drift-correction etc. These functions have been implemented with native PsychoPy functions, and they are called by the EyeLink API to draw the calibration targets at appropriate locations. When developing your own tasks in PsychoPy it is important that you include this library with your experimental script, as per the example scripts. If you are using the EyeLink Plugin for PsychoPy then you don't have to worry about this -- the appropriate EyeLinkCoreGraphicsPsychoPy.py file will be installed along with the plugin.
EyeLink Data Viewer Messaging Commands and Syntax
Throughout the course of your experiment, in addition to sending messages to the EyeLink data file (i.e., EDF file) that log the timing of events within your task, it's typically a good idea to send special messages that allow integration with Data Viewer. If you use the EyeLink Plugin for PsychoPy then it will handle this Data Viewer integration for the most part automatically (please see the EyeLink Plugin for PsychoPy User Manual for detailed information on how to use it). The Builder (Code Component method) and Coder examples included in the EyeLink Developers Kit illustrate how to send special messages to the EDF to convey important information to Data Viewer, like trial starting/ending times, trial variable values, trial stimulus information, and more. You can find a webinar at the following link that covers the formatting of these messages in detail:
- EyeLink Data Viewer Integration Messaging Protocol
Documentation
You can learn about how to install and use the EyeLink Plugin for PsychoPy in its User Manual:

This video tutorial provides an overview of the basics of integrating EyeLink systems via PsychoPy Coder, and a detailed walkthrough of the picture.py template
EyeLink / PsychoPy Integration Video Tutorial
PsychoPy uses the PyLink wrapper of the EyeLink Developers Kit: PyLink is fully featured and all of its functions are documented in the PyLink API User Guide which is packaged with the EyeLink Developers Kit. A very useful Getting Started with Python and PyLink PDF file can also be found in the same locations:
- Windows: C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/
- Mac: /Applications/Eyelink/SampleExperiments/Python/
- Linux: /usr/share/EyeLink/SampleExperiments/Python/