Mirametrix Research

Application Programming Interface

Version 1.1 DRAFT Revised June 7, 2010

Mirametrix Research Inc.

309-2233 3rd Ave West

Vancouver, B.C.

V6K 1L5

1 (888) 698-6472

www.mirametrix.com

Copyright

Mirametrix Research Inc. All Rights Reserved.

Application Programming Interface

Table of Contents
1 2 Introduction Operation 4 4

2.1 2.2 2.3 2.4

3

Client / Server

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 4 4 4
5

TCP/IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Commands

3.1 3.2
4

SET

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 5
6

GET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Calibration

4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8

5

CALIBRATE_START . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIBRATE_SHOW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIBRATE_DELAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIBRATE_TIMEOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIBRATE_FAST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIB_START_PT and CALIB_RESULT_PT . . . . . . . . . . . . . . . . . . . . CALIB_RESULT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CALIB_RESULT_SUMMARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6 6 6 6 7 7 7 8
9

Tracker Program Control

5.1 5.2
6

TRACKER_EXIT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRACKER_DISPLAY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9 9
9

Remote Data

6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9

ENABLE_SEND_DATA ENABLE_SEND_TIME

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9 10 10 11 11 11 12 12 13 13 14 14 15 15 16 16 17 17 17 17 18 18 18

ENABLE_SEND_COUNTER

ENABLE_SEND_TIME_TICK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIME_TICK_FREQUENCY ENABLE_SEND_POG_LEFT ENABLE_SEND_POG_RIGHT ENABLE_SEND_POG_BEST

ENABLE_SEND_POG_FIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.10 ENABLE_SEND_PUPIL_LEFT 6.11 ENABLE_SEND_PUPIL_RIGHT

6.12 ENABLE_SEND_EYE_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.13 ENABLE_SEND_EYE_RIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.14 ENABLE_SEND_CURSOR 6.15 ENABLE_SEND_GPI 6.16 SCREEN_SIZE 6.18 TRACK_RECT 6.20 SERIAL_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.17 CAMERA_SIZE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.19 PRODUCT_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6.21 COMPANY_ID 6.23 API_SELECT

6.22 API_ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

2 of 19

Application Programming Interface

Updates from V1.0 to V1.1

18

7.1 7.2 7.3 7.4

March 26, 2010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . April 16, 2010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . May 18, 2010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . June 7, 2010 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

18 19 19 19

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

3 of 19

Application Programming Interface

Introduction

The Mirametrix eye-trackers conform to the Open Eye-gaze Interface, providing developers with the ability to add eye-gaze to custom applications. The Open Eye-gaze Interface provides a standardized method for performing calibration and acquiring eye-gaze information.

Operation

The Open Eye-gaze Interface is based on a web services model for data transmission. Communication is performed using a client / server architecture, passing XML strings over a TCP/IP connection.

2.1

Client / Server
The

The eye-gaze tracker operates as the server, responding to queries from a connected client.

server responds with an acknowledge once for each client command with the exception of calibration and free-running data transmission. When calibrating the server will transmit the results of the calibration procedure at each point as it takes place, while a continuous stream of eye-gaze information is transmit when free-running data transmission is enabled.

2.2

TCP/IP
Using TCP/IP allows the eye-tracker to

Communication takes place over a TCP/IP connection. network connection.

easily operate on a second computer with commands and data transmission taking place over a

2.3

XML
Using strings prevents the need for

All data structures take the form of XML string fragments. for managing and parsing the formatted data.

proprietary data structures, while the XML format provides an open and easily extensible method Client commands are either GET or SET operations where the XML tag is GET or SET.

2.4

Coordinates

All reported coordinates are in percentages of the tracking window (unless otherwise specied), which itself is in percentages of the screen size. By default the tracking window is 100% of the screensize and therefore only the screen size is required to convert from the reported X,Y coordinates to pixels. For X coordinates, 0 is the right most position and 1 is the left most position and for the Y coordinate 0 is the top most position and 1 is the bottom most position. For the pupil image coordinates the X,Y values are percentages of the camera image size.

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

4 of 19

Application Programming Interface

Commands

The eye-tracker is controlled using GET and SET commands in the form of XML fragments. A GET or SET command is always replied to with a successful (ACK) or unsuccessful response (NACK). The command may have any number of additional parameters and takes the form: SEND : < M C D ID="DATA_ID" PARAM1="VALUE" ... /> ... />

