An Open API for Gaze-Point Estimation
Systems
This API targets to unify the communication protocol between a software that estimates gaze-point on a certain
plane (usually, a screen) and an application with a (graphical) user interface. The first communication side is further
called as “system”, and the second as “application”. There is a third side involved in this communication acting as a
middle ware between systems and apps, called in this documentation as “system browser”: it is a helping tool that
provides an information about the accessible systems.
In addition, the API supports a definition a module that not only consumes data from a system (i.e., acts as a usual
application), but also generates a new data available for other applications and modules, and usually has no user
interface. These modules are visible for applications like simplified systems. A system browser provides for
applications a list of available modules.
Therefore, the description of the API consists of three major parts: 1) API for systems, 2) API for modules, and 3) API
for browsers. The communication protocol uses JSON notation.
Contents
Code notation .................................................................................................................................................................. 3
Requests ........................................................................................................................................................................... 5
info ............................................................................................................................................................................... 7
state ............................................................................................................................................................................. 7
settings ......................................................................................................................................................................... 7
timestamp .................................................................................................................................................................... 8
initialize ........................................................................................................................................................................ 9
display .......................................................................................................................................................................... 9
hide ............................................................................................................................................................................ 10
trigger ......................................................................................................................................................................... 10
calibrate ..................................................................................................................................................................... 10
calibration .................................................................................................................................................................. 11
layers .......................................................................................................................................................................... 11
layer............................................................................................................................................................................ 11
Events ............................................................................................................................................................................. 13
state ........................................................................................................................................................................... 13
data ............................................................................................................................................................................ 13
Protocol
Notation
Generally, the protocol notation corresponds to the JSON code notation. However, keys are show in JS notation
(without quotation marks) to separate them visually from values.
Text between “<” and “>” denotes “any valid value”. Brackets “[ ]” denote that the key/value is optional. Note that
“[...]” denotes a JSON array.
Keys or values separated by the vertical line “|” are the exclusive alternatives (only one is allowed). Keys or values
separated by two vertical lines “||” are the non-exclusive alternatives (at least one must be used). Keys and values
in parenthesis “( )” are grouped logically; a group is usually used together with alternatives.
Sometimes, only a part of the JSON object is displayed. For example, an answer to the “state” request may be
described as
“available” | “calibrating” | “ready” | “tracking”
meaning that the full answer is
{
request: “state”,
from: <id>,
answer: “available” | “calibrating” | “ready” | “tracking”
}
Sometimes, only keys are listed and values are omitted. For example, a system’s answer may be described as
name, version, company || author [, description]
meaning that the full answer is
{
request: “info”,
from: <id>,
answer: {
name: <name>,
version: <version>,
company: <company> || author: <author>,
description: <description>
}
}
Format
Requests
{
request: <request>,
[, to: <id>]
[, parameters: <value> | { ... } | [ ... ] ]
}
Requests describe commands flowing from clients to servers. The key request is the only compulsory key that
describes the request. The key to identifies the system or plugin that this request is addressed to. If omitted
or empty, it addresses the system browser. The key parameters contains any necessary parameters of a
particular request.
Answers
{
request: <request>,
( answer: <value> | { ... } | [ ... ] ) | error: <description>
[, from: <id>]
}
Answers describe data or operation result requested by clients flowing back to them from servers in response
to requests. The key request identifies the request that this answer corresponds to. The key from identifies
the system or plugin that issued this answer. If omitted or empty, the source of the answer is the system
browser. The key answer contains the actual answer. If the request has failed or it is not supported, then this
key is replaces by the error that contains the description of error.
Events
{
event: <event>
content: <data> | { ... } | [ ... ]
[, from: <id>]
}
Events described data flowing to clients from servers without an explicit request. The key event identifies the
event. The key from identifies the system or plugin that fired this event. If omitted or empty, the source of
the event is the system browser. The key content contains the event’s data.
Common objects
Setting
Format
{
name, value, default, readonly
[, description]
( [, units] [ ( [, min] [, max] [, step] ) | list: [...] ] ) |
[, settings]
}
Description
The keys name, value, default (value) and readonly (flag) are the compulsory keys. The key description is a
short string that is suitable to display next to the control in a client application where the setting can be
edited. If it is omitted, then the name can be used for this purpose.
The optional units key indicates measurement units of the setting (eg., ms, mm, °). Other optional keys (min,
max, step and list) help to describe the range or list of the valid values of the given setting.
If the setting has the settings key (i.e., it is a container for other settings) then only the keys name and
description are allowed. The key settings is an array of Setting objects.
Data
Format
{
name,
[, description]
[ ( [, units] ( [, min] [, max] ) | list: [...] ] ) | data: [...] ) ]
}
Description
The object describes a single layer value, or a container for values. The key name is the only compulsory key.
The key description is a short string that is suitable to display (if it is omitted, then the name can be used for
this purpose).
The optional units key indicates measurement units (eg., “ms”, “mm”, “px”, “°”). Three other optional keys
(min, max and list) help to describe the range or list of the valid values of the given data.
If the setting has the data key (i.e., it is a container for other data) then only the keys name and description
are allowed. The key data is an array of Data objects.
Quality
Format
{
overall
}
Description
This object is a matter of the COGAIN calibration quality standard. Before it is officially published, it contain
the only key overall, a number between 0 and 1 describing the overall quality, where 0 means failed
calibration and 1 means absolutely perfect calibration.
Layer
Format
{
name, description, enabled,
data: [...]
[, settings: [...] ]
[, parameters: {...} ]
}
Description
All keys are compulsory. The key data is an array of Data objects, the key settings is an array of Setting
objects, and the key parameters is an array of named values that describe the layer parameters created
dynamically:
[
[<name1>: <value1>
[, <name2>: <value2>
[, ... ] ] ]
]
Notes
Each system must implement at least the following layer:
{
name: “basic”,
description: “Basic gaze point on screen”,
enabled: <enabled>,
data: [
{ name: “timestamp”, description: “Timestamp”, units: “s” },
{ name: “x”, description: “Gaze X on screen”, units: “px” },
{ name: “y”, description: “Gaze Y on screen”, units: “px” },
]
}
Requests to GPE systems
info
Gets information about the system
Parameters
Answers
name, version, company || author [, description]
state
Gets the system state
Parameters
Answers
“unavailable” | “available” | “calibrating” | “ready” | “active”
 unavailable – the system was not initialized (not ready to start calibration)
 available – the system initialized but not calibrated yet
 calibrating – the system is running the calibration routine (unmapped data may be delivered to clients)
 ready – the system is calibrated and is ready to deliver data (data is not delivering)
 active – data is delivering to clients
