Eyelink Toolbox

FAQ

Eyelink Toolbox

Psychtoolbox

Home

Intro

Download

Mac OS9

Win

Forum

Help

Last updated: 24-12-2004

 

Is there documentation on the EyelinkToolbox?

There's no eyelinktoolbox manual (volunteer, anyone?). But there's a few places were you can find info that should help you get started:

1. study the demo's provided with the toolbox
2. typing eyelink at the matlab prompt provides an overview of possible eyelink commands
3. this faq and the help page
4. as pointed out by Jochen Laubruck, the original eyelink programming manual is a good place to find out about which commands can be passed via the eyelink toolbox function EYELINK('command', 'formatstring', [...]). Look for eyecmd_printf() and the section titled "Useful Eyelink Commands".

5. search the psychtoolbox forum's messages
6. post a question on the forum.
7. Eyelinktoolbox paper.
 

Claudiu Simion asked: I am a new user of Eyelink and have experience with Psychtoolbox for PC. I recently downloaded the Eyelink toolbox for PC. I tried to compose a simple program with Eyelink toolbox, but I don't know where to start, the help only gives the command syntax, without ellaborating.

In the EyelinkToolbox directory is a subdirectory EyelinkDemos that
contains a number of examples that should get you started using
the Eyelink and EyelinkToolbox. The "contents.m" file at the top level of the EyelinkToolbox gives a (more or less complete) overview of all directories and all files that are in the toolbox. The help page gives some simple instructions as well. If you have gone through all these steps, and it still doesn't work, (and you have seeved through this FAQ as well), we suggest posting a message on the forum, accurately describing your problem, your OS, matlab version, Operator PC software version, and, in case of a bug, a minimal program that exhibits the bug.

We will adapt the eyelink.m file in a future version so that it too points to the demos.

Can I try the demos without having an eyelink?

Some of the demo's (e.g. EyelinkEventExample.m) will run without an Eyelink. In that case the mouse is used for "simulating" an eye. Press 'ESC' when you encounter a blank screen (this is when normally setup would happen). You'll see a dot, press and release space to start the actual demo.

 

Does the Eyelink Toolbox run natively on Mac OS X?

No, it will only run in OS 9 or classic mode, but in the latter case, the timinig of the vertical blanking of your display cannot be determined by SCREEN, so timing is inaccurate. We suggest only running actual experiments under native OS 9.

Will there ever be an Eyelink Toolbox for Mac OS X?

Probably. SR-Research has released an experiment support library that works under OS X. The Eyelink Toolbox will be build on top of that. We have developed a very rudimentary OS X version, but it needs quite a bit of polishing, and not all functions work correctly yet, hence we're not releasing it yet. We also want to be sure it will work with a release 1 version of the psychtoolbox. Send an email or post a message on the forum if you require a version very quickly.

Does the Eyelink Toolbox run on Win 95, 98, 2000, XP?

Many people have gotten it to work under various versions of Windows (98 and XP and 2000).

But it is not always without problems. Read on for details.

I get an error saying ''??? Invalid mex-file -- the specified module could not be found''

What is wrong? And what should I do?

Ronald van den Berg figured it all out (for XP at least). Follow this link for details on how to solve this type of problems.

 

Some more on path problems and finding dll's.

E.g Kristian Lukander reports: On Windows XP,
the toolbox seems to work with all of our current versions of Matlab (5.1,
6.1 and 6.5). On Windows 2000 however, it doesn't work with at least any of the above versions. I don't think it's very likely to be a Matlab problem rather than a Windows problem. For instance both XP and 98 have their dll-files in a directory named \Windows\System32 whereas Win2000 uses a directory named \Win32\System32. Could the problem be that the path for the dll-file is hard-coded to the first case?

Enno Peters found this tidbit:

The search path for a dll is never hard coded, the following info I got
from msdn concering this search path;
---
The Search Path Used by Windows to Locate a DLL

