Getting Started with Python and PyLink

[Sam]

You can integrate EyeLink eye trackers with Python using PyLink, our API wrapper for creating custom eye-tracking applications. PyLink is included with the EyeLink Developers Kit. This guide assumes you are using the official Python distribution, which is available for free fromhttps://www.python.org.

---

Installation Instructions
Prerequisites
Before installing PyLink, you must complete the following two steps:

• Configure Network: Set up your Display PC's network connection to communicate with the EyeLink Host PC.
  
• Install Developers Kit: Install the latest version of the EyeLink Developers Kit for your operating system.
  

Installation Methods
Once the prerequisites are met, choose one of the following methods to install the PyLink library.

• Install with pip
  You can install PyLink using pip from either our official PyPi server or a local wheel (.whl) file included with the Developers Kit.
  • Windows:
    Code:

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

    python3.x -m pip install --index-url=https://pypi.sr-support.com sr-research-pylink
  
  
• Install from a local wheel file:
  The wheel files are located in the wheels folder of the Developers Kit installation.
  • Windows:
    Code:

    py -3.x -m pip install <your_wheel_file.whl>
  • macOS / Linux:
    Code:

    python3.x -m pip install <your_wheel_file.whl>
  Replace <your_wheel_file.whl> with the specific .whl file that matches your Python version and system architecture. The wheels come pre-packaged with the EyeLink Developers Kit or can be downloaded separately:
  • Windows: C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\
    
  • macOS: /Applications/Eyelink/SampleExperiments/Python/
    
  • Linux: /usr/share/EyeLink/SampleExperiments/Python/
    
• Automated Install Script
  Running the install_pylink.py script will automatically find and install the correct PyLink library for your system.
  • Windows:
    • Open Command Prompt by typing cmd in the Start Menu.
      
    • Execute the following commands. Replace -3.x with your Python version (e.g., -3.9).
      
      Code:

      cd "C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\"
py -3.x install_pylink.py
  • macOS:
    • Open the Terminal.
      
    • Execute the following commands. Replace python3.x with your Python version (e.g., python3.9).
      
      Code:

      cd /Applications/EyeLink/SampleExperiments/Python
python3.x install_pylink.py
  • Linux:
    • Open the Terminal.
      
    • Execute the following commands. Replace python3.x with your Python version (e.g., python3.9).
      
      Code:

      cd /usr/share/EyeLink/SampleExperiments/Python
python3.x install_pylink.py
  Note for macOS/Linux: You may need administrator privileges. If the command fails, try adding sudo before it (e.g., sudo python3.9 install_pylink.py).
  
  
• Manual Installation
  You can manually copy the pylink library into your Python installation's site-packages folder.
  
  Find your site-packages directory: Open a Python shell and run the following commands to find the path:
  
  Code:

  import site
site.getsitepackages()
  
  Example output for Python 3.8 on macOS:
  ['/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages']
  
  Copy the pylink folder: Locate the pylink folder inside the EyeLink Developers Kit directory that matches your Python version and copy it into the site-packages path you found above. You can do this by dragging and dropping the folder or by using a terminal command.
  
  Example cp command for macOS:
  
  Code:

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

---

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 Python examples are grouped into two types: basic scripts that show core API functions, and multimedia scripts that demonstrate integration with graphics libraries:

1. Basic Examples (No Dependencies)
   These scripts, located in the linkEvent and linkSample folders, demonstrate essential EyeLink API functions without requiring any extra libraries like PsychoPy or Pygame. They show you how to connect to the tracker, perform calibration, start/stop recording, and send messages.
   
   

   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. Multimedia Examples (PsychoPy / Pygame):
   These examples, found in the PsychoPy_examples and Pygame_examples folders, show how to integrate EyeLink into a typical experiment using common graphics libraries.
   
   Important Dependencies
   For these examples to work, you must include their accompanying library file (e.g., EyeLinkCoreGraphicsPsychoPy.py) and three .wav files in the same folder as your main experiment script. These files are required for calibration graphics and sounds.
   
   

   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.

   
   
   
3. How to Run an Example:
   To run any example, navigate to its directory in your terminal or command prompt and execute the script with Python.
   
   For example, to run the picture script located on your Desktop using 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
Beyond just marking event times, it's highly recommended to send specially formatted messages to your EyeLink Data File (.edf) to improve integration with Data Viewer. These messages allow Data Viewer to automatically parse your experiment's structure, including trial start/end times, variables, and stimulus information.

All the multimedia examples demonstrate how to format and send these messages. For a complete guide on the protocol, see the resources below.

• Webinar: EyeLink Data Viewer Integration Messaging Protocol.
  
• Manual:Data Viewer User Manual, in the section "Protocol for EyeLink Data to Viewer Integration" (accessible via Help > Contents).
  

---

Documentation:

• PyLink API User Guide (Primary Documentation)
  This is the complete guide for all PyLink functions. It is included with the EyeLink Developers Kit in the following locations:
  • Windows: C:\Program Files (x86)\SR Research\EyeLink\SampleExperiments\Python\
    (Available as pylink api userguide.pdf and pylink.chm)
    
  • macOS: /Applications/Eyelink/SampleExperiments/Python/pylink api userguide.pdf
    
  • Linux: /usr/share/EyeLink/SampleExperiments/Python/pylink api userguide.pdf
    
• EyeLink Programmer's Guide (Supplementary)
  PyLink is a wrapper for our core C API. This guide is the complete documentation for that underlying C API, detailing all its functions, data structures, and implementation. It is an excellent resource for understanding the core logic of the EyeLink system.
  
  Note on Syntax: While the function names and syntax in this C API guide will differ from the Python implementation in PyLink, the core functionality and concepts are analogous.