How to control SimpleGazeTracker from an application other than GazeParser

SimpleGazeTracker can be controlled by sending commands through TCP/IP connection. For example, SimpleGazeTracker opens a new data file named ‘exp01_participant01.csv’ when receiving following text (\0 indicates null charactor).:

openDataFile\0exp01_participant01.csv\01\0

In this example, ‘openDataFile’ is a command. ‘exp01_participant01.csv’ and ‘1’ are parameters of the command. Command and each parameter must be end with \0.

Some commands have return value. \0 is reserved for representing the end of the data. For example, ‘getCurMenu’ command returns current menu item as a string.:

MinPoints(72)\0

Here ‘MinPoints(72)’ is the returned value and \0 is the terminator.

Note

‘#’ was used to represent the end of the return data in version 0.5.3 or former. Exceptionally, ‘getImageData’ command used 0xFF as the terminator instead of ‘#’.

SimpleGazeTracker is originally designed to work in conjunction with GazeParser.TrackingTools. However, SimpleGazeTracker can be controlled by other application. Following tables show SimpleGazeTracker commands. Please note that SimpleGazeTracker is under development and therefore commands may be added, modified or deleted.

Key emuration

Commands Description
key_Q

Emulating a keypress of ‘Q’ on the Recorder PC. This terminates SimpleGazeTracker.

  • Parameter: none
  • Return: none
key_UP

Emulating a keypress of up arrow key on the Recorder PC. This changes current menu item.

  • Parameter: none
  • Return: none
key_DOWN

Emulating a keypress of down arrow key on the Recorder PC. This changes current menu item.

  • Parameter: none
  • Return: none
key_LEFT

Emulating a keypress of left arrow key on the Recorder PC. This decreases value of the parameter.

  • Parameter: none
  • Return: none
key_RIGHT

Emulating a keypress of right arrow key on the Recorder PC. This increases value of the parameter.

  • Parameter: none
  • Return: none

Managing data file

Commands Description
openDataFile

Open data file on the Recorder PC. If data file is already opened, the data file is closed and a new data file is opended.

  • Parameter: name of data file, overwrite mode (0=rename, 1=overwrite)
  • Return: none
insertSettings

Insert GazeParser parameters to the data file.

  • Parameter: a string to be output to the data file. Lines must be separated by ‘/’ and the first charactor must be ‘#’.
  • Return: none
closeDataFile

Close data file.

  • Parameter: none
  • Return: none

Calibration and validation

Commands Description
getCurrMenu

Get name of current menu item.

  • Parameter: none
  • Return: a string representing current menu item.
getImageData

Request current camera image.

  • Parameter: none
  • Return: binary data of camera image. Camera image is 8bit-monochrome. A value of 255 is reserved for representing the end of the data. For example, if size of the camera image is 320x240, returned data is 320x240+1 = 76801 bytes. The last byte is 0x00 and no other byte is 0x00.
startCal

Start calibration mode.

  • Parameter: a string of comma-separated values which represents calibration area and initialization mode. If calibration area is (x1,y1,x2,y2) and initialize all calibration data, parameter is ‘x1,y1,x2,y2,1’. If you want to append calibration data to the current data, paramter is ‘x1,y1,x2,y2,0’. modified in 0.10.0.
  • Return: none.
getCalSample

Record the center of the pupil and the Purkinje image with calibration target position. These values will be used for calculating calibration parameters when endCal command is received. Modified in 0.6.0

  • Parameter: position of the target in the screen coordinate and number of samples collected at each position. If the position is (x,y) and number of samples is n, parameter is ‘x,y,n’.
  • Return: none
endCal

Stop calibraion mode.

  • Parameter: none
  • Return: none
startVal

Start validation mode.

  • Parameter: a string representing calibration target positions. For example, if target positions are (x1,y1), (x2,y2) and (x3,y3), parameter is ‘x1,y1,x2,y2,x3,y3’.
  • Return: none.
getValSample

Record the center of the pupil and the Purkinje image with validation target position. Modified in 0.6.0

  • Parameter: position of the target in the screen coordinate and number of samples collected at each position. If the position is (x,y) and number of samples is n, parameter is ‘x,y,n’.
  • Return: none
endVal

Stop validation mode.

  • Parameter: none
  • Return: none
toggleCalResult

