eyetribe_API Reference

This document describes the communication protocol of The Eye Tribe Tracker known as the Tracker API.

Using the Tracker API requires a connected and correctly positioned Tracker Device and a running Tracker Server as explained in the Getting Started guide.

A connection must be established between a client implementation and the Tracker Server before messages can be exchanged using the Tracker API. Establishing such a connection involves opening a TCP Socket in your programming language of choice and connecting to localhost on port 6555. For a full source code example see Tutorials section.

The Tracker API protocol consists in the exchange of JSON formatted messages over TCP sockets. The Tracker API protocol is explained in the following.

Client Message

Request Message

The request message is a generic structure, which has three mandatory attributes:

  1. category: The query category. The different types of requests are grouped into different categories
  2. request: The actual request of the message. What constitutes a valid request depends on the category
  3. values: an JSON array of parameters or a JSON object depending on the request type

Conceptually, the categoryrequest and values can be thought of as class.method.value. From this, the the general JSON structure for the client request message is defined as:

{
    "category": string,
    "request" : string,
    "values" : [ … ] or { … }
}
Category TypeValues
tracker for SDK Tracker state and information related requests
calibration for calibration related requests
heartbeat for signalling heartbeats to the server
Response Message

The SDK Tracker reply message serves a dual purpose; firstly, for each request sent by the client, the tracker will provide the result of a request with reply message. Secondly, it serves as message publishing container for continuously published data, i.e. gaze data.

  1. category: the category of the incoming message. This allows the client to differentiate between replies for a request or published data
  2. request: type of the request
  3. statuscode: HTTP status code compliant integral value denoting the overall result of the request
  4. values: a JSON object of actual return values, if any

The valid categories for replies are:

Category TypeValues
tracker for SDK Tracker state and information related requests
calibration for calibration related requests
heartbeat for signalling heartbeats to the server

On error, the reply will hold suited statuscode and values object may contain:

  • statusmessage: string, an error description of why the request failed
  • [get/set value]: string, an error description of why get/set request failed

All requests related to the Tracker Server are specified with the category tracker.  This includes initial configuration requests to the tracker, once a client has connected to it, which consists of specifying desired frame rate, whether to push or pull and protocol version. 

The Tracker category support two generic requests:

  • get: read specified tracker values
  • set: write specified tracker values (if writable).
{
    "push": bool,
    "heartbeatinterval": int,
    "version":  int,
    "trackerstate": integer,
    "framerate": integer, 
    "iscalibrated": bool,
    "iscalibrating": bool,
    "calibresult": object
    "frame": string,
    "screenindex": int,
    "screenresw" : int,
    "screenresh" : int,
    "screenpsyw" : float,
    "screenpsyh" : float
}

Below is the meaning of each state item value dependent on whether it is get or set.

AttributesGetSet
push:booleanTracker server is running in push, or pull mode.Start tracker server in push mode
heartbeatinterval:integerThe expected interval in millisecond heartbeats are sent from clientN/A - immutable, defined by Tracker Server
version:integerThe protocol version currently used by the client
Defaults to latest version
 integer: The protocol version requested by the client
trackerstate:integerThe state of the physical tracker device, see Tracker State
N/A - immutable, defined by SDK Tracker
framerate:integerThe frame rate that the tracker is running atN/A - immutable, configured by user (config file)
iscalibrated:booleanIndicates if we have a calibrated tracker.N/A - immutable, state maintained by SDK
iscalibrating:booleanIndicates if we are in calibration state.N/A - immutable, state maintained by SDK
calibresult:objectLatest valid calibration result objectN/A - immutable, use for pull mode
frame:stringLatest frame data available, see Frame ObjectN/A - immutable, use for pull mode
screenindex:integerIndex of screen in multi screen setupIndex of current screen
screenresw:integerScreen resolution width in pixelsScreen resolution width in pixels
screenresh:integerScreen resolution height in pixelsScreen resolution height in pixels
screenpsyw:floatScreen physical width in metersScreen physical width in meters
screenpsyh:floatScreen physical height in metersScreen physical height in meters

Request get

Client needs to know if the server is running and the system is calibrated. This is done by submitting the following request:

{
    "category": "tracker",
    "request" : "get",
    "values": [ "push", "iscalibrated" ]
}

On success, the server replies:

{
    "category": "tracker",
    "request" : "get",
    "statuscode" : 200,
    "values": {
        "push" : true,
        "iscalibrated": true
    }
}

Note that a user calibration must be performed before any on-screen gaze coordinates are transmitted.

Request set

Client wants to start tracker. This is done submitting the following request:

{
    "category": "tracker",
    "request": "set",
    "values": {
        "push": true,
        "version": 1
    }
}

On successful request the server replies:

{
    "category": "tracker",
    "request": "set",
    "statuscode" : 200
}

If a request fails the server reply with a status code 500 and a message providing further information.

