.. _reference: References ========== Initialize SimpleGazeTracker toolbox ------------------------------------ Initialize ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab param = SimpleGazeTracker('Initialize', wptr, wrect); Initialize SimpleGazeTracker toolbox parameters. This method must be called first. Use SimpleGazetracker('UpdateParameters',param) to configure parameters. * Parameters * **wptr:** Window pointer returned by Screen('OpenWindow'). * **wrect:** Window rectangle returned by Screen('OpenWindow'). * Return * :ref:`simplegazetracker-parameter-structure`. UpdateParameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab ret = SimpleGazeTracker('UpdateParameters',param); Update SimpleGazeTracker toolbox parameters. * Parameters * **param:** :ref:`simplegazetracker-parameter-structure`. * 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab ret = SimpleGazeTracker('Connect'); Open TCP/IP connection with SimpleGazeTracker. IP address and port of SimpleGazeTracker is specified by :ref:`simplegazetracker-parameter-structure`. * Parameters * No parameters. * Return * **0**: Succeeded. **-1**: Failed. CloseConnection ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab ret = SimpleGazeTracker('CloseDataFile'); Close data file on SimpleGazeTracker. * Parameters * No parameters. * Return * **0**: Command is successfully sent. **-1**: Failed. Calibration ----------- CalibrationLoop ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: matlab 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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block::matlab data = SimpleGazeTracker('ReadDataFile', filename) Read SimpleGazeTracker CSV file as an array of structure. * Parameters * **filename:** Name of SimpleGazeTracker data file.