Eyelink 1000 Eye-Tracking System

From REALab Wiki
Jump to navigation Jump to search

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.

Important notes

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

Matlab Code

Beginning of script, eyelink initialization

%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);

End of experiment, closing eyelink

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');


Gaze-Contingent Displays

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');

Sample Reports

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.

Pupil Output

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');

Data Viewer

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.

Example Script

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.