GazeParser.TrackingTools - tools for recording eye movements

class GazeParser.TrackingTools.BaseController(configFile=None)

Base class for SimpleGazeTracker controllers. Following methods must be overridden.

  • self.setCalibrationScreen(self, screen)
  • self.updateScreen(self)
  • self.setCameraImage(self)
  • self.putCalibrationResultsImage(self)
  • self.setCalibrationTargetStimulus(self, stim)
  • self.setCalibrationTargetPositions(self, area, calposlist)
  • self.getKeys(self)
  • self.verifyFixation(self, maxTry, permissibleError, key, message, ...)
  • self.setCurrentScreenParamsToConfig(self)

Initialize controller.

Parameters:configFile (str) – name of the configuration file. If None, TrackingTools.cfg in the GazeParser configuration directory is used. Default value is None.
calibrationLoop()

Start calibration loop. Following keys can be used to perform calibration.

Key Description
Z Toggle camera image display.
X Toggle calibration results display.
C Start calibration (call doCalibration() method)
V Start validation (call doValidation() method)
A Toggle on/off of Z key functions.
S Save the latest calibration/validation data to SimpleGazeTracker data file.
I Save camera image to SimpleGazeTracker data directory.
ESC or Q Exit calibration
Returns:‘escape’ or ‘q’ depending on which key is pressed to terminate calibration loop.
closeDataFile()

Send a command to close data file on the Tracker Host PC.

connect(address='', portSend=10000, portRecv=10001)

Connect to the Tracker Host PC. Because most of methods communicate with the Tracker Host PC, this method should be called immediately after controller object is created.

Parameters:
  • address (str) – IP address of SimpeGazeTracker (e.g. ‘192.168.1.2’). If the value is ‘’, TRACKER_IP_ADDRESS in the configuration file is used. Default value is ‘’.
  • portSend (int) – TCP/IP port for sending command to Tracker. This value must be correspond to configuration of the Tracker. Default value is 10000.
  • portRecv (int) – TCP/IP port for receiving data from Tracker. This value must be correspond to configuration of the Tracker. Default value is 10001.
deleteCalibrationDataSubset(points=[], updatePlot=True)

Delete specified calibration data.

Parameters:points – Points to be removed.
doCalibration(allowRecalibration=True)

Start calibration process.

doManualCalibration()

Start manual calibration process.

doValidation()

Start validation process.

fitImageBufferToTracker()

Do getCameraImageSize() and setReceiveImageSize() to fit image buffer to image size of the SimpleGazeTracker’s camera unit.

return:A tuple of two elements which represents new width and hight of the image buffer. None if failed.
getCalibrationResults(timeout=0.2)

Get a summary of calibration results. Usually, you don’t need use this method.

Parameters:timeout (float) – If the Host Tracker PC does not respond within this duration, ‘—-‘ is returned. Unit is second. Default value is 0.2
Returns:a tuple mean error and maximum error. Mean and maximum error are the distance between calibration taget position and gaze position in screen corrdinate. When recording mode is monocular, return value is (mean error, maximum error). When binocular, return value is a tuple of 4 elements: the former 2 elements correspond to left eye and the latter 2 elements correspond to right eye.
getCalibrationResultsDetail(timeout=0.2)

Get detailed calibration results.

Usually, you don’t need use this method because this method is automatically called form doCalibration() and doValidation().

Parameters:timeout (float) – If the Tracker Host PC does not respond within this duration, ‘—-‘ is returned. Unit is second. Default value is 0.2
Returns:Detailed Calibration
getCameraImage(timeout=0.2)

Get current camera image. If image data is successfully received, the data is set to self.PILimg. Usually, you don’t need use this method.

Parameters:timeout (float) – If the Host Tracker PC does not respond within this duration, image is not updated. Unit is second. Default value is 0.2
getCameraImageSize(timeout=0.2)

Get image size of SimpleGazeTracker’s camera unit.

Returns:A tuple of two elements (width, height). None if failed.
getCurrentMenuItem(timeout=0.2)

Get current menu item on the Tracker Host PC as a text. Usually, you don’t need use this method.

Parameters:timeout (float) – If the Tracker Host PC does not respond within this duration, ‘—-‘ is returned. Unit is second. Default value is 0.2
Returns:Text.
getEyePosition(timeout=0.02, getPupil=False, ma=1)

Send a command to get current gaze position.

Parameters:
  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.02
  • getPupil (bool) – If true, pupil size is returned with gaze position.
  • ma (int) – If this value is 1, the latest position is returned. If more than 1, moving average of the latest N samples is returned (N is equal to the value of this parameter). Default value is 1.
Returns:

When recording mode is monocular, return value is a tuple of 2 or 3 elements. The first two elements represents holizontal(X) and vertical(Y) gaze position in screen corrdinate. If getPupil is true, area of pupil is returned as the third element of the tuple. When recording mode is binocular and getPupil is False, return value is (Left X, Left Y, Right X, Right Y). If getPupil is True, return value is (Left X, Left Y, Right X, Right Y, Left Pupil, Right Pupil).

getEyePositionList(n, timeout=0.02, getPupil=False)

