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
EyeTrackerEyeTracker.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 |