REPLY : < ACK ID="DATA_ID" REPLYPARAM1="VALUE"

3.1

SET

Description

The SET command is used to set variables within the eye-tracker and to initiate or cancel operations.

Example Usage

SEND : <SET ID=" ENABLE_SEND_COUNTER" STATE="0" /> REPLY : < ACK ID=" ENABLE_SEND_COUNTER" STATE="0" />

3.2

GET

Description

The GET command is used to get variables from the eye-tracker and to check on the state of an operation.

Example Usage

SEND : < GET ID=" ENABLE_SEND_COUNTER" /> REPLY : < ACK ID=" ENABLE_SEND_COUNTER" STATE="0" />

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

5 of 19

Application Programming Interface

4
4.1

Calibration
CALIBRATE_START

Description

Start or stop the calibration procedure.

DATA_ID CALIBRATE_START

Read/Write R/W

Parameters STATE

Type Boolean

Description Start or stop calibration procedure

Example Usage

SEND : < GET ID="CALIBRATE_START" /> REPLY : < ACK ID="CALIBRATE_START" STATE="0" /> SEND : <SET ID="CALIBRATE_START" STATE="1" /> REPLY : < ACK ID="CALIBRATE_START" STATE="1" />

4.2

CALIBRATE_SHOW

Description

Show or hide the calibration window.

DATA_ID CALIBRATE_SHOW

Read/Write R/W

Parameters STATE

Type Boolean

Description Show or hide the default calibration window

Example Usage

SEND : < GET ID="CALIBRATE_SHOW" /> REPLY : < ACK ID="CALIBRATE_SHOW" STATE="0" /> SEND : <SET ID="CALIBRATE_SHOW" STATE="1" /> REPLY : < ACK ID="CALIBRATE_SHOW" STATE="1" />

4.3

CALIBRATE_DELAY

Description

Set the delay before a calibration point in started seconds, which provides time for calibration point animation. DATA_ID CALIBRATE_DELAY Read/Write R/W Parameters VALUE Type oat Description Calibration point delay

Example Usage

SEND : < GET ID="CALIBRATE_DELAY" /> REPLY : < ACK ID="CALIBRATE_DELAY" VALUE= " 0 . 5 0 " /> SEND : <SET ID="CALIBRATE_DELAY" VALUE="1" /> REPLY : < ACK ID="CALIBRATE_DELAY" VALUE= " 1 . 0 0 " />

4.4

CALIBRATE_TIMEOUT

Description

Set the maximum duration of a calibration point in seconds after the calibration delay.

DATA_ID CALIBRATE_TIMEOUT

Read/Write R/W

Parameters VALUE

Type oat

Description Maximum duration of calibration point

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

6 of 19

Application Programming Interface

Example Usage

SEND : < GET ID="CALIBRATE_TIMEOUT" /> REPLY : < ACK ID="CALIBRATE_TIMEOUT" VALUE= " 4 . 0 0 " /> SEND : <SET ID="CALIBRATE_TIMEOUT" VALUE="3" /> REPLY : < ACK ID="CALIBRATE_TIMEOUT" VALUE= " 3 . 0 0 " />

4.5

CALIBRATE_F AST

Description

If enabled the calibration will jump to the next point as soon as sucient data has been collected at the current calibration point, rather than waiting until the completion of the CALIBRATE_TIMEOUT value. DATA_ID CALIBRATE_FAST Read/Write R/W Parameters STATE Type int Description Enable fast calibration

Example Usage

SEND : < GET ID="CALIBRATE_FAST" /> REPLY : < ACK ID="CALIBRATE_FAST" STATE="1" /> SEND : <SET ID="CALIBRATE_FAST" STATE="0" /> REPLY : < ACK ID="CALIBRATE_FAST" STATE="0" />

4.6

CALIB_START_PT and CALIB_RESULT_PT

