Introduction

About

The EyeLogic Software Development Kit (SDK) is a free software package for building custom applications that use an EyeLogic eye tracking device. It provides the ability to connect to your device from any custom application via an Application Programming Interface (API). The EyeLogic SDK is available in the following programming languages C++, C#, C, and Python. It can also be used with any other programming language that can import dynamic link libraries (DLLs), such as Visual Basic or Matlab.

For each directly supported language, there is a short and simple example program to help you start developing your first EyeLogic application.

This manual describes how to use the EyeLogic API for C and gives a step-by-step introduction on how to start with your own C program.

System Requirements

Please refer to the EyeLogic Server documentation for system requirements and installation instructions.

The SDK has no additional requirements. It is built for Microsoft Windows (32 bit or 64 bit) only. The included sample projects are written for Microsoft Visual Studio 2017 or newer. Other compilers are not supported at this time.

Installation and Getting Started

Download Software

To use an EyeLogic eye tracking device from within your application, you need the EyeLogic Server and the EyeLogic SDK. Check the download page for the latest version of both packages: https://www.eyelogicsolutions.com/downloads/

Compatibility

The software is written to support backwards compatibility, i.e. updating the EyeLogic Server software will not break support for your device, regardless of the model. This guide assumes that you are installing the latest version of the EyeLogic Server. Please always update to the latest server version before reporting an error to the EyeLogic Support.

On the other hand, it is not always necessary to update the SDK and API DLLs. Since you as a programmer would have to recompile your application with each SDK update, we have designed the SDK to allow the server to communicate with older API versions. So when you ship your application, simply add the EyeLogic API DLLs of the current version to your package. It will be compatible with both current and newer versions of the server.

See Shipping Your Application for a tutorial on how to ship your application.

Installing the EyeLogic SDK on Windows

The EyeLogic SDK does not need to be installed. It is shipped as a .zip file that simply needs to be extracted to any directory on your hard drive. Make sure you have user rights to that directory, e.g. any directory within C:\Program Files or similar is problematic as it requires admin rights to access those files every time you start your program. It is recommended to use a local user directory.

Note: The SDK has to be installed on the same computer as the server. Please see the main server manual for help on installing the server.

After extracting the .zip file, the directory contains one subfolder for each supported programming language. Open the c folder, the content should be:

bin - contains the binary DLLs to link against
example - contains the sample code
include - contains the include header files for compilation

Getting Started with the Sample Code

In the directory, into which you unpacked the SDK EyeLogicSDK, navigate to the sub-directory c/example and open the solution file AllDemoClients.sln in Visual Studio. Note, you will need Visual Studio 2017 or newer to open this file.

You may want to choose your destination compile level (Debug/Release) in the drop down list on top of the screen. Set it to "Debug" while developing your app. When your app is finished, set it to "Release" to create an optimized application binary. Then compile from the menu with Build->Build Solution. You should see output similar to the following:

1>------ Build started: Project: DemoClient, Configuration: Debug x64 ------
2>------ Build started: Project: DualPC, Configuration: Debug x64 ------
3>------ Build started: Project: Validation, Configuration: Debug x64 ------
1>  main_democlient.c
2>  dualpc_democlient.c
3>  validation_democlient.c
1>  DemoClient.vcxproj -> cpp\example\x64\Debug\DemoClient.exe
2>  DualPC.vcxproj -> cpp\example\x64\Debug\DualPC.exe
3>  Validation.vcxproj -> cpp\example\x64\Debug\Validation.exe
1>  Copy dll dependencies for execution
1>          1 File copied.
2>  Copy dll dependencies for execution
2>          1 File copied.
3>  Copy dll dependencies for execution
3>          1 File copied.
========== Build: 3 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

Before running the application check that the EyeLogic Server is running (see the EyeLogic Server manual). If the server is running, there will be an EyeLogic icon in the Windows system tray.

On the left hand side of the Editor you will see a list of all projects/clients. The active one is highlighted in bold (DemoClient). You can make any other demo client active (e.g. DualPC or Validation) by right-clicking on the desired name in the list and setting it as the startup project.

Press F5 to compile and run the application.

Note that your firewall may block the connection between your program and the server. In this case, add a rule to your firewall to allow your application to open TCP/UDP ports to an application on localhost (for Windows Defender, just click "Accept").

If you have reached this point, you have set up your EyeLogic SDK correctly. You are now ready to start developing your own application. See the next section Concepts for the basic programming concepts and for a tutorial on how to deploy and ship your application.

Concepts

Server-Client Setup

