References

Initialize SimpleGazeTracker toolbox

Initialize

param = SimpleGazeTracker('Initialize', wptr, wrect);

Initialize SimpleGazeTracker toolbox parameters. This method must be called first. Use SimpleGazetracker(‘UpdateParameters’,param) to configure parameters.

UpdateParameters

ret = SimpleGazeTracker('UpdateParameters',param);

Update SimpleGazeTracker toolbox parameters.

  • Parameters
  • Return
    • Cell allay of two elements.
      • First element: A negative value if new parameters are invalid.
      • Second element: Updated parameters. If the first element is negative, parameters are unchanged.

GetCameraImageSize

ret = SimpleGazeTracker('GetCameraImageSize');

Get image size of SimpleGazeTracker’s camera unit. SimpleGazeTracker(‘Connect’) must be executed in advance.

  • Parameters
    • No parameters.
  • Return
    • Array of two elements.
      • (width, height) if scceeded.
      • (-1, -1) if failed.

Open/close connection with SimpleGazeTracker

Connect

ret = SimpleGazeTracker('Connect');

Open TCP/IP connection with SimpleGazeTracker. IP address and port of SimpleGazeTracker is specified by SimpleGazeTracker parameter structure.

  • Parameters
    • No parameters.
  • Return
    • 0: Succeeded. -1: Failed.

CloseConnection

ret = SimpleGazeTracker('CloseConnection');

Close TCP/IP connection. This method must be called at the end of experiment.

  • Parameters
    • No parameters.
  • Return
    • 0: Succeeded. -1: Failed.

Open/close data file

OpenDataFile

ret = SimpleGazeTracker('OpenDataFile', filename, overwrite);

Open data file on SimpleGazeTracker.

  • Parameters
    • filename: Name of data file. File is created in the SimpleGazeTracker data directory. Absolute path (e.g. ‘/home/user/data.csv’) and relative path (e.g. ‘../data.csv’) are not supported either.
    • overwrite: If 1, SimpleGazeTracker overwrites existing data file. If 0, SimpleGazeTracker renames existing data file. For example, if ‘data.csv’ is given as the file name but ‘data.csv’ already exists, ‘data.csv’ is renamed to ‘data.csv.n’ (n=0,1,2,...).
  • Return
    • 0: Command is successfully sent. -1: Failed.

SendSettings

ret = SimpleGazeTracker('SendSettings', info);

Insert some text to SimpelGazeTracker data file. A cell array is used to pass texts to be inserted as the argument. For example, if {{‘Param1’,’Value1’},{‘Param2’,’Value2’},{‘Param3’,’Value3’}} is passed, these values are inserted to SimpleGazeTracker’s data file as following.:

#Param1,Value1
#Param2,Value2
#Param3,Value3

If you plan to use python and GazeParser library for off-line analysis, it would be convenient for you to insert GazeParser’s settings using this command.

  • Parameters
    • info: Cell allay.
  • Return
    • 0: Command is successfully sent. -1: Failed.

CloseDataFile

ret = SimpleGazeTracker('CloseDataFile');

Close data file on SimpleGazeTracker.

  • Parameters
    • No parameters.
  • Return
    • 0: Command is successfully sent. -1: Failed.

Calibration

CalibrationLoop

res = SimpleGazeTracker('CalibrationLoop');

Start Calibration procedure. SimpleGazeTracker(‘Connect’) must be called in advande.

  • Parameters
    • No parameters.
  • Return
    • Cell allay of two elements.
      • First element: ‘ESCAPE’ if calibration loop is finished by ESC key. ‘q’ otherwise.
      • Second element: 1 if calibration is performed at least once. 0 otherwise.

Start/stop recording

StartRecording

ret = SimpleGazeTracker('StartRecording', message, wait);

Start recording. Message can be inserted to describe conditions of the recording.

  • Parameters
    • message: Message to be inserted.
    • wait: Duration of waiting for starting recording. Unit is second.
  • Return
    • 0: Command is successfully sent. -1: Failed.

StopRecording

ret = SimpleGazeTracker('StopRecording', message, wait);

Stop recording. Message can be inserted to describe conditions of the recording.

  • Parameters
    • message: Message to be inserted.
    • wait: Duration of waiting for termination of recording. Unit is second.
  • Return
    • 0: Command is successfully sent. -1: Failed.

Commands during recording

SendMessage

ret = SimpleGazeTracker('SendMessage', message);

Insert message into data file. Timestamp is added on SimpleGazeTracker.

  • Parameters
    • message: Message to be inserted.
  • Return
    • 0: Command is successfully sent. -1: Failed.

GetEyePosition

pos = SimpleGazeTracker('GetEyePosition', ma, timeout);

Get latest gaze position.

  • Parameters
    • ma: 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).
    • timeout: This method fails if SimpleGazeTracker does not respond within this duration. Unit is second.
  • Return
    • Cell allay of two elements.
      • First element: Gaze position (x,y). If SimpleGazeTracker lost gaze position, (-10000,-10000) is returned.
      • Second element: Pupil area. If SimpleGazeTracker lost gaze position, 0 is returned.

GetEyePositionList

msg = SimpleGazeTracker('GetEyePositionList', n, getPupil, timeout)

Get latest gaze position list.

  • Parameters
    • n: 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. setting value far below/above from zero will take long time, resulting failure in data acquisition and/or stimulus presentation.
    • getPupil: 0 or 1. If 1, pupil area is returned with gaze position.
    • timeout: This method fails if SimpleGazeTracker does not respond within this duration. Unit is second.
  • Return
    • an n-by-4 matrix if getPupil=1. The first column is timestamp (unit=millisecond). the second and the third columns are X and Y of gaze position, respectively. The fourth column is pupil area. If getPupil=0, the fourth column is omitted (that is, n-by-3 matrix is returned). X and Y are equal or less than -10000 if SimpleGazeTracker lost gaze position. [] is returned if this method is failed.

Commands immediately after recording

GetWholeMessageList

msg = SimpleGazeTracker('GetWholeMessageList', timeout)

Get all messages inserted in the latest recording.

  • Parameters
    • timeout: This method fails if SimpleGazeTracker does not respond within this duration. Unit is second.
  • Return
    • Cell array. (i,1) is timestamp of i-th message (unit=millisecond). (i,2) is inserted message. {} is returned if this method is failed or no message has been inserted in the latest recording.

GetWholeEyePositionList

msg = SimpleGazeTracker('GetWholeEyePositionList', getPupil, timeout)

Get all gaze positions recorded in the latest recording.

  • Parameters
    • getPupil: 0 or 1. If 1, pupil area is returned with gaze position.
    • timeout: This method fails if SimpleGazeTracker does not respond within this duration. Unit is second.
  • Return
    • an n-by-4 matrix if getPupil=1. The first column is timestamp (unit=millisecond). the second and the third columns are X and Y of gaze position, respectively. The fourth column is pupil area. If getPupil=0, the fourth column is omitted (that is, n-by-3 matrix is returned). X and Y are equal or less than -10000 if SimpleGazeTracker lost gaze position. [] is returned if this method is failed.

Offline data analysis

ReadDataFile

Read SimpleGazeTracker CSV file as an array of structure.

  • Parameters
    • filename: Name of SimpleGazeTracker data file.