Page tree
Skip to end of metadata
Go to start of metadata

Using the eye tracker

NOTE: Always attach EEG electrodes before putting the eye tracker on the participant 

Step 1: Position the Tracker

  • Plug the tracker in to any available USB port
  • Attach the tracker’s wire to the participant by attaching the clip to their clothing - the clip should not be attached any lower than the top of the breast or it will pull the headset when recording (if a participant is wearing a low cut camisole for example, attach the clip to the shoulder strap)
  • Stretch tracker out and place on the participant’s head (it is made of a very durable material and will stretch a long way before it breaks), then let the wings close back against the head
  • Nose pieces should be snug against the top arch of the nose
  • Participant should be able to see most of the arm out of the corner of their eye
  • Wings should be just above the ear or resting on it (like glasses)

Step 2: Verify the Tracker is Recording Accurately

  • Open Pupil Capture on the computer
  • Navigate to the eye0 window (there is no eye1 since we only have the one camera version - you can close the eye1 window if it opens) - if the eye0 window is not showing, go to General Settings and select "detect eye0"
  • Drag a corner of the eye0 window to open it so you can see the eye video
  • By default, the tracker records the eye upside down - this is not an issue and it can be flipped later when viewing the recording
  • Make sure the eye is fully in the center of the screen and you can see most of it; you should not be able to see much nose and the eyebrow should not be visible
  • You should see a large green circle that doesn't move (this indicates the field where the tracker is most confident of pupil detection), and the eye should have a red ring around the pupil and a red dot at the center
  • If the dot and ring are pale or not visible, adjust the camera angle using the ball joint and the extension bar until they appear in strong red (don't worry if you extend the arm too far and it comes off; it slides right back on)
  • Have the participant move their head around slowly and move their eye around their field of vision to make sure the camera can track the eye when it moves

Step 3: Making an Eye Recording

  • Open the Recorder submenu and make sure the program is saving the file in the location you want by checking the path ("Path to Recordings")
  • To point to the program to a different folder, enter the correct file path in the Path field (you can find the file path by navigating to the file you want in File Explorer and then right clicking and choosing Properties); to copy the new path into Pupil Capture, highlight the path in Properties, click Ctrl C, then select the Path field and click Ctrl V
  • Begin a recording either by clicking the R button on the worldview screen or clicking the R key on the keyboard
  • When you are finished, click the R button or key and the file will save in the folder you asked it to

*Note: If you made the pupil recording with PupilLabs version 1.15 or later, you will need to change the Marker Detection Mode in the Pupil Player settings to "Legacy square markers" for steps 4 and 5 to work. 

Step 4: Viewing the Eye Recording

  • To view the recording, open the main recordings folder and drag the recording folder you just made (ex. 000) onto the Pupil Player shortcut on the desktop (Note, do NOT open the recording folder and attempt to drag an individual file over to Pupil Player; this will not work) This is what the path to your recording should look like (path - yourfolder\Recordings\date folder\000 etc.)
  • You will now see the worldview recording and the eye video recording; if you do not see the eye video, go to the Vis Eye Video Overlay menu and select "Show Eye0"
  • You can now play the recording - the worldview will display dots and lines which indicate where the tracker thought the eye was looking at those times
  • NOTE: this original video file does not have the accurate duration and frame/time pairings. We have to export the recording to see the correct version.

Step 5: Exporting the Recording

  • Open the Video Export Launcher menu in Pupil Player
  • Name the file by editing the "Export name" field
  • Press the export button (looks like a download icon) or press E on the keyboard to export the file
  • You will see a progress bar appear in the Video Export Launcher menu; when it is done exporting the file, it will automatically display the time it took to complete the export and the file location of the export (Note: exports automatically save in a sub folder of the original recordings folder created earlier)
  • Navigate to the exports sub folder and click on the mp4 file with the name you chose
  • The video will automatically open in your default video viewer (MediaPlayer, etc.) and will display both the worldview and the eye camera recordings with the accurate time and duration
  • New Excel files will also be created in the export sub folder with the accurate time marks and pupil tracking info
  • Note: once you export the video, the original recording may no longer open in Pupil Player


  • The Python code that sends annotations from OpenSesame to PupilCapture to mark when stimuli occur does not work in newer versions of the OpenSesame and Pupil software because of Python updates included in those software. The following software versions are currently required for the annotations to work properly:
  • OpenSesame: 3.1.2 with Python 2.7.12
  • Pupil (Capture and Player): 1.7 - 42
  • To install these older software versions, navigate to the OpenSesame Discord Releases Page ( and the PupilLabs Discord Releases Page ( and download the 64 bit packages for the versions above. 

MatLab processing

Erin has written several MatLab functions to assist in processing and analysis of Pupil Labs data. The below comments are specific to a script called “pupil_processing.m”, that was designed for a pilot study of how pupil size changes during encoding of a word list predict memory. This can be found in Z:\PROJECTS\21. Waking States Study II\Technical Files\Preprocessing. Other versions of the processing script have been developed for other studies.  

Current functionality is to:

  1. Import: pupil diameter + associated timestamps, annotations marking stimulus onset generated by OpenSeame, blink detections, and performance data from our modified DRM task
  2. Clean and plot the pupil diameter timeseries, with markers representing each stimulus presentation or other annotation
  3. Plot the 5sec before and after each CORRECTLY recalled stimulus vs. INCORRECTLY recalled stimulus, with significant differences marked


1. You must have the following MatLab functions present on the MatLab path:

  • "Z:\PROJECTS\21. Waking States Study II\Technical Files\Preprocessing\importpupil.m"
  • "Z:\PROJECTS\21. Waking States Study II\Technical Files\Preprocessing\importannotations.m"
  • "Z:\PROJECTS\21. Waking States Study II\Technical Files\Preprocessing\importblinks.m"
  • "Z:\PROJECTS\21. Waking States Study II\Technical Files\Preprocessing\importperformance.m"

2. The following data files must be present in the current MatLab directory:

  • blinks.csv
  • pupil_positions.csv
  • subject99.csv à [but named whatever your actual participant id is]
  • annotations.csv

How to Run

Run the function from the command line by typing


where fs = integer sampling rate and subjectid = a text string (enclosed in ‘single quotes’) of participant id that matches file name for the .csv file of the performance data.  An example would be:



  1. Graph of pupil diameter over time, showing original data, interpolated points, and the final filtered time series, with markers for each annotation
  2. Graph of correct vs. incorrect trials
  3. Optionally, the following variables can be saved to the workspace:
    1. Filtered = Filtered pupil diameter timeseries
    2. Annotations = Annotations file generated by pupil labs
    3. Correct_trials = Data series for the 5sec before and after each correct trial

    4. Incorrect_trials = Data series for the 5sec before and after each incorrect trial
    5. H = Whether, for each timepoint, correct and incorrect trials differ significantly (result of a ttest)
    6. P = For each timepoint, the p-value comparing correct and incorrect trials (result of a ttest

To get these outputs, you must specify variable names to save these in the call to the function, like this:

>>[filtered,annotations,correct_trials,incorrect_trials,H,P] = pupil_processing(fs,subjectid)

  File Modified
JPEG File matlab.jpg Feb 26, 2019 by ghumiston

  • No labels