While calibrating, information about the status of each calibration point is transmit. At the start of each calibration point, the CALIB_START_PT record is sent along with the X and Y coordinates of the target point. After the completion the calibration point the CALIB_RESULT_PT record is sent, immediately followed by the subsequent CALIB_START_PT record for the next calibration point. Data ID CALIB_START_PT CALIB_START_PT CALIB_START_PT CALIB_RESULT_PT CALIB_RESULT_PT CALIB_RESULT_PT Param PT CALX CALY PT CALX CALY Type int oat oat int oat oat Description Calibration point started Calibration X coordinate for PT Calibration Y coordinate for PT Calibration point completed Calibration X coordinate for PT Calibration Y coordinate for PT

Example Result

< CAL ID="CALIB_START_PT" PT="1" CALX= " 0 . 1 0 0 0 0 " CALY= " 0 . 0 8 0 0 0 " /> < CAL ID="CALIB_RESULT_PT" PT="1" CALX= " 0 . 1 0 0 0 0 " CALY= " 0 . 0 8 0 0 0 " />

4.7

CALIB_RESULT

When the calibration procedure completes, the results for each point are collected in an XML string and transmit. An example of the calibration return data is shown below for a single point.

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

7 of 19

Application Programming Interface

Data ID CALIB_RESULT CALIB_RESULT CALIB_RESULT CALIB_RESULT CALIB_RESULT CALIB_RESULT CALIB_RESULT CALIB_RESULT

Param CALX? CALY? LX? LY? LV? RX? RY? RV?

Type oat oat oat oat int oat oat int

Description Calibration X coordinate for point ? Calibration X coordinate for point ? Left eye point-of-gaze X for point ? Left eye point-of-gaze Y for point ? Left eye valid ag for point ? Right eye point-of-gaze X for point ? Right eye point-of-gaze Y for point ? Right eye valid ag for point ?

Example Result

< CAL ID="CALIB_RESULT" CALX1= " 0 . 1 0 0 0 0 " CALY1= " 0 . 0 8 0 0 0 " LY1 = " 0 . 0 7 4 2 0 "

LX1 = " 0 . 0 9 2 0 0 " ... />

LV1="1" RX1= " 0 . 1 2 6 7 9 " RY1= " 0 . 1 3 6 1 9 " RV1="1"

4.8

CALIB_RESULT_SUMMARY

When the calibration procedure completes, a summary of the results can be queried using the CALIB_RESULT_SUMMARY identier.

Data ID CALIB_RESULT_SUMMARY CALIB_RESULT_SUMMARY

Param AVE_ERROR VALID_POINTS

Type oat int

Description Average error in pixels over all calibration points Number of calibration points with valid data

Example Result

< GET ID="CALIBRATE_RESULT_SUMMARY" /> < ACK ID="CALIBRATE_RESULT_SUMMARY" AVE_ERROR= " 2 6 . 4 4 " VALID_POINTS="9" />

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

8 of 19

Application Programming Interface

Tracker Program Control

Options for the control of the Tracker program through the API.

5.1

TRACKER_EXIT

Description

Command the Tracker program to exit. DATA_ID TRACKER_EXIT Read/Write R/W Parameters STATE Type Boolean Description Exit the Tracker program

Example Usage

SEND : < GET ID="TRACKER_EXIT" /> REPLY : < ACK ID="TRACKER_EXIT" STATE="0" /> SEND : <SET ID="TRACKER_EXIT" STATE="1" /> REPLY : < ACK ID="TRACKER_EXIT" STATE="1" />

5.2

TRACKER_DISPLAY

Description

Set the Tracker program to show or hide the user display image.

DATA_ID TRACKER_DISPLAY

Read/Write R/W

Parameters STATE

Type Boolean

Description Show/Hide the Tracker display image

Example Usage

SEND : < GET ID="TRACKER_DISPLAY" /> REPLY : < ACK ID="TRACKER_DISPLAY" STATE="0" /> SEND : <SET ID="TRACKER_DISPLAY" STATE="1" /> REPLY : < ACK ID="TRACKER_DISPLAY" STATE="1" />

Remote Data

The GET and SET commands operate on the remote data specied by the DATA_ID identier, along with optional parameters.

6.1

ENABLE_SEND_DATA

Description

Enable or disable the sending of the eye-gaze data records. Enabling this variable begins the continuous sending of the eye-gaze data records.

DATA_ID ENABLE_SEND_DATA

Read/Write R/W

Parameters STATE

Type Boolean

Description Start or stop data streaming

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

9 of 19

Application Programming Interface

Example Usage