settings
Gets the system settings
Parameters
- | [ ... ]
 No parameters – return all system’s settings (array of top-level Setting objects).
 All or a subset of settings that a system’s answer contains in response to the request for settings with no
parameters. Only the key value (except for containers) is required to pass. The request must keep the
correct hierarchy of each setting. For example, if the answer to the request settings with no parameters
contains
{
request: “settings”,
from: “{593817A0-7DB4-11CF-A2DE-1DAA00B93456}”,
answer: [ {
name: “calibration”,
description: “Calibration”,
settings: [ {
name: “points”,
value: 5,
default: 9,
description: “Number of points”,
list: [2, 5, 9, 20]
}, {
name: “speed”,
value: “normal”,
default: “normal”,
description: “Point moving speed”,
list: [“slow”, “normal”, “fast”]
} ]
} ]
}
and the client application needs to set a new calibration point moving speed, then the request should be as
follows:
{
request: “settings”,
to: “{593817A0-7DB4-11CF-A2DE-1DAA00B93456}”,
parameters: [ {
name: “calibration”,
settings: [ {
name: “speed”,
value: “fast”
} ]
} ]
}
Answers
 For the request with no parameters: all system’s settings, an array of the Setting objects
 For the request with parameters: a subset of the passed settings (with the corrected (current) values)
