EyeLink Eyetracker functions

Overview

We have functions to interface Matlab with the EyeLink scanner. These functions allow you to calibrate the scanner and get current eye position information, etc. These are all referenced below. We have included 64-bit binaries based on a beta-version of Eyelink's frameworks.

To run the eyelink commands, you will need to have the Eyelink Frameworks installed. If they are not installed, you may see an error like this:

>> mglEyelinkOpen
Invalid MEX-file '/Users/justin/proj/mgl/mgllib/mglEyelink/mglPrivateEyelinkOpen.mexmaci64':
dlopen(/Users/justin/proj/mgl/mgllib/mglEyelink/mglPrivateEyelinkOpen.mexmaci64, 1): Library not loaded:
@executable_path/../Frameworks/edfapi.framework/Versions/A/edfapi
  Referenced from: /Users/justin/proj/mgl/mgllib/mglEyelink/mglPrivateEyelinkOpen.mexmaci64
  Reason: image not found

The Eyelink libaries can be downloaded from the Eyelink CD - or, if you are using 64-bit, follow instructions here to get the beta. The ones you will need are called eyelink_core.framework (used for interfacing with the eye tracker) and edfapi.framework (used for reading the edf files that the tracker makes). These frameworks will appear as directories in Library/Frameworks (either in the root directory or your home directory). You also need the SDL frameworks (SDL.framework, SDL_ttf.framework, SDL_mixer.framework, SDL_image.framework, SDL_gfx.framework). There is also an eyelink_core_graphics.framework, but this framework should not be necessary. Once you have successfully installed the Frameworks, you should also be able to compile the Eyelink code (this is only necessary to do if you are using 32-bit Matlab or some other platform for which the code does not work):

mglMake('Eyelink')

Follow the Eyelink instructions for setting up your Eyelink computer and connecting to it. But, essentially, you need to do at least the following:

  1. Connect the Eyelink computer to your stimulus computer with an Ethernet cross cable (should be provided by SR Research).
  2. Set your Network settings correctly. Usually you will have plugged the Eyelink computer into the second network adaptor. So you will then need to go to System Preferences/Network and set “Ethernet 2” to the following
    Configure IPv4: Manually
    IP Address: 100.1.1.2
    Subnet Mask: 255.255.255.0
    Router, DNS Server and Search Domains are irrelevant (I think)
  3. Boot up the Eyelink computer.
  4. Run the command mglEyelinkOpen in matlab on the stimulus computer. You should see the green bar in the top right hand corner of the Eyelink computer change to say: TCP/IP Link Open
  5. Run the command mglEyelinkClose and it should change back to: Link Closed

If the system does not find a connected Eyelink computer, you will likely see an error like this:

>> mglEyelinkOpen
displayApi: Socket BIND failed: -1 48 port 4000
displayAPI: /Users/sugy/dev/displayAPI/macdispapi/../common/w32_link.c 564 failed to create socket
Cannot initialize link: Check network and TCP/IP setup(mglPrivateEyelinkOpen) Connection type is 0
Connection failed: could not establish a link.

If you use the mgl task code, you do not need to call any of the following functions explicitly.

mglEyelinkEDFRead

purpose: Reads an Eyelink file into matlab
usage: mglEyelinkReadEDF(filename,<verbose>)

argumentvalue
filenameName of EDF file you want to read
verboseSet to 1 to display verbose information, defaults to 0

mglEyelinkOpen

purpose: Opens a TCP/IP link between matlab and the EyeLink eyetracker.
usage: mglEyelinkOpen(ip,conntype);

argument value
ip The IP address of the eyewink eye tracker, defaults to 100.1.1.1
conntype 0, open up a direct link, 1 initializes a dummy connection useful for debugging.
% open the link
% calls mglPrivateEyelinkOpen, default ip is '100.1.1.1', default conntype is 0
try
  mglEyelinkOpen('100.1.1.1', 0);
catch err
  mglEyelinkOpen('100.1.1.1', 1);
  disp(sprintf('(mglEyelinkOpen) Establishing a dummy connection with the EyeLink'));
end

mglEyelinkCMDPrintF

purpose: Sends a command to the eyetracker
usage: mglEyelinkCMDPrintF('an EyeLink command');

argument value
a string anything recognized by EyeLink (see the manual)
% set up some variables
mglEyelinkCMDPrintF('screen_pixel_coords = 0 0 %d %d', mglGetParam('screenWidth'), mglGetParam('screenHeight')); 
mglEyelinkCMDPrintF('calibration_type = HV9');
mglEyelinkCMDPrintF('file_event_filter = RIGHT,FIXATION,SACCADE,BLINK,MESSAGE,BUTTON'); 
mglEyelinkCMDPrintF('file_sample_data = RIGHT,GAZE,AREA,GAZERES,STATUS'); 
mglEyelinkCMDPrintF('sample_rate = 500');

mglEyelinkSetup

This function switches the Eyelink Software into the 'setup' state where you can adjust thresholds, change settings and run the calibration routine. You can use any of the keyboard commands that are available from the Eyelink software (on the Eyelink computer keyboard). This function returns when you exit the Eyelink setup state (via the ESC key), usually after you have successfully calibrated or validated. The keys you can use are listed below, for more information refer to the Eyelink Users Manual.

The basic keys are