SEND : < GET ID=" ENABLE_SEND_DATA" /> REPLY : < ACK ID=" ENABLE_SEND_DATA" STATE="0" /> SEND : <SET ID=" ENABLE_SEND_DATA" STATE="1" /> REPLY : < ACK ID=" ENABLE_SEND_DATA" STATE="1" />
Data Record

If enabled the data record will be continuously transmit. If no other parameters are enabled the result will look like: < REC /> < REC /> ...

6.2

ENABLE_SEND_COUNTER

Description

Enable or disable the sending of the packet counter. The packet counter is incremented each time a packet is sent from the server. The packet counter provides a means for determining if packets are being lost. DATA_ID ENABLE_SEND_COUNTER Read/Write R/W Parameters STATE Type Boolean Description Enable counter data

Data Record

The counter is identied in the data record as follows: Param CNT Type integer Description Sequence counter for data packets

Example Data Record

< REC CNT="1"/> < REC CNT="2"/> ...

6.3

ENABLE_SEND_TIME

Description

Enable or disable the elapsed time variable. The elapsed time variable identies the elapsed time since the last calibration. DATA_ID ENABLE_SEND_TIME Read/Write R/W Parameters STATE Type Boolean Description Enable time stamp data

Data Record

The elapsed time is identied in the data record as follows: Param TIME Type oat Description Elapsed time in seconds since last system initialization or calibration

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

10 of 19

Application Programming Interface

Example Data Record

< REC TIME="1141.437"/ > < REC TIME="1141.453"/ > ...

6.4

ENABLE_SEND_TIME_TICK

Description

Enable or disable the high resolution timer tick. The high resolution timer tick returns the output of the QueryPerformanceCounter (Win32 API) function and can be used to synchronize eye-gaze with other data recorded on the same computer. To convert to seconds divide this value by the output of the TIME_TICK_FREQUENCY variable.

DATA_ID ENABLE_SEND_TIME_TICK

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable high resolution timer tick

Data Record

The elapsed time is identied in the data record as follows: Param TIME_TICK Type LONGLONG Description Tick count (signed 64-bit integer)

Example Data Record

< REC TIME_TICK="5712427212840"/ > < REC TIME_TICK="5712464779821"/ > ...

6.5

TIME_TICK_FREQUENCY

Description

Get the timer tick frequency for high resolution timing. This returns the output of QueryPerformanceFrequency in the Win32 API.

DATA_ID TIME_TICK_FREQUENCY

Read/Write R

Parameters FREQ

Type LONGLONG

Description Tick frequency (signed 64-bit integer)

Example Usage

SEND : < GET ID="TIME_TICK_FREQUENCY" /> REPLY : < ACK ID="TIME_TICK_FREQUENCY" FREQ= " 2 4 0 5 4 8 0 0 0 0 " />

6.6

ENABLE_SEND_POG_LEFT

Description

Enable or disable the sending of the point-of-gaze data from the left eye.

DATA_ID ENABLE_SEND_POG_LEFT

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable left eye point-of-gaze data

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

11 of 19

Application Programming Interface

Data Record

The left eye point of gaze is identied in the data record as follows: Param LPOGX LPOGY LPOGV Type oat oat int Description Left point-of-gaze X Left point-of-gaze Y Left point-of-gaze valid ag

Example Data Record

< REC LPOGX= " 0 . 2 1 7 2 6 " LPOGY= " 0 . 3 5 5 2 4 " LPOGV="1"/> < REC LPOGX= " 0 . 1 5 7 7 4 " LPOGY= " 0 . 3 7 0 4 8 " LPOGV="1"/> ...

6.7

ENABLE_SEND_POG_RIGHT

Description

Enable or disable the sending of the point-of-gaze data from the right eye.

DATA_ID ENABLE_SEND_POG_RIGHT

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable right eye point-of-gaze data

Data Record

The right eye point of gaze is identied in the data record as follows: Param RPOGX RPOGY RPOGV Type oat oat int Description Right point-of-gaze X Right point-of-gaze Y Right point-of-gaze valid ag

Example Data Record

< REC RPOGX= " 0 . 1 1 6 6 7 " RPOGY= " 0 . 3 9 3 3 3 " RPOGV="1"/> < REC RPOGX= " 0 . 1 1 1 3 1 " RPOGY= " 0 . 4 8 8 5 7 " RPOGV="1"/> ...

