And here is our first task: prepare requirements and recommendations concerning API type. I start it with the list of my expectations, others please correct/improve it if necessary.

1. API must be implemented using the technology fast enough. However, it is hard to say what is "enough". My own expectation here is that samples are delivered to client applications with the delay max 50 ms. I guess, human motor reaction to any visible stimuli is longer that this threshold. My experience shows that the existing solutions (TCP/IP connection between driver/dispatcher and low-level API; wrapping low-level API into COM objects) are good enough, but others may exist too, no strict restrictions here...
2. API must be implemented in a way that is it visible globally (on a PC) and no files from SDK must be copied into the folder where client application is installed. Again, COM technology seems the best here, IMHO, although I have heard some critics about it (mainly, due to the too long delays) and suggestion (not quite well argued, however) for other API types. The way I see it:

* During eye-tracking API installation, it registers itself into the HKEY_LOCAL_MACHINE\SOFTWARE\ETUDE\Devices\ by creating a key with the name of the CLSID of the class that implements basic eye-tracking interfaces. For example:

'['HKEY_LOCAL_MACHINE\SOFTWARE\ETUDE\Devices\{00000000-000-0000-0000-000000000000}']'
@ = "EyeTrackerName"

* Client applications or helpers (auxiliary ETUDE classes) will read this registry key to obtain a list of devices installed and create an object of the CLSID specified that implements a basic eye-tracking interface (to be discussed in a separate topic).

Any better suggestions on this topic? Would it be possible to use COM technology in Linux/Mac? If not, what could be other (cross-platform) solutions that satisfy the requirements listed above?

gdaunys wrote:

In textbooks about Microsoft .NET often is written that .NET remoting has advantages against COM. And exist MONO project, which is proposing .NET methods implementations for other platforms.

Indeed, something to keep in mind... I'll try to dig it a bit.. whether it suits for API development

adrian wrote:

But I think it would be a "nice to have" to be eyetracking hardware treated like any other default group of devices (monitors, mice). So that the manufacturer itself could implement a PnP installation as basic eyetracker (as Oleg said e.g in \ETUDE\Devices and additionally as a mouse).

I seems for me, that PnP approach will not work for eye-trackers, since

gdaunys wrote:

In case of videooculographical eye tracking systems the attached to computer bus device is camera. By its identifier a camera driver is launched. An eye tracker is a system of hardware and software components. So we must have in mind that real driver for hardware is camera driver, which is used by image processing software. Image processing software using calibration data calculates point of gaze coordinates and transfer them to applications or to some intermediate software component as COM server.

Moreover, MS Windows does not support eye-tracking devices on a level it supports mouse and keyboard, thus the access to ET devices will be via OEM libraries, not via nt.dll, kernel.dll or user32.dll. As long as eye-tracking system is a combination of hardware and software, it is not gonna be PnP, IMHO.

It seems that we have the same in mind, and I guess that everyone stay happy if there will be some commonly-accepted way for an ET system to a) announce itself and its features, and b) expose its services (functions).

gdaunys wrote:

I want accent diversity of eye trackers hardware.

Sure, but the role of the API standardization is to left behind such API peculiarities of each system, so that access to it and data capturing is fairly easy and straightforward.

What seems also important for me, is that in future we may have many ET systems on a single machine, and many clients connected to the same or distinct systems. Thus many-to-many. Therefore the next expectation from an API is:

3. API allows many-to-many connections. For example, there are T60 and X120 in the setup, and App1 and App2 clients running simultaneously. Each client gathers data from both devices simultaneously (each client contains several components, each component is communicating with a single device only). And such a setup should work. And there would be possible very complex setups:

One may notice that Tobii SDK is organized this way already, thus I would encourage others to follow this way :). This expectation does not tell how to implement such functionality in API, is explains its features only.

Here is the first draft of API assumptions and requirements:

API assumptions

• This specification targets primary to HCI researchers and developers, but others may benefit from it as well.
• This specification deals with gaze data passive (collecting) and active (interaction) usage.

• Fast:
  API must be implemented using the technology fast enough, i.e. samples are delivered to client applications no later than 50 ms after a video frame was captured. Most of the today existing solutions (TCP/IP connection between driver/dispatcher and low-level API; wrapping low-level API into COM objects) are good enough, but others may exist too, no restrictions here.
• Accurate timestamping:
  Tmestamping is at least of millisecond precision and is presented as “double”-type value in seconds (or, alternatively, two integers - for second and microsecond parts). One of the system information fields should report about the timestamp retrieval moment: for example, -2 value for system that timestamps data by the frame start time, -1 for system that timestamps data by the frame middle time, 0 for system that timestamps data by the frame end time, and any positive value to denote typical latency (in milliseconds) between frame end time and the moment of timestamp retrieval.
• Allows many-to-many connections:
  Each client application can be connected to different eye-tracking systems in parallel and receive data, and each API can serve for multiple client application. Moreover, the standard should support systems that may track more than one person at a time.
