====== EyeLink Eyetracker functions ======
===== Overview =====
We have functions to interface Matlab with the [[http://www.sr-research.com/EL_1000.html|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 [[EyeLink64bit|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:
  - Connect the Eyelink computer to your stimulus computer with an Ethernet **cross** cable (should be provided by SR Research).
  - 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<code>
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)
</code>
  - Boot up the Eyelink computer.
  - 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**
  - 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.
  
Note that the eyelink computer ethernet ip should be set to 100.1.1.1, while the display computer should be set to 100.1.1.2, in order to make a bidirectional connection between the two devices ([[https://www.sr-research.com/support/thread-281.html|eyelink support]]). 

If you use the [[:mgl:taskreferenceeyelink|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>)\\

^argument^value^
|filename|Name of EDF file you want to read|
|verbose|Set 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
<code matlab>
mglEyelinkRecordingStart('file-sample','file-event',
                         'link-sample','link-event');
</code>
===== 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**