6.8

ENABLE_SEND_POG_BEST

Description

Enable or disable the sending of the best point-of-gaze data. The best POG is simply the average of the left and right POG estimates if both the left and right estimates are valid. If either the left or right POG is invalid, then the best POG is equal to the remaining valid POG.

DATA_ID ENABLE_SEND_POG_BEST

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable best eye point-of-gaze data

Data Record

The best point of gaze is identied in the data record as follows: Param BPOGX BPOGY BPOGV Type oat oat int Description Best point-of-gaze X Best point-of-gaze Y Best point-of-gaze valid ag

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

12 of 19

Application Programming Interface

Example Data Record

< REC BPOGX= " 0 . 4 4 2 1 5 " BPOGY= " 0 . 6 2 1 4 4 " BPOGV="1"/> < REC BPOGX= " 0 . 4 4 3 1 4 " BPOGY= " 0 . 4 2 3 6 4 " BPOGV="1"/> ...

6.9

ENABLE_SEND_POG_FIX

Description

Enable or disable the sending of the xation point-of-gaze data.

DATA_ID ENABLE_SEND_POG_FIX

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable xation point-of-gaze data

Data Record

The xation point of gaze is identied in the data record as follows: Param FPOGX FPOGY FPOGS FPOGD FPOGID FPOGV Type oat oat oat oat int int Description Fixation point-of-gaze X Fixation point-of-gaze Y Fixation start (seconds) Fixation duration (elapsed time since xation start (seconds)) Fixation number ID Fixation point-of-gaze valid ag

Example Data Record

< REC FPOGX= " 0 . 4 0 5 9 5 " FPOGY= " 0 . 7 8 7 6 2 " FPOGS= " 0 . 5 1 2 " FPOGD= " 0 . 3 2 0 " FPOGID="2" FPOGV="1"/> < REC FPOGX= " 0 . 4 0 2 7 4 " FPOGY= " 0 . 8 0 0 4 8 " FPOGS= " 0 . 5 1 2 " FPOGD= " 0 . 3 3 6 " FPOGID="2" FPOGV="1"/> ...

6.10

ENABLE_SEND_PUPIL_LEFT

Description

Enable or disable the sending of the left pupil image data.

DATA_ID ENABLE_SEND_PUPIL_LEFT

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable left eye image data

Data Record

The pupil image data is identied in the data record as follows: Param LPCX LPCY LPD LPS LPV Type oat oat oat oat int Description Left eye pupil center X Left eye pupil center Y Left eye pupil diameter (pixels) Left eye pupil distance (unit less, from calibration position) Left eye pupil image valid

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

13 of 19

Application Programming Interface

Example Data Record

< REC LPCX= " 0 . 0 9 9 7 3 " LPCY= " 0 . 2 0 0 0 0 " LPD= " 1 6 . 3 0 " < REC LPCX= " 0 . 0 9 9 7 3 " LPCY= " 0 . 1 9 3 7 5 " LPD= " 1 6 . 2 0 " ...

LPS= " 0 . 7 7 " LPV="1"/> LPS= " 0 . 7 7 " LPV="1"/>

6.11

ENABLE_SEND_PUPIL_RIGHT

Description

Enable or disable the sending of the right pupil image data.

DATA_ID ENABLE_SEND_PUPIL_RIGHT

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable right eye image data

Data Record

The pupil image data is identied in the data record as follows: Param RPCX RPCY RPD RPS RPV Type oat oat oat oat int Description Right eye pupil center X Right eye pupil center Y Right eye pupil diameter (pixels) Right eye pupil distance (unit less, from calibration position) Right eye pupil image valid

Example Data Record

< REC RPCX= " 0 . 4 7 4 7 3 " RPCY= " 0 . 1 7 9 1 7 " RPD= " 1 4 . 9 0 " RPS= " 1 . 5 5 " RPV="1"/> < REC RPCX= " 0 . 4 7 0 7 4 " RPCY= " 0 . 1 7 9 1 7 " RPD= " 1 4 . 8 2 " RPS= " 1 . 5 5 " RPV="1"/> ...

6.12

ENABLE_SEND_EYE_LEFT

Description

