Getting Started with Python and PyLink

[Sam]

Getting Started with Python, PyLink, and Pygame

This guide covers the core principles for integrating SR Research EyeLink eye trackers with Python, both with Pygame and without a dedicated media module. You can build experimental tasks using a multimedia library like Pygame, or run pure Python scripts if your task does not require visual or auditory stimuli.

The PyLink (sr-research-pylink) library and pygame-eyelink-coregraphics dependencies are available as standalone PyPI packages.

To read the comprehensive documentation for PyLink, see the PyLink API User Guide. It is included with the EyeLink Developers Kit installation 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
  

If you are using Python-based experiment builders like PsychoPy or OpenSesame, please note that while they also rely on PyLink, they utilize their own specific coregraphics implementations. You can find the dedicated documentation for these platforms here:

• Getting Started with PsychoPy / EyeLink Integration
  
• Getting Started with OpenSesame
  

---

1. Setup & Installation

Before running the EyeLink examples, set up your Display PC's network connection to communicate with the EyeLink Host PC. To set up your connection refer to: How do I configure my network settings to connect to the EyeLink Host PC?.

To install the necessary dependencies for the Pygame examples, open a terminal or command prompt and run:

Code:

pip install pygame sr-research-pylink pygame-eyelink-coregraphics

Alternatively, if you are working from a EyeLink Developers Kit provided pygame_examples directory, run:

Code:

pip install -r requirements.txt

Important: For offline installation steps see section 3.1 Offline Installation.

---

2. Example Scripts Overview

You can find the following examples included within the EyeLink Developer's Kit installation, or you can download them directly here:

  Python_Pygame_Examples.zip (Size: 1.66 MB / Downloads: 1)

A. Scripts Without a Multimedia Library
Two example Python scripts do not require additional Python multimedia libraries (like Pygame). These are useful examples for backend data retrieval or non-visual tasks. These tasks only require PyLink.

Code:

pip install sr-research-pylink

Template	Description
linkEvent	This script demonstrates 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 demonstrates 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.

B. Example Scripts Descriptions Using Pygame

The following templates demonstrate standard integration methods for scripts using Pygame:

Template	Description
picture	This example 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 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 play back the target movement.
saccade	This example 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 example 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 example shows how to implement 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).

---

3. Offline Installation and Support

3.1 Offline Installation
If your Display PC is not connected to the internet (which is common for dedicated experimental setups), you can still install the required dependencies using an offline method.

Method A: Downloading packages via pip (Recommended for the most recent versions)
Important: The sr-research-pylink package is Python-version specific. If the internet-connected computer you are using to download the packages does not have the exact same version of Python and operating system as your offline Display PC, you must explicitly tell pip which versions to target.

• Step 1: Download the packages on an internet-connected computer
  Standard Download (If both PCs have the exact same Python version and OS):
  
  Code:

  pip download pygame sr-research-pylink pygame-eyelink-coregraphics -d ./eyelink_packages
  
  Targeted Download (If the PCs have different Python versions or OS):
  You can force pip to download the specific pre-compiled .whl files (wheels) for your target Display PC using the --only-binary=:all: flag. Example for 64-bit Windows and Python 3.10:
  
  Code:

  pip download --only-binary=:all: --python-version 3.10 --platform win_amd64 --abi cp310 pygame sr-research-pylink pygame-eyelink-coregraphics -d ./eyelink_packages
  
  
• Step 2: Transfer the files
  Move the eyelink_packages folder to your offline Display PC using a USB drive.
  
  
• Step 3: Install the packages on the Display PC
  Navigate to the location where you saved the folder, and run:
  
  Code:

  pip install --no-index --find-links=./eyelink_packages pygame sr-research-pylink pygame-eyelink-coregraphics

Method B: Using the EyeLink Developers Kit local files (Alternative)
The EyeLink Developers Kit comes with offline wheel (.whl) file installations specifically for sr-research-pylink. While this might not give you the absolute most recent version of py, if you have installed the Developers Kit, the. whl files are already on your machine. You can find these installers locally in the SampleExperiments/Python/Offline_Install/ directory.

To install via this method, simply locate the file with the cp** tag that matches your Python version (for example, cp310 corresponds to Python 3.10) and install it directly via pip:

Code:

pip install path/to/the/specific_pylink_wheel.whl

Note: This method only provides pylink. You will still need to acquire offline installers for other dependencies like pygame if they are not already installed on your Display PC.

3.2 Technical Support
If you encounter any issues running the provided example scripts, or if you need assistance integrating EyeLink tracking into your own Python experiments, please do not hesitate to reach out to our support team.

You can contact us directly at support@sr-research.com.

To help us resolve your issue as quickly as possible, please include the following information in your email:

• Your EyeLink model and Host PC software version.
  
• The Operating System of your Display PC (e.g., Windows 11, macOS 26, Ubuntu 22.04).
  
• The version of Python you are using.
  
• A brief description of the issue, including any specific error messages or the name of the example script you are trying to run.
  

---

Further Reading: For documentation on the underlying C API that PyLink wraps, see the EyeLink Programmer's Guide.