Setup Screen
  • RETURN : display the eye image in the primary MGL context
  • LEFT/RIGHT ARROW : switch the selected eye image
  • A : Auto threshold the eye
  • C : Enter the calibration routine (ENTER to accept a calibration)
  • V : Enter the validation routine (ENTER to accept a validation)
  • UP/DOWN ARROW : adjust the pupil reflection threshold
  • +/- : adjust the corneal reflection threshold

All Keyboard Commands

Setup Screen
  • ESC : Go to the Offline screen or exit Camera Setup
  • ENTER : Toggles sending images over link
  • C : Go to the Calibration screen
  • V : Go to the Validate screen
  • D : Go to the Drift correction/check screen
  • O : Go to the Output screen
  • S : Go to Set Options page
  • Ctrl + Alt + Q : Exit the EyeLink Host application
  • Page Up and ⇑ : Increase pupil threshold/bias
  • Page Down : Decrease pupil threshold/bias
  • EyeLink 1000 User Manual version (9/13/2007) © 2005-2007 SR Research Ltd. 23 : and ⇓
  • + and - : Set corneal reflection threshold/bias
  • ⇐ and ⇒ : Select Eye, Global or zoomed view for link
  • A : Auto threshold selected imageTower MountDesktop Mount; Additionally, for the EyeLink Remote, realigns the search limit box on top of the current eye position
  • E : Cycle through eye(s) to track.
  • L : Select left eye for recording
  • R : Select Right eye for recording
  • B : Select both eyes for recording
  • P : Toggle Pupil only or Pupil-CR mode selection (may be locked)
  • Q : Toggle Ellipse and Centroid pupil center position algorithm
  • F : Select sampling rate of EyeLink recording
  • U : Toggle search limit box on or off
  • SHIFT and cursor keys (⇐, ⇒, ⇑, or ⇓) : If search limits are enabled, these keys can be used to move the position of the search limits.
  • ALT and cursor keys (⇐, ⇒, ⇑, or ⇓) : If search limits are enabled, these keys can be used to adjust the size and shape of the search limits.
  • M : Toggle Mouse-click Autothreshold on or off
  • X : Toggle crosshair display
  • T : Toggle threshold coloring display
  • I : Change illuminator power (hardware dependent)
  • K : Perform camera position autodetect (mirror mount); Toggle “lock tracked eye” button (Desktop Mount).
Video Overlay Only
  • W : Video overlay configuration.
Calibration Screen
  • ESC : Camera setup
  • A : Auto calibration set to the pacing selected in Set Options menu. (Auto trigger ON). EyeLink accepts current fixation if it is stable.
During Calibration
  • ENTER or Spacebar : Begins calibration sequence or accepts calibration value given. After first point, also selects manual calibration mode.
  • ESC : Terminates calibration sequence.
  • M : Manual calibration (Auto trigger turned off.)
  • A : Auto calibration set to the pacing selected in Set Options menu. (Auto trigger ON). EyeLink accepts current fixation if it is stable.
  • Backspace : Repeats previous calibration target.
After Calibration
  • ENTER : Accept calibration values
  • V : Validate calibration values
  • ESC : Discard calibration values
  • Backspace : Repeats last calibration target.
Validation Screen
  • ESC : Camera setup
  • A : Auto calibration set to the pacing selected in Set Options menu. (Auto trigger ON). EyeLink accepts current fixation if it is stable.
During Validation
  • ESC : (First Point) Exit to Camera Setup (Following Points) Restart Calibration.
  • ENTER or Spacebar : Begins calibration sequence or accepts calibration value given. After first point, also selects manual calibration mode.
  • M : Manual validation (Auto trigger turned off.)
  • A : Auto validation set to the pacing selected in Set Options menu. (Auto trigger ON). EyeLink accepts current fixation if it is stable.
  • Backspace : Repeats previous calibration target.
Validation Result
  • GOOD (green background): Errors are acceptable (worst point error < 1.5 deg, avg error < 1.0 deg)
  • POOR (red background): Errors are too high for useful eye tracking (worst point error > 2.0 deg, avg error >1.5 deg)
  • FAIR (gray background): Errors are moderate, calibration should be improved (any value between the above criteria)
After Validation
  • ENTER : Accept validation values
  • ESC : Discard validation values

mglEyelinkOpenEDF

purpose: Open up a new datafile to store the eye data
usage: mglEyelinkOpenEDF(filename)

mglEyelinkRecordingStart

purpose: Tell the eyetracker to start recording samples
usage: mglEyelinkRecordingStart(startvector)

argument value
1 0 0 0 edf-sample (record eye samples in the current eyelink .edf file)
0 1 0 0 edf-event (record events in the current eyelink .edf file)
0 0 1 0 link-sample (send eye position samples back to matlab)
0 0 0 1 link-event (send events back to matlab)

Pass in either a vector for recording state: e.g. [1 0 0 0] where the elements are [file-sample file-event link-sample link-event] or up to four string arguments that set the recording state

mglEyelinkRecordingStart('file-sample','file-event',
                         'link-sample','link-event');

mglEyelinkEDFPrintF

purpose: Insert a message into the recorded datastream
usage: mglEyelinkEDFPrintF(message)

argument value
meessage text string that you want to insert

mglEyelinkGetCurrentEyePos

purpose: Get the X and Y coordinate of the current eye position
usage: pos = mglEyelinkGetCurrentEyePos()

argument value
pos returns the eye position in the current device coordinates - e.g. visual angle if visual angle coordinates are set.

mglEyelinkClose

purpose: Close the link between matlab and the eyetracker
usage: mglEyelinkClose