Enable or disable the sending of the left eye data. DATA_ID ENABLE_SEND_EYE_LEFT Read/Write R/W Parameters STATE Type Boolean Description Enable left eye data

Data Record

The eye data is identied in the data record as follows: Param LEYEX LEYEY LEYEZ LEYEV LPUPILD LPUPILV Type oat oat oat int oat int Description Left eye position in X -left/+right (cm) Left eye position in Y -down/+up (cm) Left eye position in Z -away/+toward (cm) Left eye data valid Left eye pupil diameter (mm) Left pupil data valid 0 - Invalid pupil data 1 - Valid pupil data 2 - Valid pupil data, but old position data

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

14 of 19

Application Programming Interface

Example Data Record

<REC LEYEX=" 5.295" LEYEY=" 2.031" LEYEZ="62.116" LEYEV="1" LPUPILD="3.586" LPUPILV="1"/> <REC LEYEX=" 5.282" LEYEY=" 2.032" LEYEZ="62.247" LEYEV="1" LPUPILD="3.570" LPUPILV="1"/> ...
6.13 ENABLE_SEND_EYE_RIGHT

Description

Enable or disable the sending of the right eye data.

DATA_ID ENABLE_SEND_EYE_RIGHT

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable right eye data

Data Record

The eye data is identied in the data record as follows: Param REYEX REYEY REYEZ REYEV RPUPILD RPUPILV Type oat oat oat int oat int Description Right eye position in X -left/+right (cm) Right eye position in Y -down/+up (cm) Right eye position in Z -away/+toward (cm) Right eye data valid Right eye pupil diameter (mm) Right pupil data valid 0 - Invalid pupil data 1 - Valid pupil data 2 - Valid pupil data, but old position data

Example Data Record

<REC REYEX="1.349" REYEY=" 1.988" REYEZ="64.328" REYEV="1" RPUPILD="3.449" RPUPILV="1"/> <REC REYEX="1.327" REYEY=" 1.978" REYEZ="63.613" REYEV="1" RPUPILD="3.400" RPUPILV="1"/> ...
6.14 ENABLE_SEND_CURSOR

Description

Enable or disable the sending of the right mouse cursor position.

DATA_ID ENABLE_SEND_CURSOR

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable mouse cursor data

Data Record

The mouse cursor data is identied in the data record as follows:

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

15 of 19

Application Programming Interface

Param CX CY CS

Type oat oat int

Description Cursor X position Cursor Y position Cursor button state 0 - No press 1 - Left button down 2 - Left button up 3 - Left double click 4 - Right button down 5 - Right button up 6 - Right double click

Example Data Record

< REC CX= " 0 . 1 2 3 2 1 " CY= " 0 . 3 2 5 7 1 " CS="0"/> < REC CX= " 0 . 1 2 6 1 9 " CY= " 0 . 3 6 2 8 6 " CS="0"/> ...

6.15

ENABLE_SEND_GPI

Description

Enable or disable the sending of up to 10 general purpose input data values which can be used to set user dened values in the eye-gaze data stream. For example, if various stimulus are being displayed, the stimulus ID could be saved into one of the GPI values.

DATA_ID ENABLE_SEND_GPI

Read/Write R/W

Parameters STATE

Type Boolean

Description Enable general purpose input data

The number of general purpose input data values is set with the GPI_NUMBER parameter.

DATA_ID GPI_NUMBER

Read/Write R/W

Parameters VALUE

Type int

Description Set the number of general input data variables (0 to 10)

Data Record

The general purpose input data is identied in the data record as follows: Param GPI? Type String Description GPI? value (where ? is 1 to 10)

Example Data Record

< REC GPI1="IMG1" /> < REC GPI1="IMG1" /> < REC GPI1="IMG1" /> ...

6.16

SCREEN_SIZE

Description

Get the size of the screen in pixels. DATA_ID SCREEN_SIZE Read/Write R/W R/W Parameters WIDTH HEIGHT Type int int Description Screen width (pixels) Screen height (pixels)

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

16 of 19

Application Programming Interface

Example Usage

SEND : < GET ID="SCREEN_SIZE" /> REPLY : < ACK ID="SCREEN_SIZE" WIDTH="1680" HEIGHT="1050" />

6.17

CAMERA_SIZE

Description

