Coming soon – the EyeLink 3. Combined head and eye tracking at up to 1000 Hz.

SR Support Forum   ›   Learning Resources   ›   Getting Started   ›   Getting Started with Experiment Programming   ›   Getting Started with Python and PyLink
Getting Started with Python and PyLink
Sam
Research Support Specialist
*******
Joined: Aug 2020
Posts: 864

#1
08-27-2020, 03:53 PM
Python is a high-level programming language popular in the scientific community. The EyeLink Developers Kit provides an application programming interface (API) that allows users to develop custom eye tracking applications. The Python wrapper of this API is called PyLink, and it is compatible with both Python 2.7 and 3.6-3.12. This guide assumes that users are working with the official Python distribution that is freely available from https://www.python.org.

Installation Instructions
  1. Configure your Display PC's network connection to communicate with the EyeLink Host PC.
  2. Install the latest version of the EyeLink Developers Kit for your operating system.
  3. Install and configure PyLink

    The EyeLink Developers Kit contains versions of Pylink that are specifiic for different versions of Python and system architectures. We have provided multiple different ways to install the PyLink library - please pick the option that you are most comfortable with:
    1. Install PyLink using the install_pylink.py script

      Running the install_pylink.py script will automatically install the appropriate PyLink library:

      Windows: Open a Command window by typing “cmd” from the Start menu; then execute the following commands (please replace -3.x with the target version, e.g., -3.6).

      Code:
      cd C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\
      py -3.x  install_pylink.py

      macOS: Run the following commands in the terminal (Please replace python3.x with the target version, e.g., python3.6).

      Code:
      cd /Applications/EyeLink/SampleExperiments/Python
      python3.x install_pylink.py

      Linux: Run the following commands in the terminal (Please replace python3.x with the target version, e.g., python3.6).

      Code:
      cd /usr/share/EyeLink/SampleExperiments/Python
      python3.x install_pylink.py
      Note: In some installation scenarios (e.g., to obtain administrator privilege on macOS and Linux), you may need to add sudo before the command e.g. sudo python3.x install_pylink.py.

    2. Manually install the PyLink library

      You can also manually install the PyLink by copying the PyLink library to the Python site-packages (Windows and macOS) or dist-package folder (Ubuntu / Linux). To find the specific path of the site-packages or dist-package folder, open a Python shell and type the following command:

      Code:
      import site
      site.getsitepackages()

      For example on macOS with python 3.8, the output will be:

      Code:
      ['/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages']

      Then simply copy the correct pylink folder to the site-package/dist-package folder. You can manually drag and drop and move the pylink folder into the correct location or in the terminal on macOS, you can use the cp command with the -R option (copy recursively, i.e. copy the foler and its contents) from the EyeLink Developers Kit location to the Python site-package location using the following syntax:

      Code:
      cp -R /Applications/Eyelink/SampleExperiments/Python/3.8/pylink /Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages

    3. Install the PyLink libray using pip

      We provide PyLink with pip from our PyPi server (https://pypi.sr-support.com/) via the sr-research-pylink meta-package. The EyeLink Developers Kit also includes Python wheel files in the wheels folder. Separate wheel files are provided for different versions of Python and architectures. You can also use pip to install these locally available wheel files.

      To install PyLink from the PyPi server or a local .whl file, please run the following code (if using a .whl file replace *.whl with the specific wheel file that matches the version of python and architecture you plan to use, for example, sr_research_pylink-2.0.42917.0-cp38-cp38-macosx_10_9_x86_64.macosx_11_0_x86_64 .whl).:

      Windows:
      Code:
      py -3.x -m pip install --index-url=https://pypi.sr-support.com sr-research-pylink

      or

      py -3.x -m pip install *.whl

      macOS / Ubuntu
      Code:
      python3.x -m pip install --index-url=https://pypi.sr-support.com sr-research-pylink

      or

      python3.x -m pip install *.whl

Testing your installation

To check that PyLink is properly installed enter the following code in your Python shell:

Code:
import pylink

If no error message appears, you are now ready to use the PyLink library and can check your installation by running one of the example templates described below.

Templates / Example Projects

The example scripts can be found in the following locations:
  • Windows:         C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\examples
  • macOS:             /Applications/Eyelink/SampleExperiments/Python/examples
  • Linux:                /usr/share/EyeLink/SampleExperiments/Python/examples
The examples are grouped into two types of scripts:
  1. Scripts that do not require any additional multimedia libraries to be installled (scripts in the linkEvent and linkSample folders):
    These two scripts showcase the frequently used commands for connecting to the EyeLink tracker, configuring tracker parameters, performing calibration / validation, starting / ending recordings, and messaging for event logging.

    Template Description
    linkEvent This script shows the frequently used commands for connecting to the tracker, configuring tracker parameters, starting/ending recording, and messaging for event logging. Most importantly, this script shows how to retrieve eye events (Fixation Start / End, Saccade Start / End, etc.) during data recording from the stimulus presentation PC.
    linkSample This script shows the frequently used commands for connecting to the tracker, configuring tracker parameters, starting / ending recording, and messaging for event logging. Most importantly, this script shows how to retrieve samples (time stamped gaze position, pupil size, etc.) in real-time during data recording.

  2. Scripts that require either PsychoPy or Pygame to be installed (scripts in the PsychoPy_examples and Pygame_examples folders):
    In a typical experimental task, dedicated libraries for graphics generation, keyboard response collection, etc can be used. Here we provide examples for PsychoPy and Pygame to illustrate eye tracking integration with a Python-based programming tool through the PyLink library.

    Note that for both the PsychoPy and Pygame examples, there is an accompanying library in the same folder as the example script, e.g., EyeLinkCoreGraphicsPsychoPy.py and CalibrationGraphicsPygame.py respectively. There are also three .wav files that this .py library depends on. This .py library and the .wav files are needed for tracker calibration. You do not need to change these files in any way, but please include them in your experimental scripts folder.

    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 (PsychoPy only) A simple video demo with animated calibration / drift-check targets. In each trial eye movements are recorded while a video stimulus is presented on the screen.
To run any example scripts use the commands below (which assume that the picture folder is on the Desktop and you are running Python 3.6).

Windows: Open the Command Prompt and enter the command below

Code:
py -3.6 Desktop\picture\picture.py


macOS / Ubuntu: Open the terminal and enter the command below

Code:
python3.6 ~/Desktop/picture/picture.py

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. The 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: You can also find full documentation of the protocol in the Data Viewer User Manual (Help -> Contents) under the section "Protocol for EyeLink Data to Viewer Integration".

Documentation:

PyLink is fully featured and all of its functions are documented in the PyLink API User Guide. This guide is packaged with the EyeLink Developers Kit:
  • Windows:         C:/Program Files(x86)/SR Research/EyeLink/SampleExperiments/Python/pylink api userguide.pdf or pylink.chm
  • macOS:             /Applications/Eyelink/SampleExperiments/Python/pylink api userguide.pdf
  • Linux:                /usr/share/EyeLink/SampleExperiments/Python/pylink api userguide.pdf
Given that PyLink is a wrapper for our C API contained within the EyeLink Developers Kit, you may also find the EyeLink Programmer's Guide helpful in expanding your knowledge of given functions in the API. This document contains the complete documentation of our C API functions, data structure, and implementation. The syntax functions listed in the manual will likely differ in how they are wrapped within the PyLink library, but much of the functionality should be analogous.