The EyeLogic software consists of two main parts: The server and the API. The server is the neccessary driver for your eye tracking device. It detects your device and handles the communication. The API is part of the EyeLogic Standard Development Kit (SDK). It consists of .dll files that can be used by your application to connect to the EyeLogic Server, start tracking and receive eye tracking data.

The server is designed to run continuously as a background process on your computer. When not actively tracking, the server uses a negligible amount of your computer's resources. Once an EyeLogic eye tracking device is connected, the Server application automatically detects it automatically and allows the user to set it up via the Server configuration dialogue (see the Server icon in the Windows tray bar). If for some reason the server background process is not running (the tray icon is missing), you can start the server manually from the Windows Start menu.

The API is a set of .dll files that can be used by any custom program (called a user application). These DLLs allow the user application to connect to the (running) server. Note that it the EyeLogic Server can run on the same machine as the user application, or they can run on different PCs. See Dual PC Setup for how to set up the setup with running the server and the user application running on different machines.

Set Up a Project for your Application

For an easy start to developing a new application, it is recommended that you copy the existing sample folder to a new location (e.g. EyeLogic_SDK\c with all its contents). The sample source file already provides a fully functional implementation. From this sample code, you can easily modify and extend the code to suit your individual experiment.

Alternatively, you can start a new Visual Studio project from scratch. In this case, make sure that the compiler and linker are able to find the EyeLogic include and binary files. To do this, make the following changes to the project properties of your Visual Studio project:

Under "C/C++", set "Additional Include Directories" to the location of <Location of your EyeLogic_SDK>\c\include.
Under "Linker", set "Additional Library Dependencies" to <Location of your EyeLogic_SDK>\c\bin.
Under "Linker -> Input", add ELCApi.lib to "Additional Dependencies" (for Win32-Applications, use ELCApi32.lib).

Control Flow between API and server

The usual control flow between the custom application/API and the server is characterised by the following steps:

initialize: Before calling any other function the API DLLs need initializing.
connect to server: Establish a connection to the server via TCP.
find eye tracking device: Obtain the information on connected eye trackers, otherwise wait until an eye tracker is plugged in.
start tracking: Request tracking. If successful, the device will start tracking and the server sends GazeSamples to the user application, see also Gaze Samples.
perform calibration: Request a calibration. A calibration point will appear on the screen, animated to move across the screen. The user must fixate on this point until the calibration screen disappears. The system is calibrated and ready for use when this process is successfully completed.
shut down: At the end of your experiment either stop the tracking or simply shutdown the API.

All information which is passed from the server to the user application is passed via asyncronous callbacks. The application must register it's own implementations of these callback functions with the API (see Example Program for a sample implementation).

Note that you need to calibrate to get valid gaze samples (see Gaze Samples). Any gaze samples reported before the system is calibrated will not contain valid eye data.

Dual PC Setup

The Dual PC Setup is a special setup where the EyeLogic Server runs on a different computer than the user application.

The most common use case for the Dual PC Setup would be the following. Running an experiment with an operator constrolling the eye tracking device and a participant performing a task. The participant uses a different PC (which displays the experiment) than the operator (who can control the eye tracker via the EyeLogic Server software).

The operator's computer (called the Operator PC) must have the EyeLogic driver software (the EyeLogic Server) installed and running. The eye tracker is physically attached to a monitor that is connected to the participant's computer (called the Experiment PC). The USB cable of the eye tracker is plugged into the USB port of the Operator PC!

The operator can now use the server to detect the eye tracking device. On the Experiment PC, any custom application that presents an experiment to the participant can use the EyeLogic API to remotely connect to the server. To do this, the application should use the API calls:

elRequestServerList() to obtain a list of all EyeLogic servers in the local network (LAN/WLAN) which are running and are configured to allow remote connections
elConnectRemote() to conntect to a specific server from that list
elSetActiveScreen() to set the screen connected to the Experiment PC as the active screen for eye tracking (replacing the default main screen of the Operator PC)

Note, that a server must allow remote connections for it to be found. You can enable this in the settings of the server window.

If the connection is successful, the client can operate as usual as if it were connected to a local server. See the demo application "dualpc" demo application in the SDK for an example.

Example Program

In this section, the code of the C example program is explained in some detail.

The file starts with an include section. It adds

#include "elcapi/ELCApi.h"

in order to find all neccessary definitions of the EyeLogic API.

The next relevant part is the definition of the callback functions which are invoked by the EyeLogic API whenever an event occurs. Declaration of those functions may look like:

void onGazeSample( const struct ELCGazeSample* gazeSample );
void onEvent( enum ELCEvent event );