With both implicit and explicit linking, Windows first searches the set
of pre-installed DLLs such as the performance library (KERNEL32.DLL) and the security library (USER32.DLL). Windows then searches for the DLLs in the following sequence:

That also means that I still don't have a clue why it doesn't work under
Windows 2000, and also havent had the chance to test it.

 

The Eyelink Toolbox doesn't work on any windows version?

To get the Toolbox running on windows you need to update the Eyelink Experiment Toolkit to version 2.0.

Do you have standard settings in the EyeLink Toolbox which can be
changed and maybe adapted to our network?

No. The Eyelink Toolbox doesn't define anything in a fixed manner. As far as we know, all settings for the Eyelink can be found in the .INI files (that's how it is on the mac). Browse through them and look for something that looks like and IP nr.
(Sebastian Pannasch wrote: I installed the version 2. properly and it works - more or less. We use our eyetracker also in connection with a driving simulation on LINUX - therefore we changed the IP adress - with the old Eyelink Experiment Toolkit everything is fine. Using the new version I got "connection timed out" - the same for the EyeLink Toolbox, but I guess this is our problem we have to fix it for ourself. (indeed....fwc)
Do you have standard settings in the EyeLink Toolbox which can be
changed and maybe adapted to our network?). (No, thus. FWC).

How can we thank you for developing this toolbox?

We repeat after Denis Pelli and David Brainard: Do not thank us, cite us. If you want to acknowledge the use of this software when you publish your research, you could do so in the following way:

"We wrote our experiments in Matlab, using the Psychophysics and Eyelink Toolbox extensions (Brainard, 1997; Pelli, 1997; Cornelissen, Peters & Palmer, 2002; see http://psychtoolbox.org/)."

Brainard, D. H. (1997) The Psychophysics Toolbox, Spatial Vision 10:433-436.

Cornelissen, F.W., Peters. E., Palmer, J. (2002). The Eyelink Toolbox: Eye tracking with MATLAB and the Psychophysics Toolbox. Behavior Research Methods, Instruments & Computers, 34, 613-617.

Pelli, D. G. (1997) The VideoToolbox software for visual psychophysics: Transforming numbers into movies, Spatial Vision 10:437-442.

Why aren't the native "trackersetup" and "driftcorrection" commands available in the windows version?

The built-in functions 'dotrackersetup' and 'driftcorrection' are only supported on macintosh. There are an equivalent files in the matlab toolbox (in "dotrackersetup.m" and "dodriftcorrect.m") that do exactly the same. This works on both mac and PC.Their presence in the mac version is in principle only temporary. We put them in for testing purposes. Use the MATLAB versions (.m files) instead. We are now quite convinced they work properly. They have the advantage of being much more flexible to adapt (would you want to do so). The mac built-in versions remain present as long as they work properly, but we will not support them any longer. After all, we have the Psychtoolbox to do the graphics for us!

 

Does the Eyelink Toolbox work with Eyelink II?

Yes, it does run without any problems (only mac version verified for sure).

How can I use events in my experiment?

The demo "eyelinkeventexample.m" in the directory EyelinkDemos/ShortDemos/ provides an example of how to use events to achieve certain things. In this case it doesn't stop as you want to do, but changes the contrast of a number, but I guess you'll get the picture.