• Visible globally:
  There is an ETUDE Eye-Tracking System Manager (ETSYM) implemented in each API, that knows how to detect certain types of eye-tracking systems. Each ETSYM installed on a PC declares its own name, names of manufacturers and their systems (with their versions) that it recognizes. ETSYM manages the lists of systems available currently, and provides this list to clients on request. It also informs clients when some systems becomes available/unavailable. The list of ETSYMs installed on a PC is available via some global resources.
• Auto-scan:
  ETSYM scans for the systems available and create a list of them. It exposes a function that establishes a connection between client application and ET system. This function takes a system ID as parameter and returns descriptor of ETUDE Eye-Tracking System (ETSYS) the client now is connected to. System ID is either a) the ID value from the list of available systems, or b) the value received via an event that informs client that a new system becoming available.
• Self-informative:
  ETSYS exposes properties that return manufacturer name, system name, system version, and a number of possible system configurations. There should be at least one default configuration for each system. The default configuration has “0” value. ETSYS also exposes a property to get/set current configuration, and a function that that fills a predefined structure of the basic ET system characteristics (such as sampling frequency, mix/max working distance, etc.) given the configuration index (the structure also contains the name of a given configuration). ETSYS provides functions to list, get and set system-specific parameters (not classified, addressed by name).
• Notification of state change:
  Each API has 4 variables to indicate system state, and it send notifications to clients when any variable changes

  Available	Connected	Calibrated	Tracking	Description
  no	-	-	-	System is not available
  yes	no	-	-	System is available but not connected to the client application
  yes	yes	no	-	System is connected to the client application, but is not calibrated yet
  yes	yes	yes	no	System is connected, calibrated and ready to deliver data
  yes	yes	yes	yes	System sends data to the client application

• Easy-to-calibrate:
  Each API provides two means to calibrate a system. First mean is a simple function that runs all the calibration routine and returns after the routine is finished (either successfully or not). The second mean is a custom calibration (client application shows stimuli and informs API about new calibration point ready to add). Each ETSYS provides (optionally) an access to ETUDE Eye-Tracking System Calibration, ETSYC (if custom calibration is not available, the corresponding function returns NULL). API also has a mean to indicate how good the current or ready-to-set calibration is (for example, via a read-only property that returns a value between 0 (not calibrated) and 1 (ideal calibration)).
  API stores a number of named calibrations that can be set as a current calibration. There are functions that a) return the number of available calibrations (can be 0, if this feature is not implemented), b) get name of each calibration in the list, c) add the current calibration to the list of calibration (take a name as a parameter), and d) set a calibration as current given its index.
• Leveled tracking quality report:
  API provides means to inspect tracking quality. Ideally, it has three levels of report:
  1. numerical: a number between 0 (no valid samples) and 1 (all samples are valid) is accessible to client application via callback function (estimation based on data collected within a certain time interval)
  2. simple GUI component: small GUI component to be placed into a client application to stay aware about tracking quality while tracking is on.
  3. full-featured GUI component: somewhat similar to the existing Tobii’s TrackStatus component.
• Layered data:
  The richness and meaning of data that client application receives depends on what data layer it announces as data source. A client can subscribe to use many layers simultaneously. Possible layers (events): a) simple/complete/binocular sample, b) gaze event (fixation/saccade/smooth pursuit/blink) start/update/end, c) head event (?) start/update/end, d) gaze-awareness event (GUI object entering/leaving), e) gaze-control event (GUI object selection/click/double-click/???), f) interaction event (gesture/dwell/?) start/update/end. Each API manifests what kind of layers it implements. Before changing the system state into “Tracking=yes”, each client should subscribe to receive data of a certain layer. Each data packet contains a) data validity value between 0 (invalid) and 1 (absolutely valid), and b) time-stamp.
• Synchronization:
  Each API has a function that returns current ET system internal clock value (timestamp).
• GUI for options adjustment:
  Each API has a function that shows a dialog with ET systems options.

...and here is the example from life:

Just yesterday here we were discussing about implementing a tool for our research. We are going to study the case of text entry (usual, not by gaze) and reading, having one person per task: one is typing a text, another one is reading the product. The software runs on a single machine, but uses two screens: one for writer, one for reader. The text that is shown for reader is not "raw", i.e. the software tries not to show words while they are in typing or editing process, but rather complete result.
And in our study we are going to track eye movements of both writer and reader. Obviously, we need two eye-trackers, connected to the same machine, and a single tool will collect data.

I'm not sure we can implement such a tool with our current ET systems...

OK, I agree that this is a very specific case, and API should be as simple as possible. But I mentioned that this requirement is "weak" and comes more like a recommendation: in future, it might be useful to have several synchronized devices. Anyway, violation of this recommendation will not harm compatibility with standard API...

This branch is temporally locked due to hard spamming. Please, contact administrator if you wish to post any message here.