Eyelink 1000 Eye-Tracking System
Our SR Research Eyelink 1000 eye tracking systems record pupil movement data at 1000 Hz sampling rate 0.25-0.50 degree accuracy. We have 4 desktop mounted Eyelink 1000 systems, 2 in each lab.
- 1 Important notes
- 2 Matlab Code
When communicating with the Eyelink vis messages or commands, it's important to note the following:
- File names must consist only of numbers - e.g., instead of 's01' for subject 01, use the file name '01' (*correction: what really matters is the number of bytes in the name, so if you're unable to output a file try shortening the file name)
- Image file names must not contain spaces - this is important when writing images to be overlaid in data viewer, since image file names with spaces will not be overlaid
- Screen coordinates must not have decimal places - e.g., when defining coordinates of Interest Areas, or Background Images, or other Screen coordinates, make sure to use whole numbers or the command will not work
%Provide Eyelink with details about the graphics environment % and perform some initializations. The information is returned % in a structure that also contains useful defaults % and control codes (e.g. tracker state bit and Eyelink key values). el=EyelinkInitDefaults(expWindow); % Initialization of the connection with the Eyelink Gazetracker. % exit program if this fails. if ~EyelinkInit(dummymode, 1) fprintf('Eyelink Init aborted.\n'); % **here execute any cleanup and shutdown functions** Screen('closeall'); return; end [v vs]=Eyelink('GetTrackerVersion'); fprintf('Running experiment on a ''%s'' tracker.\n', vs ); fileName=sprintf('%s_RT.edf', subjectNumber); %NB: must be number, not string!!! Eyelink('Openfile',fileName); %configuration settings Eyelink('command','screen_pixel_coords = %ld %ld %ld %ld', 0, 0, mX-1, mY-1); %mX and mY are max x and y screen coordinates Eyelink('message', 'DISPLAY_COORDS %ld %ld %ld %ld', 0, 0, mX-1, mY-1); % make sure that we get gaze data from the Eyelink Eyelink('Command', 'link_sample_data = LEFT,RIGHT,GAZE,AREA'); % Calibrate the eye tracker EyelinkDoTrackerSetup(el);
Eyelink('closefile'); % download data file try fprintf('Receiving data file ''%s''\n', fileName); status=Eyelink('ReceiveFile',fileName); if status > 0 fprintf('ReceiveFile status %d\n', status); end if 2==exist(fileName, 'file') fprintf('Data file ''%s'' can be found in ''%s''\n', fileName, pwd ); end catch rdf fprintf('Problem receiving data file ''%s''\n', fileName ); rdf; end
DataViewer trial marking
If you want to break up different trials in DataViewer, then put this code before and after the trail:
Eyelink('StartRecording'); %code for one trial goes here EYELINK('stoprecording');
Areas of interest
You can create Areas of Interest for a picture in DataViewer, which should output *.ias file for that picture. Then when that picture is shown in matlab, you can use the following code which will allow Eyelink to tell whether the eyes focused on that AOI. Note from Sarah: if you want to use this, you have to present the picture/image for a long enough time for the image to load (likely more than 1sec, maybe closer to 2seconds), so this may not work well with very dynamic stimuli presentations.
Screen('Flip', expWindow); % Displays the window so you can see it template = ['InterestAreas/Photo' num2str(photoNumber) '-InterestAreas.ias']; %"template" is just a var name Eyelink('Message', '!V IAREA FILE %s', template); %note: you have to use the right .ias filename for given pic
This is useful for analyzing randomized experiments where different trials have different AOIs.
Real time gaze coordinates
You can find the x and y gaze coordinates in real time with the following code. (This is from the eyelinkgazecontingentdemo.m script included with psychtoolbox).
if Eyelink('NewFloatSampleAvailable') > 0 % get the sample in the form of an event structure evt = Eyelink( 'NewestFloatSample'); if eye_used ~= -1 % do we know which eye to use yet? % if we do, get current gaze position from sample x = evt.gx(eye_used+1); % +1 as we're accessing MATLAB array y = evt.gy(eye_used+1); % do we have valid data and is the pupil visible? if x~=el.MISSING_DATA && y~=el.MISSING_DATA && evt.pa(eye_used+1)>0 eyemx=x; eyemy=y; end end end
To work, you need this at the top (right below the line: EyelinkDoTrackerSetup(el);):
WaitSecs(0.1); eye_used = Eyelink('EyeAvailable'); % get eye that's tracked if eye_used == el.BINOCULAR; % if both eyes are tracked eye_used = el.LEFT_EYE; % use left eye end
and you should should have this at the beginning and end of each trial:
%START RECORDING Eyelink('StartRecording'); error=Eyelink('CheckRecording'); if(error~=0) break; end
%STOP RECORDING Eyelink('StopRecording');
You can use the real time gaze coordinates to update the screen or change images depending on where the subject is looking. e.g., The below code will display a fixation cross for 2 seconds- it will display one fixation cross image when subjects are not looking at it (texhomebox), and another fixation cross image when it's being fixated (texhomeboxfix):
%display fixation image Screen('DrawTexture', w, texhomebox, , [mX/2-20, mY/2-20, mX/2+20, mY/2+20]); [VBLTimestamp startrt]=Screen('Flip', w); %START RECORDING Eyelink('StartRecording'); error=Eyelink('CheckRecording'); if(error~=0) break; end %begin loop for 2 seconds, mark if subjects are not continuing to look at fixation cross with earlystartflag variable earlystartflag=0; while (GetSecs-startrt)<=2.00 if Eyelink('NewFloatSampleAvailable') > 0 % get the sample in the form of an event structure evt = Eyelink('NewestFloatSample'); if eye_used ~= -1 % do we know which eye to use yet? % if we do, get current gaze position from sample x = evt.gx(eye_used+1); % +1 as we're accessing MATLAB array y = evt.gy(eye_used+1); % do we have valid data and is the pupil visible? if x~=el.MISSING_DATA && y~=el.MISSING_DATA && evt.pa(eye_used+1)>0 eyemx=x; eyemy=y; %added this- change fixation image if looking at it Screen(w, 'FillRect', white); if (eyemx> (mX/2-100) && eyemx < (mX/2+100) && eyemy> (mY/2-100) && eyemy < (mY/2+100)) Screen('DrawTexture', w, texhomeboxfix, , [mX/2-20, mY/2-20, mX/2+20, mY/2+20]); DrawFormattedText(w, message, 'center', mY/2+100, black); else Screen('DrawTexture', w, texhomebox, , [mX/2-20, mY/2-20, mX/2+20, mY/2+20]); DrawFormattedText(w, message, 'center', mY/2+100, black); if (GetSecs-startrt)>=1.500 earlystartflag=1; end end Screen('Flip', w); end end end end %...rest of trial goes here... %end recording for this trial Eyelink('StopRecording');
If you're having an issue trying to get sample reports out of Data Viewer, make sure "load samples" is checked upon importing an edf file. In the inspector window (you make have to load an edf file and then delete it to get this to show up), click on the preferences tab. Then go to "data loading" and make sure "load samples" is checked.
Now when you import an edf file, you should be able to see "sample reports" as an option in the analysis>output menu.
If you're not getting pupil data from your sample output, you may need to include these lines in matlab (after the commands for opening the eyelink file):
Eyelink('command', 'file_sample_data = LEFT,RIGHT,GAZE,HREF,AREA,GAZERES,STATUS,INPUT'); Eyelink('command', 'link_sample_data = LEFT,RIGHT,GAZE,GAZERES,AREA,STATUS,INPUT');
If your matlab code worked correctly, you should have output an edf file which includes in it overlay images, AOIs, condition info, and info about the beginning and end of your trial (the period when you are actually interested in eye movements, e.g., usually from right after the fixation cross until the participant responded). You can double click on the .edf file and look around to confirm all this information is present, and then output a trial report, fixation report, AOI report, or saccade report by selecting which variables you want to output and then saving as a text file. This text file can be imported into R for analysis.
An example script which includes gaze contingent eyelink code (i.e., only start the trial when the participant is looking at the fixation cross), AOIs which change from trial to trial (waste bin signs with randomized positions), image overlays on the edf file (i.e., when looking at eye gaze data in data viewer, the subject's fixations will be shown over an image of what was actually shown on that trial), and condition info (i.e., sign style condition for each trial), is available for download here: signage_recycling_eyelink.zip
The main script to run is signage_recycling.m. All the bits of code for communicating with the eyelink are enclosed in if statements like this:
if strcmp(elstate,'on') ... end
You can turn the eyelink bits of code on or off by changing elstate='on' at the top of the program. I would recommend you first make sure the program runs without the eyelink code, then if everything looks alright turn the eyelink code on.
Another example script is available here: EyeLinkPicture.m. I haven't actually run this code but I have found it useful to look over as it's very well commented.