These are the callback functions that will be called by the EyeLogic software whenever an event occurs. These functions are defined in the following lines. The example code simply prints the event to the console, but you can write your own implementation here.

The main( ) method is where the application implements its control flow. It consists of the following code lines:

elInitApi( "Demo Client" );

Always call elInitApi first before calling any other function of the EyeLogic C API. This is necessary to initialise the internal structures. Accordingly, the last command of your program to the EyeLogic API should be

elDestroyApi( );

The callback functions are registered by:

elRegisterEventCallback( onEvent );

and (further below):

elRegisterGazeSampleCallback( onGazeSample );

After initialization the program proceeds with:

const enum ReturnConnect retConnect = elConnect( );

Connects to the EyeLogic server. Check the return code to see if the connection was established successfully.

elGetActiveScreen( &screenConfig );

and

elGetDeviceConfig( &deviceConfig );

are called in order to obtain information about the active screen and the connected eye tracking device. If no device is connected, deviceConfig.deviceSerial is set to 0.

const enum ReturnStart retStart = elRequestTracking( 0 );

Tells the device to start tracking and the Server to begin sample processing. Parameter 0 specifies the frame rate mode. If your device is capable of multiple frame rate modes (60Hz, 120Hz or 250Hz), you can also specify a different number. The list of available frame rate modes is passed to the onDeviceConnected( ) callback, with the first frame rate mode (0) being the default mode, which is usually the fastest available mode on your system.

const enum ReturnCalibrate retCalibrate = elCalibrate( 0 );

Performs a calibration. This method blocks until the calibration is finished - i.e. completed or cancelled. The parameter 0 indicates the type of calibration. A list of available calibration methods is part of the DeviceConfig and can be obtained by calling getDeviceConfig( ).

The example program waits for 10 seconds and then closes the connection:

disconnect( );
elRegisterGazeSampleCallback( 0 );
elRegisterEventCallback( 0 );

The last two lines unregister the callback functions. Be sure to unregister them before destroying the API object.

elDestroyApi( );

Gaze Samples

Gaze samples are the most important data which is generated by the eye tracker. The eye tracker provides one gaze sample per frame. Each sample contains information about the time of measurement, the position of the eyes, the pupil radius and the point at which the user is lokking on a stimulus plane (usually a computer monitor).

Shipping Your Application

When you want to ship your application, be sure to include all relevant files so that it can run on different computers. The EyeLogic functionality will only work on computers that have the EyeLogic Server installed. The installed server must be at least be of the same version as the supplied API DLLs (a newer server version is acceptable).

In addition to the relevant files of your application, you need to ship the contents of the bin/ folder of your language (typically including some .dll files). Place the contents of the bin/ folder in the working directory of your application and ship them together.

Appendix

License Agreement and Warranty for SDK

IMPORTANT – PLEASE READ CAREFULLY:

The License Agreement is a legal agreement between you and EyeLogic GmbH and its affiliates (“EyeLogic”, “we”, or “us”). This license agreement governs your use of the EyeLogic software and any third party software that may be distributed therewith (collectively the “software”). EyeLogic agrees to license the software to you (personally and/or on behalf of you employer) (collectively “you” or “your”) only if you accept all the terms contained in this license agreement. By installing, using, copying, or distributing all or any portion of the software, you accept and agree to be bound by all of the terms and conditions of this license agreement.

If you do not agree with any of the terms of this license agreement, do no install or use the software.

