Experiment example (PsychoPy): EyeLink eye-tracking starter demo
Author: Hadi Zaatiti, hadi.zaatiti@nyu.edu
Description
A single PsychoPy script to get started with the EyeLink eye tracker on the MEG stimulus computer. It calibrates the tracker, shows where the participant is looking in real time, and measures how accurate the calibration is, so a new user can check the whole eye-tracking chain before writing their own experiment.
It is built from SR Research’s official PsychoPy Coder examples (picture.py and GC_window.py,
psychopy-eyelink 2.2.1.1), which are kept in the repository next to it, and uses the same
calibration settings as the lab’s MATLAB/Psychtoolbox MGS eye-tracking task.
The script runs in three steps:
Camera setup and calibration. The standard EyeLink setup screen opens on the participant screen. From the stimulus computer keyboard:
ENTERshows or hides the camera image,Ccalibrates,Vvalidates,ESCorOleaves the setup screen.Live gaze. A blue dot follows the eye and an orange line shows the path it took, either as a 1.5 s fading trail or as the full path since it was last cleared. Nine reference circles mark the calibration points: look at each one and check the dot lands on it.
Accuracy check. Nine dots appear one at a time on the calibration points. For each dot the script takes the median gaze position and reports the error in degrees of visual angle, then shows a summary screen (green < 0.5°, yellow < 1°, red otherwise) with an overall GOOD / FAIR / POOR verdict. The experimenter can recalibrate and repeat from that screen.
The script also has a dummy mode in which the mouse plays the role of the eye, so it can be tried on any computer without the tracker. If the tracker cannot be reached, the script offers to continue in dummy mode.
Keys
Screen |
Key |
Action |
|---|---|---|
Camera setup |
|
Show / hide the camera image |
|
Calibrate / validate |
|
|
Leave the setup screen |
|
Live gaze |
|
Switch between fading trail and full path |
|
Clear the path |
|
|
Recalibrate |
|
|
Go to the accuracy check |
|
Accuracy summary |
|
Recalibrate and repeat the check |
|
Finish |
|
Anywhere |
|
Stop the demo (the data is still saved) |
Calibration settings
The calibration follows the lab’s MATLAB MGS task (mgs_meg_main...m):
HV9calibration, with the calibration and validation points confined to the central 50% of the screen (calibration_area_proportion = 0.5 0.5) instead of the EyeLink default of about 88% × 83%.Monocular tracking of the right eye (
binocular_enabled = NO,active_eye = RIGHT), set before calibration, with EDF and link data filtered to the right eye.Saccade parser thresholds of 35 °/s (velocity) and 9500 °/s² (acceleration).
Mid-grey calibration target (200/255) on a dark-grey background (100/255), 1% of the screen width.
Screen geometry used for the degree conversion: 65 cm wide screen, eyes 56.5 cm from the screen centre (the MEG-room measurements).
All of these are set at the top of the script:
# =============================================================================
TRACKER_IP = "100.1.1.1" # default EyeLink Host PC address
SCREEN_INDEX = 1 # default screen for the participant display. The lab's other
# scripts use screen=1 for the stimulus/projector screen.
# The start dialog lists the detected screens so you can change it.
FULL_SCREEN = True # set False while debugging
WINDOW_SIZE = (1280, 720) # only used when FULL_SCREEN is False
# Physical display geometry, used to convert pixels to degrees in the accuracy
# check. Values are the MEG-room measurements from the lab's MATLAB MGS task
# (mgs_meg_main...m): 65 x 36.5 cm screen, eyes 56.5 cm from the screen centre.
SCREEN_WIDTH_CM = 65.0 # visible width of the image on the screen (cm)
VIEW_DISTANCE_CM = 56.5 # participant's eyes to screen centre (cm)
# Colours on a 0-255 scale, same as the MATLAB task
BACKGROUND_COLOR_255 = (100, 100, 100) # dark grey background
CAL_TARGET_COLOR_255 = (200, 200, 200) # mid-grey calibration target
CAL_TARGET_SIZE_PCT = 1.0 # target diameter, % of screen width
# Calibration: same settings as the MATLAB MGS task
CALIBRATION_TYPE = "HV9" # 9 points (MATLAB task). HV5 quicker, HV13 more thorough
CALIBRATION_AREA = (0.5, 0.5) # calibration/validation points span the central
# 50% of the screen width/height (EyeLink default is
# about 0.88 x 0.83). None = tracker default.
TRACKED_EYE = "RIGHT" # monocular right eye, like the MATLAB task.
# "LEFT", "RIGHT", or None to keep the Host PC setting.
SACCADE_VELOCITY_THRESHOLD = 35 # deg/s (conservative parser, as in MATLAB)
SACCADE_ACCELERATION_THRESHOLD = 9500 # deg/s^2
SAMPLE_RATE = None # e.g. 1000. None = keep the Host PC setting.
TRAIL_SECONDS = 1.5 # length of the fading trail in live-gaze mode
MAX_PATH_POINTS = 3000 # cap for "full path" mode
# The live-gaze reference circles and the accuracy-check dots sit on the same
# 3x3 grid as the calibration points (set by CALIBRATION_AREA).
ACC_SETTLE_S = 0.8 # ignore gaze for this long after a target appears
ACC_COLLECT_S = 0.8 # then average gaze over this window
GOOD_DEG = 0.5 # SR Research rule of thumb: mean < 0.5 deg is good
OK_DEG = 1.0
# =============================================================================
Running the demo
Install the dependencies, either PsychoPy Standalone with the EyeLink plugin (Tools > Plugins / packages manager), or a conda environment created from the
environment.ymlnext to the script (conda env create -f environment.yml). It installspsychopy,psychopy-eyelink,psychopy-eyelink-coregraphicsandsr-research-pylink.Turn on the EyeLink Host PC and make sure it is showing the EyeLink software. The stimulus computer’s tracker network port should be
100.1.1.2/255.255.255.0; the Host PC is100.1.1.1.Run
eyelink_gaze_demo.py(PsychoPy Coder or VS Code with the PsychoPy environment).In the start dialog, enter an EDF file name (8 characters max, letters / numbers /
_), leave Dummy mode unticked, and choose the participant screen. The dialog lists every screen with its index, resolution and position; the default is screen 1, as in the lab’s other PsychoPy scripts.
Note
The EyeLink setup screen reads keys through the PsychoPy window. When the window opens
full screen on the second (participant) screen it may not have keyboard focus, and ENTER /
C then go to whatever window does (for example the VS Code terminal). The script gives the
window focus when it opens, and the instruction screen before the setup screen reads SPACE
the same way: if SPACE does nothing there, click once on the participant screen.
Output
Each run creates results/<EDFNAME>_<YYYY_MM_DD_HH_MM>/ next to the script, containing:
<id>.EDF: the full-rate EyeLink recording, copied from the Host PC when the demo exits. Open it in Data Viewer, or convert it withedf2ascand load it in MNE withmne.io.read_raw_eyelink("file.asc").<id>_gaze_samples.csv: gaze during the live-gaze step, one row per screen frame (a convenient lower-rate copy; use the EDF for analysis).<id>_accuracy_check.csv: target position, measured gaze and error for every accuracy-check dot.
The EDF contains messages that can be used as event markers, such as LIVE_GAZE_START /
LIVE_GAZE_END, TARGET_ON <n> <x> <y>, TARGET_OFF <n> and
ACCURACY_RESULT mean <m> max <m> deg.
The results/ folder is git-ignored so participant eye-tracking data does not end up in the
repository.
Using it in your own experiment
All the tracker code is in the EyeLinkSession class of the script (connect,
attach_window, calibrate, start_recording, get_gaze, message, close).
Copy it into your experiment, send a message() at each stimulus onset alongside the MEG trigger,
and call close() at the end to copy the EDF to the stimulus computer.