PyGaze
The open-source toolbox for eye tracking

PyGaze - documentation - eyetracker

The eyetracker library is used to create EyeTracker objects, to communicate with an eye tracker. Both SMI and EyeLink systems are supported, as well as a dummy mode, which uses the mouse to simulate eye movements.

contents

EyeTracker
EyeTracker.calibrate
EyeTracker.close
EyeTracker.connected
EyeTracker.drift_correction
EyeTracker.fix_triggered_drift_correction
EyeTracker.log_var
EyeTracker.pupil_size
EyeTracker.sample
EyeTracker.send_command
EyeTracker.start_recording
EyeTracker.status_msg
EyeTracker.stop_recording
EyeTracker.wait_for_blink_end
EyeTracker.wait_for_blink_start
EyeTracker.wait_for_event
EyeTracker.wait_for_fixation_end
EyeTracker.wait_for_fixation_start
EyeTracker.wait_for_saccade_end
EyeTracker.wait_for_saccade_start

EyeTracker

arguments
display a libscreen.Display object

keyword arguments
trackertype the eye tracker type (a string value), indicating which type of tracker is attached; should be 'eyelink', 'smi', 'tobii', or 'dummy' (default = TRACKERTYPE)
resolution display resolution (tuple or list), e.g. (1280,1024) (default = DISPSIZE)
eyedatafile the name (string value) for the file in which gaze data will be stored (default = LOGFILENAME)
logfile logfile name (string value); note that this is the name for the SMI logfile, NOT the .idf file (default = LOGFILE)
fgc the foreground colour: a colour name (e.g. 'red') or a RGB tuple (e.g. (255,0,0)) (default = FGC)
bgc the background colour: a colour name (e.g. 'red') or a RGB tuple (e.g. (255,0,0)) (default = BGC)
saccvelthresh saccade velocity threshold in degrees of visual angle per second (default = SACCVELTHRESH)
saccaccthresh saccade acceleration threshold in degrees of visual angle per square second (default = SACCACCTHRESH)
ip SMI ONLY: internal ip address for iViewX (default = SMIIP)
sendport SMI ONLY: port number for iViewX sending (default = SMISENDPORT)
receiveport SMI ONLY: port number for iViewX receiving (default = SMIRECEIVEPORT)

Calibrates the eye tracking system
arguments
None

keyword arguments
None

returns
None puts tracker into calibration mode; if an SMI tracker is used, a calibration report is added to the SMI logfile and some properties are updated (i.e. the thresholds for detection algorithms)

Neatly close connection to tracker
arguments
None

keyword arguments
None

returns
None saves data and sets self.connected to False

Checks if the tracker is connected
arguments
None

keyword arguments
None

returns
None True if connection is established, False if not; sets self.connected to the same value

Performs a drift check
arguments
None

keyword arguments
pos (x, y) position of the fixation dot or None for a central fixation (default = None)
fix_triggered Boolean indicating if drift check should be performed based on gaze position (if fix_triggered = True) or on spacepress (if fix_triggered = False) (default = False)

returns
checked Boolean indicating if drift check is ok (True) or not (False); or calls self.calibrate if 'q' or 'escape' is pressed

Performs a fixation triggered drift check by collecting a number of samples and calculating the average distance from the fixation position
arguments
None

keyword arguments
pos (x, y) position of the fixation dot or None for a central fixation (default = None)
min_samples minimal amount of samples after which an average deviation is calculated (default = 10)
max_dev maximal gaze deviation from fixation in pixels (default = 60)
reset_threshold if the horizontal or vertical distance in pixels between two consecutive samples is larger than this threshold, the sample collection is reset (default = 30)

returns
checked Boolean indicating if drift check is ok (True) or not (False); or calls self.calibrate if 'q' or 'escape' is pressed

Writes a variable to the log file
arguments
var variable name
val variable value

keyword arguments
None