Get the latest N-samples of gaze position as a numpy.ndarray object.

Parameters:
  • n (int) –

    Number of samples. If value is negative, data that have already transfered are not transfered again. For example, suppose that this method is called twice with n=-20. If only 15 samples are obtained between the first and second call, 15 samples are transfered by the second call. On the other hand, if n=20, 20 samples are transfered by each call. In this case, part of samples transfered by the second call is overlapped with those transfered by the first call.

    Note

    setting value far below/above from zero will take long time, resulting failure in data acquisition and/or stimulus presentation.

  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.02
  • getPupil (bool) – If true, pupil size is returned with gaze position.
Returns:

If succeeded, an N x M shaped numpy.ndarray object is returned. N is number of transfered samples. M depends on recording mode and getPupil parameter.

  • monocular/getPupil=False: t, x, y (M=3)
  • monocular/getPupil=True: t, x, y, p (M=4)
  • binocular/getPupil=False: t, lx, ly, rx, ry (M=5)
  • binocular/getPupil=True: t, lx, ly, rx, ry, lp, rp (M=7)

(t=time, x=horizontal, y=vertical, l=left, r=right, p=pupil)

If length of received data is zero or data conversion is failed, None is returned.

getWholeEyePositionList(timeout=0.2, getPupil=False)

Transfer whole gaze position data obtained by the most recent recording. It is recommended that this method is called immediately after stopRecording() is called.

Note

This method can be called during recording - but please note that this method takes tens or hundreds milliseconds. It may cause failure in data acquisition and/or stimulus presentation.

Parameters:
  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.2
  • getPupil (bool) – If true, pupil size is returned with gaze position.
Returns:

If succeeded, an N x M shaped numpy.ndarray object is returned. N is number of transfered samples. M depends on recording mode and getPupil parameter.

  • monocular/getPupil=False: t, x, y (M=3)
  • monocular/getPupil=True: t, x, y, p (M=4)
  • binocular/getPupil=False: t, lx, ly, rx, ry (M=5)
  • binocular/getPupil=True: t, lx, ly, rx, ry, lp, rp (M=7)

(t=time, x=horizontal, y=vertical, l=left, r=right, p=pupil)

If length of received data is zero or data conversion is failed, None is returned.

getWholeMessageList(timeout=0.2)

Transfer whole messages inserted during the most recent recording. It is recommended that this method is called immediately after stopRecording() is called.

Note

This method can be called during recording - but please note that this method takes tens or hundreds milliseconds. It may cause failure in data acquisition and/or stimulus presentation.

Parameters:timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.2
Returns:A list of messages. Each message has three elements. The first one is ‘#MESSAGE’, the second one is timestamp, and the last one is message text.

If length of received data is zero or data conversion is failed, [] is returned.

isBinocularMode(timeout=0.2)

Check SimpleGazeTracker is in monocular or binocular mode.

Returns:True: binocualr mode, False: monocular mode.
isCalibrationFinished()

Check whether calibration is performed at least once.

Returns:True if calibration is performed at least once.
isDummy()

Returns True if this controller is dummy.

openDataFile(filename, overwrite=False)

Send a command to open data file on the Tracker Host PC. The data file is created in the DATA directory at the Tracker Host PC.

Currently, relative or absolute paths are NOT supported.

Parameters:
  • filename (str) – Name of data file.
  • overwrite (bool) – If true, SimpleGazeTracker overwrites existing data file. If false, SimpleGazeTracker renames existing data file. Default value is False.

Note

Non-ascii code is not supprted as a file name.

overlayMarkersToCalScreen(marker1=[], marker2=[], drawFrame=False)

Draw markers and frame on the calibration result.

Parameters:
  • marker1 – a list of positions of open cirlces.
  • marker2 – a list of positions of filled cirlces.
  • drawFrame – If true, frame is drawn.
plotCalibrationResultsDetail()

Plot detailed calibration results.

removeCalibrationResults()

Delete current calibration results.

saveCalValResultsDetail()

Save last calibration/validation results to SimpleGazeTracker data file.

sendCommand(command)

Send a raw Tracker command to the Tracker Host PC.

Usually, you don’t need use this method.

sendMessage(message)

Send a command to insert message to data file. Timestamp is automatically appended at the Tracker Host PC.

Parameters:message (str) – Message text to be inserted.

Note

If an unicode string is passed as a message, it is converted to UTF-8 before sending.

sendSettings(configDict)

Send a command to insert recording settings to data file.

Parameters:configDict (dict) – a dictionary object which holds recording settings.
setCalSampleAcquisitionParams(numSamplesPerPos, getSampleDelay)

Set parameters for calibration sample acquisition.

Parameters:
  • numSamplesPerPos (int) – Number of samples collected at each calibration position. This value must be must be greater than 0. Default value is defined by NUM_SAMPLES_PER_TRGPOS parameter of GazeParser.TrackingTools configuration file. By default, NUM_SAMPLES_PER_TRGPOS=10.
  • getSampleDelay (float) – Delay of starting sample acquisition from target arrived at calibration position. Unit is second. This value must not be negative. Default value is defined by CAL_GETSAMPLE_DEALAY parameter of GazeParser.TrackingTools configuration file. By default, CAL_GETSAMPLE_DEALAY=0.4.