The main commands (you'd probably want to put these in some more elaborate loop):

while 1
evtype=eyelink('getnextdatatype');
if evtype==el.ENDSACC
break;
end
end

Antje Nuthmann wrote a long message on the forum with some interesting thoughts and questions:


I'm working with eyelink II, Mac OS 9.2, MATLAB 5.2.1.1421,
PsychToolbox 2.52 as well as the Eyelink Toolbox.
I want to work saccade contingent in a reading experiment.
I think I could control for the delay caused by the eyelink system as
well as for the restrictions set by the monitor refresh rate (120 Hz)
quite well.

My main problem now is MATLAB. It's slow. Setting the PixelSize
(color depth) from 32 down to 16 seemed to make things faster. Still,
according to my timing by using getSecs it takes on average 10 ms
(!!!) (sometime up to 20 ms) to run the relevant code used for online
saccade detection etc. By the way, this is not due to CopyWindow,
since I change only a small part of the screen during the saccade.

To begin with I was encouraged by reading in Cornelissen et al.
(2002) that "only a fraction of a millisecond is due to the overhead
of MATLAB...". As I now understand, the functions of the Eyelink
Toolbox are fast because they rely on underlying C functions, BUT the
functions I programmed myself are slow since I use "native MATLAB
code".
What can I do about it?

THOUGHTS:

1) SpeedTest by the Psychophysics Toolbox made some suggestions for
optimizing the MATLAB code (e.g., ~= is slower than ==). I'm
working not only with scalars and arrays, but also with structured
arrays.
Does anybody know whether accessing structured arrays costs more time
than accessing normal arrays? I'm also wondering whether working
with global variables is less time consuming than passing variables
as arguments of a function? Any suggestions in general?

2) Since there is quite a big variability in the time it takes to run
the relevant code, I thought it might be helpful to use the RUSH
function.
I finally found out how to use it but I am still puzzled.
Obviously it is possible to rush eyelink commands like eyelink
(`newestfloatsample'), at least I didn't get any error messages.
I'm puzzled about MaxPriority. Obviously I cannot pass my self-
programmed functions. But I cannot pass `eyelink' either, maybe
because it is not a function (but a MEX file)? Maybe I can use
MaxPriority for inbuilt functions only? I sort of sense that the Mac
needs to know what kind of priority the eyelink system needs or has.
Maybe it is set somewhere?
Anyway, I finally succeeded in using rush (in terms of not getting
any error messages anymore), but it also led to the highly undesired
fact that no messages were written in the message file ("xxx messages
lost" appeared at the end of the file).
So I ended up rushing only part of the relevant code, but according
to timing by using getSecs that didn't help.

3) I've heard that one can 'c compile' matlab functions. Would that
help and how can I do that?

4) In example code by SR research I saw the functions
begin_realtime_mode &
end_realtime_mode
Is there an equivalent in the Eyelink Toolbox? Or am I supposed the
handle it with the rush function?

... any suggestions, explanations, own experiences are highly
appreciated

thanks a lot
Antje Nuthmann

A few short remarks:

Maxpriority doesn't know about eyelink because it is not part of the Psychtoolbox per se.

Are you refering to the online saccade detection by the eyelink (operator PC) itself, or did you program this code yourself?

I am not aware of begin_realtime_mode & end_realtime_mode functions. I presume these are part of the new API's. If so, they're not part of the eyelinktoolbox (for that reason).

In the eyelinktoolbox code there are two examples (eyelinkexample.m & eyelinkeventexample.m) of how to create reasonably fast gaze contingent experiments.

But, c will always out perform matlab code. So, if you need to do a lot in real-time, and can't prepare your stimuli, I would suggest to use c. You can of course also use a hybrid approach, and only c-code the time critical part of your experiment, and create a mex file for that.
I don't believe you can compile PsychToolbox and eyelink toolbox code as such (I have never tried).

There's also a few ways in which you can improve performance of the eyelink, e.g. do not use filtering, shaves 4 ms of the response time (but gives less accurate saccade estimates).

At which priority level does the eyelink toolbox run?

Jochen Laubrock commented: At the "subject PC" side (i.e. the machine running the experimental software), the eyelink system does not add any hardware, but relies on TCP/IP communication via ethernet. Do you know at which priority level this is still functional? thanks, jochen

It relies on ethernet, you're correct. I don't know about the tolerable priority level. Better try first. If you have time to do some testing ....

Denis Pelli commented: if you decide to enhance MaxPriority.m to support EyeLink and send it to us, we'll fold it into the master distribution.

We haven't done this. Volunteer?