{
    "category": "tracker",
    "request": "set",
    "statuscode" : 500,
     "values": {
        "statusmessage" : "set failed, internal error"
    }
}

If a request fails the server reply with a status code 500 and a message providing further information.

{
    "category": "tracker",
    "request": "set",
    "values": {
        "push" : false,
        "version" : 1
    }
}

Request fails as  push is misspelled and provided version value is provided as string:

{
    "category": "tracker",
    "request": "set",
    "statuscode": 400,
    "values": {
        "statusmessage": "puss, not such value exists",
        "version": "only integers are supported"
    }
}

Tracker State

When requesting the tracker device connectivity state value trackerstate it returns an integer/enum with a value as described below:

StateDescriptionValue
TRACKER_CONNECTEDTracker device is detected and working0
TRACKER_NOT_CONNECTEDTracker device is not detected1
TRACKER_CONNECTED_BADFWTracker device is detected but not working due to wrong/unsupported firmware2
TRACKER_CONNECTED_NOUSB3Tracker device is detected but not working due to unsupported USB host3
TRACKER_CONNECTED_NOSTREAMTracker device is detected but not working due to no stream could be received4

Frame Object

When client connection to the SDK tracker has been established, the client will start receiving gaze data. The frame data is specified as:

{
    "category": "tracker",
    "statuscode": 200,
    "values": {
        "frame" : {
            "timestamp": string,      //string time representation e.g. '2014-04-15 15:28:46.628'
            "time": int,              //timestamp in milliseconds
            "fix": bool,              //is fixated?
            "state": int,             //32bit masked state integer
            "raw": {                  //raw gaze coordinates in pixels
                "x": int,
                "y": int
            },
            "avg": {                  //smoothed gaze coordinates in pix
                "x": int,
                "y": int
            },

            "lefteye": {
                "raw": {              //raw coordinates in pixels
                    "x": int,
                    "y": int
                },

                "avg": {              //smoothed coordinates in pix
                    "x": int,
                    "y": int
                },
                "psize": float,       //pupil size
                "pcenter": {          //pupil coordinates normalized
                    "x": float,
                    "y": float
                }
            },

            "righteye": {
                "raw": {             //raw coordinates in pixels
                    "x": int,
                    "y": int
                },
                "avg": {             //smoothed coordinates in pix
                    "x": int,
                    "y": int
                },
                "psize": float,     //pupil size
                "pcenter": {        //pupil coordinates normalized
                    "x": float,
                    "y": float
                }
            }
        }
    }
}

The state of the SDK Tracker is embedded in the "frame" object as the "state" value. The value is a masked integer and can hold several states at the same time. The state is extracted according to below table:

StateDescriptionValues
STATE_TRACKING_GAZETracker is calibrated and producing on-screen gaze coordinates. Eye control is enabled.Mask: (0x1) true: ((state & mask) != 0) false: ((state & mask) == 0)
STATE_TRACKING_EYESTracker possibly calibrated and is tracking both eyes, including pupil and glint.Mask: (0x2) true: ((state & mask) != 0) false: ((state & mask) == 0)
STATE_TRACKING_PRESENCETracker possibly calibrated and is tracking presence of user. Presence defined as face or single eye.Mask: (0x4) true: ((state & mask) != 0) false: ((state & mask) == 0)
STATE_TRACKING_FAILTracker failed to track anything in this frame.Mask: (0x8) true: ((state & mask) != 0) false: ((state & mask) == 0)
STATE_TRACKING_LOSTTracker has failed to detect anything and tracking is now lostMask: (0x10) true: ((state & mask) != 0) false: ((state & mask) == 0)

Pull mode

If tracker value "push" has been set to false, the client is expected to pull frame data. This is done by issuing the tracker-category request get with a value of frame:

{
    "category": "tracker",
    "request" : "get",
    "values": [ "frame" ]
}

Note that requesting a frame can be done at any time, even when running in push mode.

To calibrate the tracker a client perform a calibration process. The API requests involved in a calibration process are encapsulated in the calibration category and are described below.

Request start

The start request prepares the tracker for a new calibration.

{
    "category": "calibration",
    "request" : "start",
    "values": { "pointcount": integer }
}
Expected request value

pointcount: The number of calibration points the tracker needs to sample at to produce a valid calibration. The minimum number of calibration points allowed is 7, but it is recommended to use 9 or more.

Successful Tracker Server Response
{
    "category": "calibration",
    "request" : "start",
    "statuscode" : 200
}

Request pointstart

Mark the beginning of a new calibration point for the tracker to process.

Request Definition
{
    "category": "calibration",
    "request" : "pointstart",
    "values": { "x": integer, "y": integer }
}
Expected request values

x: x-coordinate of point y: y-coordinate of point

Successful Tracker Server Response
{
    "category": "calibration",
    "request" : "pointstart",
    "statuscode" : 200
}

Request pointend

Mark the end of processing a calibration point.