Note

If no configuration file is specified when Controller object is created, a file named ‘TrackingTools.cfg ‘ in the GazeParser configuration directory is used as the configuration file.

setCalTargetMotionParams(durationPerPos, motionDuration)

Set parameters for calibration/validation target motion. If durationPerPos=2.5 and motionDuration=1.0, the calibration target moves to the next position over 1.0 second and stays for 1.5 (= 2.5-1.0) seconds at that position.

Parameters:
  • durationPerPos (float) – Duration in which target moves to and stays at a calibration position. Unit is second. Default value is defined by CALTARGET_DURATION_PER_POS parameter of GazeParser.TrackingTools configuration file. By default, CALTARGET_DURATION_PER_POS=2.0.
  • motionDuration (float) – Duration in which target moves to a calibration position. This duration must be shorter than durationPerPos. Unit is second. Default value is defined by CALTARGET_MOTION_DURATION parameter of GazeParser.TrackingTools configuration file. By default, CALTARGET_MOTION_DURATION=1.0.

Note

If no configuration file is specified when Controller object is created, a file named ‘TrackingTools.cfg ‘ in the GazeParser configuration directory is used as the configuration file.

setCalibrationTargetPositions(area, calposlist)

Send calibration area and calibration target positions to the Tracker Host PC. This method must be called before starting calibration.

The order of calibration target positions is shuffled each time calibration is performed. However, the first target position (i.e. the target position at the beginning of calibration) is always the first element of the list. In the following example, the target is always presented at (512, 384) a the beginning of calibration.

calArea = (0, 0, 1024, 768)
calPos = ((512, 384),
          (162, 134), (512, 134), (862, 134),
          (162, 384), (512, 384), (862, 384),
          (162, 634), (512, 634), (862, 634))
tracker.CalibrationTargetPositions(calArea, calPos)
Parameters:
  • area (sequence) – a sequence of for elements which represent left, top, right and bottom of the calibration area.
  • calposlist (sequence) – a list of (x, y) positions of calibration target.
setCurrentScreenParamsToConfig(config, screenSize, distance)

This method simply returns “config” parameter. This method must be overridden.

See also ControllerVisionEggBackend.setCurrentScreenParamsToConfig() and ControllerPsychoPyBackend.setCurrentScreenParamsToConfig().

setPreviewImageSize(size)

Set size of preview image. It is recommened that ratio of height and width is set to be the same as that of camera image.

Parameters:size (sequence) – sequence of two integers (width, height).
setReceiveImageSize(size)

Set size of camera image sent from Tracker Host PC.

Parameters:size (sequence) – sequence of two integers (width, height).
setValidationShift(size)

Set shift of the target position in the Validation process. If this parameter is 10, target position in the Validation is 10 pixel distant from target position in the Calibration process.

Parameters:size (float) – amount of shift.
startMeasurement(wait=0.1)

Send a command to start measurement without recording. This method is the same as startRecording() except data is not output to the data file. This method is called by getSpatialError(). Usually, you need not call this method.

Parameters:wait (float) – Duration of waiting for processing on the Tracker Host PC. Unit is second. Default value is 0.1
startRecording(message='', wait=0.1)

Send a command to start recording. Message can be inserted to describe trial condition and so on.

Parameters:
  • message (str) – message text. Default value is ‘’
  • wait (float) – Duration of waiting for processing on the Tracker Host PC. Unit is second. Default value is 0.1

Note

If an unicode string is passed as a message, it is converted to UTF-8 before sending.

stopMeasurement(wait=0.1)

Send a command to stop measurement. See satrtMeasurement() for detail.

Parameters:wait (float) – Duration of waiting for processing on the Tracker Host PC. Unit is second. Default value is 0.1
stopRecording(message='', wait=0.1)

Send a command to stop recording. Message can be inserted to describe exit code and so on.

Parameters:
  • message (str) – message text. Default value is ‘’
  • wait (float) – Duration of waiting for processing on the Tracker Host PC. Unit is second. Default value is 0.1

Note

If an unicode string is passed as a message, it is converted to UTF-8 before sending.

updateCalibrationTargetStimulusCallBack(t, index, targetPosition, currentPosition)

This method is called every time before updating calibration screen. In default, This method does nothing. If you want to update calibration target during calibration, override this method.

Following parameters defined in the configuration file determine target motion and acquisition of calibration samples.

  • CALTARGET_MOTION_DURATION
  • CALTARGET_DURATION_PER_POS
  • CAL_GETSAMPLE_DEALAY

These parameters can be overwrited by using setCalibrationTargetMotionParameters() and setCalibrationSampleAcquisitionParameters().