returns
None uses native log function of iViewX to write to the SMIlog (SMI) or writes to the EDF (EyeLink) to include a line in the log file in a "var NAME VALUE" layout

Returns pupil size
arguments
None

keyword arguments
None

returns
pupilsize returns pupil diameter for the eye that is currently being tracked (as specified by self.eye_used) or None when no data is obtainable

Returns newest available gaze position
arguments
None

keyword arguments
None

returns
sample an (x,y) gaze position tuple or (-1,-1) on an error

Sends a command to the eye tracker
arguments
cmd the command (a string value) to be sent to iViewX (SMI) or to the EyeLink

keyword arguments
None

returns
None

Starts recording eye position
arguments
None

keyword arguments
None

returns
None sets self.recording to True when recording is successfully started

Displays a message on the EyeLink PC (not supported for SMI)
arguments
msg a message (string value) to be displayed on the EyeLink PC

keyword arguments
None

returns
None displays a message on the EyeLink PC; for SMI this method simply passes

Stops recording eye position; note that stopping recording via this method is reversable, recording starts again when self.start_recording is called; call self.close() to fully close the connection to the eye tracker
arguments
None

keyword arguments
None

returns
None sets self.recording to False when recording is successfully stopped

Waits until a blink is started and finished
arguments
None

keyword arguments
None

returns
time timestamp of the end of a blink

Waits until a blink is started
arguments
None

keyword arguments
None

returns
time timestamp of the start of a blink

Waits for a specified event
arguments
event for EyeLink, event should be a pylink event (e.g. pylink.ENDSACC); for SMI it should be an integer event code, one of the following:
3 = STARTBLINK
4 = ENDBLINK
5 = STARTSACC
6 = ENDSACC
7 = STARTFIX
8 = ENDFIX

keyword arguments
None

returns
outcome for EyeLink, FloatData for the specified event is returned; for SMI a self.wait_for_* method is called, depending on the specified event, the return values of corresponding method are returned

Returns time and gaze positions when a fixation is ended; function assumes that a 'fixation' has ended when a deviation of more than self.pxfixtresh from the initial fixation position has been detected (self.pxfixtresh is created in self.calibration, based on self.fixtresh, a property defined in self.__init__)
arguments
None

keyword arguments
None

returns
time, startpos, endpos time is a timestamp (ms) of a fixation end, startpos is a (x,y) gaze position tuple of the position from which the fixation started, endpos is a (x,y) gaze position tuple of the position on which the fixation ended

Returns starting time and position when a fixation is started; function assumes a 'fixation' has started when gaze position remains reasonably stable (i.e. when most deviant samples are within self.pxfixtresh) for 150 ms (self.pxfixtresh is created in self.calibration, based on self.fixtresh, a property defined in self.__init__)
arguments
None

keyword arguments
None

returns
time, startpos time is a timestamp (ms) of a fixation end, startpos is a (x,y) gaze position tuple of the position from which the fixation started

Returns ending time, and both saccade start and end position when a saccade is ended; based on Dalmaijer et al. (2013) online saccade detection algorithm
arguments
None

keyword arguments
None

returns
endtime, startpos, endpos endtime in milliseconds (from expbegintime); startpos and endpos are (x,y) gaze position tuples

Returns starting time and starting position when a saccade is started; based on Dalmaijer et al. (2013) online saccade detection algorithm
arguments
None

keyword arguments
None

returns
starttime, startpos starttime in milliseconds (from expbegintime); startpos is an (x,y) gaze position tuple

full source

You can find the full source code for eyetracker.py on GitHub.

Please note that the EyeTracker class simply morphes into the class that is responsible for communication with a different type of eye trackers. Each of these classes contains the methods described above. Which class will be morphed into, depends on a user's preference. For the full source code of every individual eye tracker class, see below.

EyeLink libeyelink.py
SMI libsmi.py
dummy libdummytracker.py

© copyright 2013-2014, Edwin S. Dalmaijer