Request Definition
{
    "category": "calibration",
    "request" : "pointend"
}
Successful Tracker Server Response

After each endpoint-request the tracker will reply with:

{
    "category": "calibration",
    "request" : "pointend",
    "statuscode" : 200
}

For the final successful endpoint request the tracker will send back the calibration result. The data format of the calibresult is described further below.

{
    "category": "calibration",
    "request" : "pointend",
    "statuscode" : 200,
    "values": { "calibresult" : [ { … } ], … }
}

Request abort

At any point during the calibration an abort request may be sent to cancel an ongoing sequence. If the tracker have had a previous working calibration it will be reinstated.

Request Definition
{
    "category": "calibration",
    "request" : "abort"
}
Successful Tracker Server Response
{
    "category": "calibration",
    "request" : "abort",
    "statuscode": 200
}

Request clear

Removes the current calibration from the tracker.

Request Definition
{
    "category": "calibration",
    "request" : "clear"
}
Successful Tracker Server Response
{
    "category": "calibration",
    "request" : "clear",
    "statuscode" : 200
}

When the calibration process is completed, the last pointend request returns a calibresult object. This object is defined as:

{
    "result": bool,        // was the calibration successful?
    "deg": float,          // average error in degrees
    "degl": float,         // average error in degs, left eye
    "degr": float,         // average error in degs, right eye
    "calibpoints": [
        {
            "state": int,    //state of calibration point
            "cp": {              //coordinates in pixels
                "x": float,
                "y": float
            },
            "mecp": {            //mean estimated coords in pixels
                "x": float,
                "y": float
            },
            "acd": {             //accuracy in degrees
                "ad": float,
                "adl": float,    //left eye
                "adr": float     //right eye
            },
            "mepix": {           //mean error in pixels
                "mep": float,
                "mepl": float,   //left eye
                "mepr": float    //right eye
            },
            "asdp": {            //average std deviation in pixels
                "asd": float,
                "asdl": float,   //left eye
                "asdr": float    //right eye
            }
        },
        ...
    ]
}

The calibpoints array contains a complete list of the results from each calibration point. The state describes the status of each point. The values are defined as:

ValueDescriptionState
0No useful tracking data was gathered for the calibration point. The calibration point should be resampled.RS_NODATA
1The data gathered for the calibration point is of questionable quality. A resample can be beneficial.RS_RESAMPLE
2The calibration point is okay. No resample is required.RS_VALID

Once a client is connected to the tracker, it must send heartbeat requests to make itself known and prove that it is still alive. These heartbeats must be sent at a rate matching the heartbeatinterval value of the tracker category. The tracker will reply to each heartbeat allowing the client to recognize if connection have been lost.

Request heartbeat

Since no operation is performed within the heartbeat category no special requests are currently available.

Request Definition
{
    "category": "heartbeat"
}
Successful Tracker Server Response
{
    "category": "heartbeat",
    "statuscode": 200
}

Each reply from the tracker holds a status code. The status codes are compliant to standard HTTP status codes but The Eye Tribe SDK also define a few status codes of their own.

Tracker State ChangeThe state of the connected tracker device has changed. Connected clients should update themselves.802

TitleDescriptionValue
Calibration ChangeCalibration state has changed. Connected clients should update themselves.800
Display ChangeActive display index has changed in multi screen setup. Connected clients should update themselves.801
Tracker State ChangeThe state of the connected tracker device has changed. Connected clients should update themselves.802
  • 0
    点赞
  • 0
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
UE4_API_Reference 是一个非常宝贵的资源,它提供了 Unreal Engine 4 引擎的全部 API 详细文档。这些离线文档对开发者来说非常重要,因为它们可以在没有网络连接的情况下提供对 UE4 引擎的完整了解和查询支持。 UE4_API_Reference 全部离线文档包括了对 UE4 的各个模块、类、函数和属性的详细描述和用法示例。开发者可以通过这些文档深入了解各个功能模块的实现原理以及如何正确使用它们。这对于开发者学习 UE4 引擎以及进行游戏开发非常有帮助。 离线文档的好处在于可以在没有网络的环境中使用。开发者不需要依赖互联网来查找关于 UE4 API 的信息,而是可以直接在本地进行搜索和查询。这不仅提高了开发效率,还可以避免由于网络问题导致的信息获取困难。 UE4_API_Reference 全部离线文档的编制工作需要花费大量的时间和精力。文档中的每一个类、函数和属性都需要进行详细描述和示例演示,以便开发者能够更好地理解和使用。这就要求文档编写人员具备广泛的知识和丰富的经验,以确保文档的完整性和准确性。 总之,UE4_API_Reference 全部离线文档对于 UE4 开发者来说是一个非常宝贵的资源。它提供了对 UE4 引擎的全面了解和查询支持,可以帮助开发者更好地学习和使用 UE4 引擎进行游戏开发。同时,它也方便了开发者在没有网络连接的环境中进行开发工作,提高了开发效率。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值