Parameters:
  • t (float) – time spent for current target position. The range of t is 0<=t<CALTARGET_DURATION_PER_POS. When 0<=t<CALTARGET_MOTION_DURATION, the calibration target is moving to the current position. When CALTARGET_MOTION_DURATION<=t<CALTARGET_DURATION_PER_POS, the calibration target stays on the current position. Acquisition of calibration samples starts when (CALTARGET_MOTION_DURATION+CAL_GETSAMPLE_DEALAY)<t.
  • index – This value represents the order of current target position. This value is 0 before calibration is initiated by space key press. If the target is moving to or stays on 5th position, this value is 5.
  • targetPosition – A tuple of two values. The target is moving to or stays on the position indicated by this parameter.
  • currentPosition – A tuple of two values that represents current calibration target position. This parameter is equal to targetPosition when CALTARGET_MOTION_DURATION<=t<CALTARGET_DURATION_PER_POS.

This is an example of using this method. Suppose that parameters are defined as following.

  • CALTARGET_MOTION_DURATION = 2.0
  • CALTARGET_DURATION_PER_POS = 1.0
tracker = GazeParser.TrackingTools.getController(backend='VisionEgg')
calstim = [VisionEgg.MoreStimuli.Target2D(size=(5, 5), color=(1, 1, 1)),
           VisionEgg.MoreStimuli.Target2D(size=(2, 2), color=(0, 0, 0))]
tracker.setCalibrationTargetStimulus(calstim)

def callback(self, t, index, targetPos, currentPos):
    if t<1.0:
        self.caltarget[0].parameters.size = ((20.0-19.0*t)*5, (20.0-19.0*t)*5)
    else:
        self.caltarget[0].parameters.size = (5, 5)

tracker.updateCalibrationTargetStimulusCallBack = callback
updateManualCalibrationTargetStimulusCallBack(t, currentPosition, prevPosition)

This method is called every time before updating calibration screen. In default, This method set “currentPos” parameter to caliration target position. If the first element of currentPos is None, calibration target position is set to (100*screen width, 100* screen height) not to display calibration target.

If you want to modify this behavior, override this method.

Parameters:
  • t (float) – time spent for current target position.
  • currentPosition – A tuple of two values that represents current calibration target position. This value is (None, None) if calibration target is not presented now.
  • prevPosition – A tuple of two values that represents previous calibration target position. This value is (None, None) if calibration target was not presented previously.

This is an example of using this method.

tracker = GazeParser.TrackingTools.getController(backend='VisionEgg')
calstim = [VisionEgg.MoreStimuli.Target2D(size=(5, 5), color=(1, 1, 1)),
           VisionEgg.MoreStimuli.Target2D(size=(2, 2), color=(0, 0, 0))]
tracker.setCalibrationTargetStimulus(calstim)

def callback(self, t, targetPos, currentPos):
    if t<1.0:
        self.caltarget[0].parameters.size = ((20.0-19.0*t)*5, (20.0-19.0*t)*5)
    else:
        self.caltarget[0].parameters.size = (5, 5)

tracker.updateManualCalibrationTargetStimulusCallBack = callback
verifyFixation(maxTry, permissibleError, key='space', mouseButton=None, message=None, position=None, gazeMarker=None, backgroundStimuli=None, toggleMarkerKey='m', toggleBackgroundKey='m', showMarker=False, showBackground=False, ma=1)

Verify spatial error of measurement. If spatial error is larger than a given amount, calibration loop is automatically called and velification is performed again.