that were not accepted. For example, if the client tried to set the calibration point speed to “7”, and this
value is not valid, then the answer could be as follows:
{
request: “settings”,
from: “{593817A0-7DB4-11CF-A2DE-1DAA00B93456}”,
answer: [ {
name: “calibration”,
settings: [ {
name: “points”,
value: 5
} ]
} ]
}
If all passed settings were accepted, it contains an empty array in the answer.
timestamp
Gets the timestamp from a system (in seconds)
Parameters
-
Answers
<timestamp>
Timestamp in seconds
initialize
Initializes a system
Parameters
Any parameters required for initialization. See the documentation for each system for the list of such
parameters.
Answers
“”
A description of the error if the request failed, or an empty string if succeeded.
display
Displays a window with the system settings, camera view, or calibration results
Parameters
- | [ ... ] | “camera” | “calibration”
 No parameters or empty array to shows all settings.
 Array of names of settings - the settings that must be displayed. Only names of the top-level containers
and settings can be listed in this array.
 camera – a window with any video stream that shows either captured or drawn eyes.
 calibration – a window with the current calibration results.
Note that some names of the top containers of settings may also be named as calibration and camera,
therefore it is important to discriminate requests via using or not an array notation. For example, the request
{
request: “display”,
to: “{593817A0-7DB4-11CF-A2DE-1DAA00B93456}”,
parameters: [“calibration”]
}
may result in displaying a window with calibration settings, whereas the request
{
request: “display”,
to: “{593817A0-7DB4-11CF-A2DE-1DAA00B93456}”,
parameters: “calibration”
}
may result in displaying a window with calibration result.
Answers
[ ... ] | <window>


For the request to show settings: this is an array of names of a subset of settings that are visible (could
contain settings that were visible already before this request).
For the request to show other windows: this is a value that was passed as a parameter with the request,
if the corresponding window is visible. If the request has failed, the return answer is an empty string.
hide
Hides a window with the system setting, camera view, or calibration results, if they are visible.
Parameters
- | [ ... ] | “camera” | “calibration”
Allowed parameters:





No parameters to hide all visible windows.
Empty array to hide the window with settings.
List of names of settings to hide them. Only names of the top-level containers and settings can be listed
in this array.
camera – hides a window with any video stream that shows either captured or drawn eyes
calibration – hides a window with the current calibration results
Answers
[ ... ] | <value>
 For the request to hide settings: this is an array of names of a subset of settings that remained visible.
 For the request to hide other windows: this is a value that was passed as a parameter with the request,
if the corresponding window is visible.
trigger
Triggers data streaming to the clients
Parameters
Answers
“”
A description of error if the request failed, or an empty answer otherwise
calibrate
starts the calibration routine
Parameters
 No parameters – uses the default calibration routine
 An object that describes a custom calibration routine. To be standardized in future.
Answers
<quality>
A description of error if the calibration has failed or aborted, otherwise the Quality object.
calibration
Manages meta-data of the calibrations
Parameters
operation [, name]
Operation can be one of the following:





save – saves the current calibration as name
load – loads the calibration named as name
delete – deletes the calibration named as name
get – gets an array of all saved calibrations
quality – gets a quality of the calibration name, or of the current calibration if name is omitted
Answers
[ ... ] | <quality>
Return an array of available calibrations for the operation get, the Quality object for the operation quality, or
an error if the request failed (usually, “the calibration with the given name exists already” for saving
operation, or “no such calibration” for other operations), otherwise an empty string.
layers
Gets the list of available data layers, or sets the active layers
Parameters
- | [ ... ]
 No parameters – the answer contains a list of all available data layers
 A list of names of layers that must generate data. Other layers will be deactivated.
Answers
[ ... ]
 For the request with no options: an array of Layer objects.
 For requests with a list of layers to activate: a list of names of active layers.
layer
Works the layer settings and parameters
Parameters
operation [, setting | parameter ]
Valid operations:





get – gets the value of setting or parameter by name,
set – sets the value of setting or parameter by name,
add – adds new parameter(s). The value of parameter is an array of named values,
remove – removes the parameter by name,
clear – removes all parameters.
Answers
{ setting | parameter, value } | “”
A property object for the operation get if succeeded, otherwise an error. For all other operation the answer
contains either an error, or an empty string.
Events of GPE-systems
state
Fires when a system state changes
Data
Same as the answer to the state request
data
Fires when a new data becomes available
Content
layer, data
The key layer is name of layer. The key data is an array of name-value pairs that corresponds to the
description of the layer.
Requests for modules
info
Gets information about the module
Parameters
Answers
name, version, company || author, description, consume, produce
The key consume is an array of layer names that the module consumes, and the key produce is an array of
layer names that the module produces.
settings
Gets the module settings
Parameters
- | [ ... ]
 No parameters – return all module’s settings (array of top-level Setting objects).
 All or a subset of settings that a module’s answer contains to the request for settings with no