Toggle calibration result screen on the Recorder PC.

  • Parameter: 0:off / 1:on New in 0.6.1
  • Return: none
getCalResults

Get a summary of calibration results.

getCalResultsDetail

Get detailed calibration results.

  • Parameter: none
  • Return: a string of comma-separated values. If recording mode is monocular, number of values are multiple of 4. Each 4 values represent x and y values of target point and gaze position, respectively. If recording mode is binocular, number of values are multiple of 6. Each 4 values represe x and y values of target point, gaze position of left eye and right eye, respectively.
saveCalValResultsDetail

Save detailed (raw) calibration data.

  • Parameter: none New in 0.8.0
  • Return: none

Measuring and Recording

Commands Description
startRecording

Start recording mode.

  • Parameter: message to be inserted.
  • Return: none
stopRecording

Stop recording mode.

  • Parameter: message to be inserted.
  • Return: none
startMeasurement

Start measurement mode. The measurement mode is the same as the recording mode except gaze position data is not output to the data file. This mode is used by getSpatialError().

  • Parameter: none
  • Return: none
stopMeasurement

Stop measurement mode.

  • Parameter: none
  • Return: none
insertMessage

Insert a message with timestamp.

  • Parameter: message to be inserted.
  • Return: none
getEyePosition

Get current eye position. If parameter is 1, the latest data is returned. If parameter is N (>=2), moving average of the latest N-samples is returned. Modified in 0.6.4

  • Parameter: number of samples New in 0.6.4
  • Return: a string representing current eye position. - monocular: ‘x,y,p’ - binocular: ‘lx,ly,lp,rx,ry,rp’
getWholeEyePositionList

Get all gaze position data in the latest recording. New in 0.6.4

  • Parameter: 0:without pupil data / 1:with pupil data
  • Return: a string representing recorded data. (N=n of samples)
    • parameter=0/monocular: ‘x1,y1,x2,y2,...,xN,yN’
    • parameter=1/monocular: ‘x1,y1,p1,x2,y2,p2,...,xN,yN,pN’
    • parameter=0/binocular: ‘lx1,ly1,rx1,ry1,lx2,ly2,rx2,ry2, ...,lxN,lyN,rxN,ryN’
    • parameter=1/binocular: ‘lx1,ly1,rx1,ry1,lp1,rp1, lx2,ly2,rx2,ry2,lp2,rp2,...,lxN,lyN,rxN,ryN,lpN,rpN’
getWholeMessageList

Get all messages in the latest recording. New in 0.6.4

  • Parameter: none.
  • Return: Message list. Messages are separated by ‘n’. Each messages are comma-separated values. The first element is “#MESSAGE”, the second element is timestamp and the third element is message text.
getEyePositionList

Get latest gaze position list. New in 0.6.4

  • Parameter: This command takes two parameters.
    • Parameter1 0:without pupil data / 1:with pupil data
    • Parameter2 Number of samples returned. If value is negative, Data that have already transered are not transfered.
  • Return
  • Return: a string representing recorded data. (N=n of samples)
    • parameter=0/monocular: ‘x1,y1,x2,y2,...,xN,yN’
    • parameter=1/monocular: ‘x1,y1,p1,x2,y2,p2,...,xN,yN,pN’
    • parameter=0/binocular: ‘lx1,ly1,rx1,ry1,lx2,ly2,rx2,ry2, ...,lxN,lyN,rxN,ryN’
    • parameter=1/binocular: ‘lx1,ly1,rx1,ry1,lp1,rp1, lx2,ly2,rx2,ry2,lp2,rp2,...,lxN,lyN,rxN,ryN,lpN,rpN’

Other commands

Commands Description
saveCameraImage

Save current camera preview on the Recorder PC.

  • Parameter: file name.
  • Return: none
allowRendering

Allow rendering camera preview on the Recorder PC. This feature is used by cameraDelayEstimationHelper().

  • Parameter: none
  • Return: none
inhibitRendering

Inhibit rendering camera preview on the Recorder PC. This feature is used by cameraDelayEstimationHelper().

  • Parameter: none
  • Return: none
isBinocularMode

Reterns whether recording mode is binocular or not. New in 0.6.4

  • Parameter: none
  • Return 0: monocular mode / 1: binocular mode
getCameraImageSize

Returns the camera image size.

  • Parameter: none
  • Return Width and height of the camera image (comma-separated).