Parameters:
  • maxTry (int) – Specify how many times error is measured before prompting readjustment.
  • permissibleError (float) – Permissible error. Unit of the value is deg.
  • key – Specify a key to get participant’s response. Default value is ‘space’.
  • mouseButton – Specify a mouse button to get participant’s response. If None, mouse button is ignored. Default value is None. See also getSpatialError().
  • message

    A sequence of three sentences. The first sentence is presented when this method is called. The second sentence is presented when error is larger than permissibleError. The third sentence is presented when prompting readjustment. Default value is a list of following sentences.

    • ‘Please fixate on a square and press space key.’
    • ‘Please fixate on a square and press space key again.’
    • ‘Gaze position could not be detected. Please call experimenter.’
  • position – Specify position of the target. If None, the center of the screen is used. Default value is None.
  • gazeMarker – Specify a stimulus which is presented on the current gaze position. If None, default marker is used. Default value is None.
  • backgroundStimuli – Specify a list of stimuli which are presented as background stimuli. If None, a gray circle is presented as background. Default value is None.
  • toggleMarkerKey (str) – Specify name of a key to toggle visibility of gaze marker. Default value is ‘m’.
  • toggleBackgroundKey (str) – Specify name of a key to toggle visibility of background stimuli. Default value is ‘m’.
  • showMarker (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • showBackground (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • ma (int) – If this value is 1, the latest position is used. If more than 1, moving average of the latest N samples is used (N is equal to the value of this parameter). Default value is 1.
Returns:

If calibration is terminated by ‘q’ key, ‘q’ is returned. Otherwise, spatial error is returned. see getSpatialError() for detail of the spatial error.

class GazeParser.TrackingTools.ControllerPsychoPyBackend(configFile=None)

SimpleGazeTracker controller for PsychoPy.

Parameters:configFile (str) – Controller configuration file. If None, default configurations are used.
convertFromPix(pos, units)

Convert units of parameters from ‘pix’. This method is called by setCalibrationTargetPositions, getEyePosition and getSpatialError.

Usually, you don’t need use this method.

Parameters:
  • pos (sequence) – Sequence of positions. odd and even elements correspond to X and Y components, respectively.
  • units (str) – ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted.
Returns:

converted list.

convertToPix(pos, units, forceToInt=False)

Convert units of parameters to ‘pix’. This method is called by setCalibrationTargetPositions, getEyePosition and getSpatialError.

Usually, you don’t need use this method.

Parameters:
  • pos (sequence) – Sequence of positions. odd and even elements correspond to X and Y components, respectively.
  • units (str) – ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted.
  • forceToInt (bool) – If true, returned values are forced to integer. Default value is False.
Returns:

converted list.

getEyePosition(timeout=0.02, units='pix', getPupil=False, ma=1)

Send a command to get current gaze position.

Parameters:
  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.02
  • units (str) – units of returned value. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
  • getPupil (bool) – If true, pupil size is returned with gaze position.
  • ma (int) – If this value is 1, the latest position is returned. If more than 1, moving average of the latest N samples is returned (N is equal to the value of this parameter). Default value is 1.
Returns:

When recording mode is monocular, return value is a tuple of 2 or 3 elements. The first two elements represents holizontal(X) and vertical(Y) gaze position in screen corrdinate. If getPupil is true, area of pupil is returned as the third element of the tuple. When recording mode is binocular and getPupil is False, return value is (Left X, Left Y, Right X, Right Y). If getPupil is True, return value is (Left X, Left Y, Right X, Right Y, Left Pupil, Right Pupil).

getEyePositionList(n, timeout=0.02, units='pix', getPupil=False)

Get the latest N-samples of gaze position as a numpy.ndarray object.

Parameters:
  • n (int) –

    Number of samples. If value is negative, data that have already transfered are not transfered again. For example, suppose that this method is called twice with n=-20. If only 15 samples are obtained between the first and second call, 15 samples are transfered by the second call. On the other hand, if n=20, 20 samples are transfered by each call. In this case, part of samples transfered by the second call is overlapped with those transfered by the first call.

    Note

    setting value far below/above from zero will take long time, resulting failure in data acquisition and/or stimulus presentation.

  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.02
  • units (str) – units of ‘position’ and returned value. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
  • getPupil (bool) – If true, pupil size is returned with gaze position.
Returns:

If succeeded, an N x M shaped numpy.ndarray object is returned. N is number of transfered samples. M depends on recording mode and getPupil parameter.

  • monocular/getPupil=False: t, x, y (M=3)
  • monocular/getPupil=True: t, x, y, p (M=4)
  • binocular/getPupil=False: t, lx, ly, rx, ry (M=5)
  • binocular/getPupil=True: t, lx, ly, rx, ry, lp, rp (M=7)

(t=time, x=horizontal, y=vertical, l=left, r=right, p=pupil)

If length of received data is zero or data conversion is failed, None is returned.

getMousePressed()

Get mouse button status.

Usually, you don’t need use this method.

getSpatialError(position=None, responseKey='space', message=None, responseMouseButton=None, gazeMarker=None, backgroundStimuli=None, toggleMarkerKey='m', toggleBackgroundKey=None, showMarker=False, showBackground=False, ma=1, units='pix')

Verify measurement error at a given position on the screen.

Parameters:
  • position – A tuple of two numbers that represents target position in screen coordinate. If None, the center of the screen is used. Default value is None.
  • responseKey – When this key is pressed, eye position is measured and spatial error is evaluated. Default value is ‘space’.
  • message (str) – If a string is given, the string is presented on the screen. Default value is None.
  • responseMouseButton – If this value is 0, left button of the mouse is also used to measure eye position. If the value is 2, right button is used. If None, mouse buttons are ignored. Default value is None.
  • gazeMarker – Specify a stimulus which is presented on the current gaze position. If None, default marker is used. Default value is None.
  • backgroundStimuli – Specify a list of stimuli which are presented as background stimuli. If None, a gray circle is presented as background. Default value is None.
  • toggleMarkerKey (str) – Specify name of a key to toggle visibility of gaze marker. Default value is ‘m’.
  • toggleBackgroundKey (str) – Specify name of a key to toggle visibility of background stimuli. Default value is None.
  • showMarker (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • showBackground (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • ma (int) – If this value is 1, the latest position is returned. If more than 1, moving average of the latest N samples is returned (N is equal to the value of this parameter). Default value is 1.
  • units (str) – units of ‘position’ and returned value. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
Returns:

If recording mode is monocular, a tuple of two elements is returned. The first element is the distance from target to measured eye position. The second element is a tuple that represents measured eye position. If measurement is failed, the first element is None.

If recording mode is binocular, a tuple of four elements is returned. The first, second and third element is the distance from target to measured eye position. The second and third element are the results for left eye and right eye, respectively. These elements are None if measurement of corresponding eye is failed. The first element is the average of the second and third element. If measurement of either Left or Right eye is failed, the first element is also None. The fourth element is measured eye position.

getWholeEyePositionList(timeout=0.02, units='pix', getPupil=False)

Transfer whole gaze position data obtained by the most recent recording. It is recommended that this method is called immediately after stopRecording() is called.

Note

This method can be called during recording - but please note that this method takes tens or hundreds milliseconds. It may cause failure in data acquisition and/or stimulus presentation.

Parameters:
  • timeout (float) – If the Tracker Host PC does not respond within this duration, tuple of Nones are returned. Unit is second. Default value is 0.2
  • units (str) – units of ‘position’ and returned value. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
  • getPupil (bool) – If true, pupil size is returned with gaze position.
Returns:

If succeeded, an N x M shaped numpy.ndarray object is returned. N is number of transfered samples. M depends on recording mode and getPupil parameter.

  • monocular/getPupil=False: t, x, y (M=3)
  • monocular/getPupil=True: t, x, y, p (M=4)
  • binocular/getPupil=False: t, lx, ly, rx, ry (M=5)
  • binocular/getPupil=True: t, lx, ly, rx, ry, lp, rp (M=7)

(t=time, x=horizontal, y=vertical, l=left, r=right, p=pupil)

If length of received data is zero or data conversion is failed, None is returned.

putCalibrationResultsImage()

Set calibration results screen.

Usually, you don’t need use this method.

setCalibrationScreen(win, font='')

Set calibration screen.

Parameters:
  • win (psychopy.visual.window) – instance of psychopy.visual.window to display calibration screen.
  • font (str) – font name.
setCalibrationTargetPositions(area, calposlist, units='pix')

Send calibration area and calibration target positions to the Tracker Host PC. This method must be called before starting calibration.

The order of calibration target positions is shuffled each time calibration is performed. However, the first target position (i.e. the target position at the beginning of calibration) is always the first element of the list. In the following example, the target is always presented at (0, 0) a the beginning of calibration.

calArea = (-400, -300, 400, 300)
calPos = ((   0,   0),
          (-350, -250), (-350,  0), (-350, 250),
          (   0, -250), (   0,  0), (   0, 250),
          ( 350, -250), ( 350,  0), ( 350, 250))
tracker.CalibrationTargetPositions(calArea, calPos)
Parameters:
  • area (sequence) – a sequence of for elements which represent left, top, right and bottom of the calibration area.
  • calposlist (sequence) – a list of (x, y) positions of calibration target.
  • units (str) – units of ‘area’ and ‘calposlist’. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
setCalibrationTargetStimulus(stim)

Set calibration target.

Parameters:stim – Stimulus object such as circle, rectangle, and so on. A list of stimulus objects is also accepted. If a list of stimulus object is provided, the order of stimulus object corresponds to the order of drawing.
setCameraImage()

Set camera preview image.

Usually, you don’t need use this method.

setCurrentScreenParamsToConfig(config, screenSize=None, distance=None)

Set current screen parameters to GazeParser.Configuration.Config object. Following parameters will be updated.

  • SCREEN_ORIGIN
  • TRACKER_ORIGIN
  • SCREEN_WIDTH
  • SCREEN_HEIGHT
  • DOTS_PER_CENTIMETER_H
  • DOTS_PER_CENTIMETER_V
  • VIEWING_DISTANCE
Parameters:
  • config (GazeParser.Configuration.Config) – instance of GazeParser.Configuration.Config config object.
  • screenSize (sequence) – Size (width, height) of screen in centimeters. If None, PsychoPy’s monitor settings are used.
  • distance (float) – Viewing distance in centimeter. If None, PsychoPy’s monitor settings are used.
Returns:

Updated configuration object.

updateScreen()

Update calibration screen.

Usually, you don’t need use this method.

verifyFixation(maxTry, permissibleError, key='space', mouseButton=None, message=None, position=None, gazeMarker=None, backgroundStimuli=None, toggleMarkerKey='m', toggleBackgroundKey='m', showMarker=False, showBackground=False, ma=1, units='pix')

Verify spatial error of measurement. If spatial error is larger than a given amount, calibration loop is automatically called and velification is performed again.

Parameters:
  • maxTry (int) – Specify how many times error is measured before prompting readjustment.
  • permissibleError (float) – Permissible error. Unit of the value is deg.
  • key – Specify a key to get participant’s response. Default value is ‘space’.
  • mouseButton – Specify a mouse button to get participant’s response. If None, mouse button is ignored. Default value is None. See also getSpatialError().
  • message

    A sequence of three sentences. The first sentence is presented when this method is called. The second sentence is presented when error is larger than permissibleError. The third sentence is presented when prompting readjustment. Default value is a list of following sentences.

    • ‘Please fixate on a square and press space key.’
    • ‘Please fixate on a square and press space key again.’
    • ‘Gaze position could not be detected. Please call experimenter.’
  • position – Specify position of the target. If None, the center of the screen is used. Default value is None.
  • gazeMarker – Specify a stimulus which is presented on the current gaze position. If None, default marker is used. Default value is None.
  • backgroundStimuli – Specify a list of stimuli which are presented as background stimuli. If None, a gray circle is presented as background. Default value is None.
  • toggleMarkerKey (str) – Specify name of a key to toggle visibility of gaze marker. Default value is ‘m’.
  • toggleBackgroundKey (str) – Specify name of a key to toggle visibility of background stimuli. Default value is ‘m’.
  • showMarker (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • showBackground (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • ma (int) – If this value is 1, the latest position is used. If more than 1, moving average of the latest N samples is used (N is equal to the value of this parameter). Default value is 1.
  • units (str) – units of ‘area’ and ‘calposlist’. ‘norm’, ‘height’, ‘deg’, ‘cm’ and ‘pix’ are accepted. Default value is ‘pix’.
Returns:

If calibration is terminated by ‘q’ key, ‘q’ is returned. Otherwise, spatial error is returned. see getSpatialError() for detail of the spatial error.

class GazeParser.TrackingTools.ControllerVisionEggBackend(configFile=None)

SimpleGazeTracker controller for VisionEgg.

Parameters:configFile (str) – Controller configuration file. If None, default configurations are used.
getKeys()

Get key events.

Usually, you don’t need use this method.

Note

This method calls pygame.event.clear()

getMousePressed()

Get mouse button status.

Usually, you don’t need use this method.

getSpatialError(position=None, responseKey='space', message=None, responseMouseButton=None, gazeMarker=None, backgroundStimuli=None, toggleMarkerKey='m', toggleBackgroundKey=None, showMarker=False, showBackground=False, ma=1)

Verify measurement error at a given position on the screen.

Parameters:
  • position – A tuple of two numbers that represents target position in screen coordinate. If None, the center of the screen is used. Default value is None.
  • responseKey – When this key is pressed, eye position is measured and spatial error is evaluated. Default value is ‘space’.
  • message – If a string is given, the string is presented on the screen. Default value is None.
  • responseMouseButton – If this value is 0, left button of the mouse is also used to measure eye position. If the value is 2, right button is used. If None, mouse buttons are ignored. Default value is None.
  • gazeMarker – Specify a stimulus which is presented on the current gaze position. If None, default marker is used. Default value is None.
  • backgroundStimuli – Specify a list of stimuli which are presented as background stimuli. If None, a gray circle is presented as background. Default value is None.
  • toggleMarkerKey (str) – Specify name of a key to toggle visibility of gaze marker. Default value is ‘m’.
  • toggleBackgroundKey (str) – Specify name of a key to toggle visibility of background stimuli. Default value is None.
  • showMarker (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • showBackground (bool) – If True, gaze marker is visible when getSpatialError is called. Default value is False.
  • ma (int) – If this value is 1, the latest position is returned. If more than 1, moving average of the latest N samples is returned (N is equal to the value of this parameter). Default value is 1.
Returns:

If recording mode is monocular, a tuple of two elements is returned. The first element is the distance from target to measured eye position. The second element is a tuple that represents measured eye position. If measurement is failed, the first element is None.

If recording mode is binocular, a tuple of four elements is returned. The first, second and third element is the distance from target to measured eye position. The second and third element are the results for left eye and right eye, respectively. These elements are None if measurement of corresponding eye is failed. The first element is the average of the second and third element. If measurement of either Left or Right eye is failed, the first element is also None. The fourth element is measured eye position.

putCalibrationResultsImage()

Set calibration results screen.

Usually, you don’t need use this method.

setCalibrationScreen(screen, font_name=None)

Set calibration screen.

Parameters:
  • screen (VisionEgg.Core.Screen) – instance of VisionEgg.Core.Screen to display calibration screen.
  • font_name (str) – font name.
setCalibrationTargetStimulus(stim)

Set calibration target.

Parameters:stim – Stimulus object such as circle, rectangle, and so on. A list of stimulus objects is also accepted. If a list of stimulus object is provided, the order of stimulus object corresponds to the order of drawing.
setCameraImage()

Set camera preview image.

Usually, you don’t need use this method.

setCurrentScreenParamsToConfig(config, screenSize, distance)

Set current screen parameters to GazeParser.Configuration.Config object. Following parameters will be updated.

  • SCREEN_ORIGIN
  • TRACKER_ORIGIN
  • SCREEN_WIDTH
  • SCREEN_HEIGHT
  • DOTS_PER_CENTIMETER_H
  • DOTS_PER_CENTIMETER_V
  • VIEWING_DISTANCE
Parameters:
  • config (GazeParser.Configuration.Config) – instance of GazeParser.Configuration.Config config object.
  • screenSize (sequence) – Size (width, height) of screen in centimeters.
  • distance (float) – Viewing distance in centimeter.
Returns:

Updated configuration object.

updateScreen()

Update calibration screen.

Usually, you don’t need use this method.

class GazeParser.TrackingTools.DummyPsychoPyBackend(configFile)

Dummy controller for PsychoPy.

closeDataFile()

Dummy function for debugging. This method does nothing.

connect(address='', portSend=10000, portRecv=10001)

Dummy function for debugging. This method does nothing.

doCalibration()

Emurates calibration procedure.

doValidation()

Emurates validation procedure.

getCalibrationResults(timeout=0.2)

Dummy function for debugging. This method does nothing.

getCalibrationResultsDetail(timeout=0.2)

Dummy function for debugging. This method does nothing.

getCameraImage()

Dummy function for debugging. This method puts a text ‘Camera Preview’ at the top-left corner of camera preview screen.

Usually, you don’t need use this method.

getCameraImageSize(timeout=0.2)

This dummy method simply returns current IMAGE_WIDTH and IMAGE_HEIGHT

getCurrentMenuItem(timeout=0.2)

Dummy function for debugging. This method does nothing.

getEyePosition(timeout=0.02, getPupil=False, units='pix', ma=1)

Dummy function for debugging. This method returns current mouse position.

getEyePositionList(n, timeout=0.02, units='pix', getPupil=False)

Dummy function for debugging. This method returns mouse position list. Use recordCurrentMousePos() method to record mouse position.

getWholeEyePositionList(timeout=0.02, units='pix', getPupil=False)

Dummy function for debugging. This method returns mouse position list. Use recordCurrentMousePos() method to record mouse position.

getWholeMessageList(timeout=0.2)

Dummy function for debugging. This method emurates getWholeMessageList.

isBinocularMode(timeout=0.2)

Currently dummy controller emulates only monocular recording.

isDummy()

Returns True if this controller is dummy.

openDataFile(filename)

Dummy function for debugging. This method does nothing.

recordCurrentMousePos()

Record current mouse position. This method is for debugging — included only in dummy controller. Therefore, make sure that your controller is dummy controller before calling this method.

Example:

if tracker.isDummy():
    tracker.recordCurrentMousePos()
sendCommand(command)

Dummy function for debugging. This method outputs commands to standard output instead of sending it to SimpleGazeTracker.

sendMessage(message)

Dummy function for debugging. This method emurates sendMessage.

sendSettings(configDict)

Dummy function for debugging. This method does nothing.

setCalibrationScreen(win, font='')

Set calibration screen.

startMeasurement(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

startRecording(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

stopMeasurement(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

stopRecording(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

class GazeParser.TrackingTools.DummyVisionEggBackend(configFile)

Dummy controller for VisionEgg.

closeDataFile()

Dummy function for debugging. This method does nothing.

connect(address='', portSend=10000, portRecv=10001)

Dummy function for debugging. This method does nothing.

doCalibration()

Emurates calibration procedure.

doValidation()

Emurates validation procedure.

getCalibrationResults(timeout=0.2)

Dummy function for debugging. This method does nothing.

getCalibrationResultsDetail(timeout=0.2)

Dummy function for debugging. This method does nothing.

getCameraImage()

Dummy function for debugging. This method puts a text ‘Camera Preview’ at the top-left corner of camera preview screen.

Usually, you don’t need use this method.

getCameraImageSize(timeout=0.2)

This dummy method simply returns current IMAGE_WIDTH and IMAGE_HEIGHT

getCurrentMenuItem(timeout=0.2)

Dummy function for debugging. This method does nothing.

getEyePosition(timeout=0.02, getPupil=False, ma=1)

Dummy function for debugging. This method returns current mouse position.

getEyePositionList(n, timeout=0.02, getPupil=False)

Dummy function for debugging. This method returns mouse position list. Use recordCurrentMousePos() method to record mouse position.

getWholeEyePositionList(timeout=0.02, getPupil=False)

Dummy function for debugging. This method returns mouse position list. Use recordCurrentMousePos() method to record mouse position.

getWholeMessageList(timeout=0.2)

Dummy function for debugging. This method emurates getWholeMessageList.

isBinocularMode(timeout=0.2)

Currently dummy controller emulates only monocular recording.

isDummy()

Returns True if this controller is dummy.

openDataFile(filename)

Dummy function for debugging. This method does nothing.

recordCurrentMousePos()

Record current mouse position. This method is for debugging — included only in dummy controller. Therefore, make sure that your controller is dummy controller before calling this method.

Example:

if tracker.isDummy():
    tracker.recordCurrentMousePos()
sendCommand(command)

Dummy function for debugging. This method outputs commands to standard output instead of sending it to SimpleGazeTracker.

sendMessage(message)

Dummy function for debugging. This method emurates sendMessage.

sendSettings(configDict)

Dummy function for debugging. This method does nothing.

setCalibrationScreen(screen, font_name=None)

Set calibration screen.

startMeasurement(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

startRecording(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

stopMeasurement(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

stopRecording(message='', wait=0.2)

Dummy function for debugging. This method does nothing.

GazeParser.TrackingTools.cameraDelayEstimationHelper(screen, tracker)

A simple tool to help estimating measurement delay. See documents of GazeParser for detail.

Parameters:
  • screen – an instance of psychopy.visual.Window or VisionEgg.Core.Screen.
  • tracker – an instance of GazeParser.TrackingTools.ControllerPsychoPyBackend or GazeParser.TrackingTools.ControllerVisionEggBackend.
GazeParser.TrackingTools.getController(backend, configFile=None, dummy=False)

Get Tracker controller object.

Parameters:
  • backend (str) – specify screen type. ‘VisionEgg’, ‘PsychoPy.
  • configFile (stt) – Controller configuration file. If None, Tracker.cfg in the application directory is used. Default value is None.
  • dummy (bool) – Get dummy controller for standalone debugging. Default value is False.