parameters. Only the key value (except for containers) is required to pass. The request must keep the
correct hierarchy of each setting. For example, if the answer to the request settings with no parameters
contains
{
request: “settings”,
from: “{30A6f5BD-98C4-11CE-BA82-01A900DBEC00}”,
answer: [ {
name: “size”,
value: 30,
default: 30,
units: “px”,
description: “Maximum fixation size”,
min: 15,
max: 80
}, {
name: “duration”,
value: 80,
default: 100,
units: “ms”,
description: “Minimal fixation duration”,
min: 40,
max: 150
} ]
}
and the client application needs to set a new maximum fixation size to 35 pixels, then the request should be
as follows:
{
request: “settings”,
to: “{30A6f5BD-98C4-11CE-BA82-01A900DBEC00}”,
parameters: [ {
name: “size”,
value: 35
} ]
}
Answers
 For the request with no parameters: all module’s settings, an array of the Setting objects.
 For the request with parameters: a subset of the passed settings (with the corrected (current) values)
that were not accepted. For example, if the client tried to set the new maximum fixation size to 10
pixels, then the answer could be as follows:
{
request: “settings”,
from: “{30A6f5BD-98C4-11CE-BA82-01A900DBEC00}”,
answer: [ {
name: “size”,
value: 30
} ]
}
If all passed settings were accepted, it contains an empty array in the answer.
display
Displays a window with the modules settings
Parameters
- | [ ... ]
 No parameters or empty array to shows all settings.
 Array of names of settings - the settings that must be displayed. Only names of the top-level containers
and settings can be listed in this array.
Answers
[ ... ]
An array of names of a subset of settings that are visible (could contain settings that were visible already
before this request).
hide
Hides a window with the module setting, if it is visible.
Parameters
- | [ ... ]
Allowed parameters:

No parameters or empty array: hides the window with settings.

List of names of settings to hide them. Only names of the top-level containers and settings can be listed
in this array.
Answers
[ ... ] | <value>
An array of names of a subset of settings that remained visible.
feed
Sends a data layer to the module
Parameters
<layer>
This is a Layer object, only the keys name and data will be analyzed.
Answers
“” | <layer>
An error if the layer or its data were not accepted, otherwise empty string or the passed layer’s data with
modified values.
reset
Resets the module state preparing it for feeding by data
Parameters
- | { ... }
No parameters or an object populated by name-value pairs (see the description of the module for details)
Answers
“”
An error if the module was not reset or parameters were not correct, empty string otherwise.
finalize
Finalizes the module’s routine.
Parameters
Answers
“”
An error if the module routine was not finalized, empty string otherwise.
Events of modules
data
Fires when a new data becomes available
Content
layer, data
Layer name and data. Data is an array of name-value pairs that corresponds to the description of the layer.
Requests for browsers
systems
Gets a list IDs of accessible systems
Parameters
Answers
[...]
A list of IDs of accessible systems. IDs are in the format of globally unique identifiers (GUID).
modules
Gets a list IDs of available modules
Parameters
Answers
[...]
A list of IDs of available modules. IDs are in the format of globally unique identifiers (GUID).
display
Displays a window with browser, systems and modules settings
Parameters
<id> | [ “browser” || “systems” || “modules” ]
If a system/module ID is passed, then only its settings are displayed. Otherwise, it must be an array where the
valid categories are listed. Passing an empty array mean a request to display settings for all categories.
Answers
[...]
An array of IDs and categories which settings are displayed.
hide
Hides browser, systems and modules settings
Parameters
<id> | [ “browser” || “systems” || “modules” ]
Pass a system/module ID, or an array of category names to hide its settings, Passing an empty array mean a
request to hide all settings.
Answers
[...]
An array of IDs and categories which settings are still displayed.