License Grant: EyeLogic grants you a revocable, nonexclusive, non-transferable, limited right to install and use the application on a device owned and controlled by you, and to access and use the application on such mobile device strictly in accordance with the terms and conditions of this licenses, the usage rules and any service agreement associated with your device. The Software includes third party software and other copyrighted material. Acknowledgements, licensing terms and disclaimers for such Third Party Software are provided with the Software or contained in the Documentation, and your use of such Third Party Software is governed by their respective terms (collectively “Related Agreements”).
Restriction on Use: You shall use the application strictly in accordance with the terms of the related agreements and shall not:
1. decompile, reverse engineer, disassemble, attempt to derive the source code of, or decrypt the application,
2. make any modification, adaption, improvement, enhancement, translation or derivative work from the application,
3. violate any applicable laws, rules or regulations in connection with your access or use of the application,
4. remove, alter or obscure any proprietary notice (including any notice of copyright or trademark) of EyeLogic or its affiliates, partners, suppliers or the licensors of the application,
5. use the application for any revenue generating endeavor, commercial enterprise or other purpose for which it is not designed or intended,
6. make the application publicly available over a network or other environment permitting access or use by others without the written permission of EyeLogic,
7. use the application for creating a product, service or software that is, directly or indirectly, competitive with or I any way substitute for any services, product or software offered by EyeLogic,
8. use any proprietary information or interfaces of EyeLogic or other intellectual property of EyeLogic in the design, development, manufacture, licensing or distribution of any applications, accessories or devices for use with the application.
Termination: EyeLogic may, in its sole and absolute discretion, at any time and for any or no reason, suspend or terminate this license and the rights afforded to you hereunder with or without prior notice. Furthermore, if you fail to comply with any terms and conditions of this license, then this license and any rights afforded to you hereunder shall terminate automatically, without any notice or other action by EyeLogic. Upon the termination of this license, you shall cease all use of the application and uninstall the application.
Disclaimer of Warranties: You acknowledge and agree that the application is provided on an “as is” and “as available” basis, and that your use of or reliance upon the application and any third party content and services accessed thereby is at you sole risk and discretion. EyeLogic and its affiliates, partners suppliers and licensors hereby disclaim any and all representations, warranties and guaranties regarding the application and third party content and services, whether express, implied or statutory, and including without limitation, the implied warranties of merchantability, fitness for a particular purpose, and non-infringement, furthermore, EyeLogic and its affiliates, partners, suppliers and licensors make no warranty that
1. The application or third party content and services will meet your requirements,
2. The application or third party content and services will be uninterrupted, accurate, reliable timely secure or error-free,
3. The quality of any products, services, information or other material accessed or obtained by you through the application will be as represented or meet your expectations, or
4. Any errors in the application or third party content and services will be corrected.
No advice or information whether oral or written, obtained by you from EyeLogic or from the application will create any warranty not expressly made herein or create any liability on the part of EyeLogic.

If the licensee modifies or replaces any of the third party open source software included in the software, EyeLogic is not obligated to provide any updates, maintenance, warranty, technical or other support or services for the resultant modified Software. You expressly acknowledge that any failure or damage to any hardware, software or systems as a result of such modification to the open source components of the software is excluded from the terms of any EyeLogic warranty.
Limitation of liability: Under no circumstances shall EyeLogic or its affiliates, partners, suppliers or licensors be liable for any indirect, incidental, consequential, special or exemplary damages arising out of or in connection with your access or use of or inability to access or use the application and any third party content and services, whether or not the damages ere foreseeable and whether or not EyeLogic was advices of the possibility of such damages. Without limiting the generality of the foregoing, EyeLogic’s aggregate liability to you (whether under contract, tort, statue or otherwise) shall not exceed the amounts actually paid by licensee for the licensed materials. The foregoing limitations will apply even if the above stated remedy fails of its essential purpose.
Confidentiality: Licensed materials are proprietary to EyeLogic and constitute EyeLogic trade and business secrets. The licensee shall maintain licensed materials in confidence and prevent their disclosure using at least the same degree of care it uses for its own trade and business secrets, but in no event less than a reasonable degree of care. The licensee shall not disclose licensed materials or any part thereof to anyone for any purpose, other than to its employees and sub-contractors, if any, for the purpose of exercising the rights expressly granted under this agreement, provided they have in writing agreed to confidentiality obligations at least equivalent to the obligations stated herein. The foregoing does not apply to information that a. is or becomes generally known or available to the public without any breach of the confidentiality obligation by licensee, b. was already known to licensee prior to the disclosure by EyeLogic, or c. was rightfully acquired by licensee from a third party without a breach of a confidentiality obligation towards EyeLogic. In case of a dispute, the licensee has the burden of proof that the licensed materials and/or any portion thereof fall under one of these exceptions. Should the licensee be legally compelled to disclose any licensed materials to a third party, such as pursuant to a mandatory order by a court or authority or any comparable action, the licensee shall, to the extent permitted under applicable law, inform EyeLogic without undue delay and undertake all possible measures to safeguard secrecy.

About EyeLogic

EyeLogic is a manufacturer of high precision and high quality eye tracking devices, mainly for scientific and research use cases. EyeLogic GmbH is a spin-off of the Free University of Berlin, faculty of mathematics and computer science and has a vast experience in image processing and computer vision.

Contact and Support

For technical support questions contact us via mail at: suppo.nosp@m.rt@e.nosp@m.yelog.nosp@m.icso.nosp@m.lutio.nosp@m.ns.c.nosp@m.om

EyeLogic GmbH
Schlesische Str. 28
10997 Berlin Germany
www: https://www.eyelogicsolutions.com

Copyright © EyeLogic GmbH