How GazeParser.TrackingTools communicates with SimpleGazeTracker

Here are examples of what commands are sent by GazeParser.TrackingTools. Suppose that ‘tracker’ is an instance of GazeParser.TrackingTools.ControllerPsychoPyBackend and that recording mode is monocular.

Opening a new data file

tracker.openDataFile('test.csv', overwrite=False)

This method sends following command.:

openDataFile\0test.csv\00\0

Note

‘overwrite’ option is supported by 0.6.2 or later.

Sending settings

params = {'SCREEN_WIDTH':1024, 'SCREEN_HEIGHT':768}
tracker.sendSettings(params)

This method sends following command.:

insertSettings\0#SCREEN_WIDTH,1024/#SCREEN_HEIGHT,768\0

Calibration Loop

calarea = [-400,-300,400,300]
calTargetPos = [[   0,   0],
                [-350,-250],[-350,  0],[-350,250],
                [   0,-250],[   0,  0],[   0,250],
                [ 350,-250],[ 350,  0],[ 350,250]]

tracker.setCalibrationTargetPositions(calarea, calTargetPos)

res = tracker.calibrationLoop()

:func`~GazeParser.TrackingTools.BaseController.calibrationLoop` sends many commands. At the beginning of calibration loop, key events are checked. If up arrow key, down arrow key or ‘q’ key is pressed, corresponding key emuration command is sent. For example, if down arrow key is pressed, send following command.:

key_DOWN\0

if left or right arrow key is pressed, corresponding key emuration command is sent. Then, to update display of parameter value on the Presentation PC, getCurrMenu is sent.:

key_LEFT\0
getCurrMenu\0

The return value of getCurrMenu is like following.

PupilThreshold(56)\0

If ‘x’ key is pressed, following command is sent to toggle calibration result. A parameter (0:off/1:on) is necessary in version 0.6.1 or later:

toggleCalResult\01\0

If ‘c’ key is pressed, following command is sent to start calibration.:

startCal\0-400,-300,400,300,0\0

During calibration process, getCalSample command is sent 400ms after the target reached to new calibration point.:

getCalSample\0-350,250\0

When calibraton process is finished, stopCal command is sent. Then, getCalResults and getCalResultsDetail are sent to display calibration results on the Presentation PC.:

endCal\0
getCalResults\0
getCalResultsDetail\0

The return value of getCalResults is comma-separated values. If recording mode is monocular, four values are returned.

5.08,7.88,28.17,50.38\0

getCalResultsDetail returns a long string. In this example, there are 9 calibration points. Ten samples are collected at each point, and each sample has 4 values. Therefore, 9x10x4=360 values are returned.

-350,9,-357,8,-350,0,-368,0,-350,0,-353,-9,-350,0,-354,-8, (snip) 0,0,-1,7,0,0,2,-6\0

If ‘v’ key is pressed, validation process is started. Validation process is similar to calibration process, but startVal, getValSample and endVal are used instead of startCal, getCalSample and endCal.:

startVal\0-400,-300,400,300\0

getValSample\0-340,260\0

endVal\0
getCalResults\0
getCalResultsDetail\0

After key events are checked, get current camera image by sending getImageData if necessary.

getImageData\0

If either ‘q’ or escape key has been pressed, calibration loop ends. Otherwise, calibration loop is repeated from the beginning.

Recording

tracker.startRecording(message='trial001')
tracker.sendMessage('Target LEFT')

while runTrial:

    #snip

    tracker.getEyePosition(ma=1)

    #snip

tracker.stopRecording()

At the beginning of these codes, following commands are sent.:

startRecording\0trial001\0
insertMessage\0Target LEFT\0

Everytime when getEyePosition() is called, getEyePosition command is sent.:

getEyePosition\01\0

getEyePosition returns horizontal, vertical gaze position and pupil size. Note that units of gaze position is always pixel. Unit conversion is performed within GazeParser.TrackingTools.ControllerPsychoPyBackend.getEyePosition().

766,394,141\0

Note

Only x and y were returned in version 0.5.3 or former. ‘ma’ option is added in 0.6.4.

At the end of the codes, stopRecording is sent. Because tracker.stopRecording() doesn’t have message, parameter of stopRecording is empty.:

stopRecording\0\0

Closing the data file

tracker.closeDataFile()

This code simply sends closeDataFile command.:

closeDataFile\0