Get the size of the camera image in pixels. DATA_ID CAMERA_SIZE Read/Write R R Parameters WIDTH HEIGHT Type int int Description Camera image width (pixels) Camera image height (pixels)

Example Usage

SEND : < GET ID="CAMERA_SIZE" /> REPLY : < ACK ID="CAMERA_SIZE" WIDTH="752" HEIGHT="480" />

6.18

TRACK_RECT

Description

Get the size of the position and size of the tracking rectangle. DATA_ID Read/Write R TRACK_RECT R R R Parameters X Y WIDTH HEIGHT Type oat oat oat oat Description X coordinate of tracking rectangle Y coordinate of tracking rectangle Width of tracking rectangle Height of tracking rectangle

Example Usage

SEND : < GET ID=" TRACK_RECT" /> REPLY : < ACK ID=" TRACK_RECT" X= " 0 . 0 0 0 0 " Y= " 0 . 0 0 0 0 " WIDTH= " 1 . 0 0 0 0 " HEIGHT= " 1 . 0 0 0 0 " />

6.19

PRODUCT_ID

Description

Product identier. DATA_ID PRODUCT_ID Read/Write R Parameters VALUE Type string Description Product identier

Example Usage

SEND : < GET ID="PRODUCT_ID" /> REPLY : < ACK ID="PRODUCT_ID" VALUE="S1 " />

6.20

SERIAL_ID

Description

Product serial number. DATA_ID SERIAL_ID Read/Write R Parameters VALUE Type string Description Device serial number

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

17 of 19

Application Programming Interface

Example Usage

SEND : < GET ID="SERIAL_ID" /> REPLY : < ACK ID="SERIAL_ID" VALUE= " 5 7 0 6 3 1 4 5 4 " />

6.21

COMPANY_ID

Description

Manufacturer identier. DATA_ID MFG_ID Read/Write R Parameters VALUE Type string Description Manufacturer identity

Example Usage

SEND : < GET ID=" COMPANY_ID" /> REPLY : < ACK ID=" COMPANY_ID" VALUE=" M i r a m e t r i x Research Inc ." />

6.22

API_ID

Description

API identity. DATA_ID API_ID Read/Write R Parameters MFG_ID VER_ID Type string string Description API vendor identity API version number

Example Usage

SEND : < GET ID="API_ID" /> REPLY : < ACK ID="API_ID" MFG_ID=" M i r a m e t r i x " VER_ID= " 1 . 0 " />

6.23

API_SELECT

Description

Select the API to use for further communication. DATA_ID API_SELECT Read/Write R R W Parameters MFG_ID? VER_ID? STATE Type string string int Description List of vendors supported List of versions supported API selected

Example Usage

SEND : < GET ID="API_SELECT" /> REPLY : < ACK ID="API_SELECT" MFG_ID0=" g e n e r i c " VER_ID0= " 1 . 0 " MFG_ID1=" M i r a m e t r i x " VER_ID1= " 1 . 0 " /> SEND : <SET ID="API_SELECT" STATE="1" /> REPLY : < ACK ID="API_SELECT" STATE="1" />

7
7.1

Updates from V1.0 to V1.1

March 26, 2010
Modied SCREEN_SIZE from READ ONLY to Read and Writable which allows for remote operation with dierent screen sizes.

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

18 of 19

Application Programming Interface

Added ENABLE_SEND_POG_BEST, which is equivalent to the average of the left and right POG if both are available, or equal to the left or right POG if only one is available.

7.2

April 16, 2010

Added ENABLE_SEND_EYE_RIGHT, and ENABLE_SEND_EYE_LEFT which provides the position of the eyes in 3D space. millimeters for use in pupillometry. This allows the pupil to be determined in units of

7.3

May 18, 2010

Added TRACKER_EXIT command to allow the API to cause the tracker program terminate. Added TRACKER_DISPLAY command to allow the API to control the diagnostic display window.

Added ENABLE_SEND_GPI, GPI_NUMBER and GPI? to allow user dened entries into the eye-gaze data stream. Added CALIBRATE_TIMEOUT, CALIBRATE_DELAY, CALIBRATE_FAST, to allow basic customization of the calibration routine.

7.4

June 7, 2010
Added CALIBRATE_RESULT_SUMMARY command to determine the quality of the last calibration.

Copyright

2010 Mirametrix Research Inc. All Rights Reserved.

19 of 19