 |
EyeLogic SDK
1.1.9
|
|
EyeLogic SDK
1.1.9
|
The EyeLogic Software Development Kit (SDK) is a free software package for building custom applications which use an EyeLogic eye tracking device. It offers the possibility to connect with your device via an application programming interface (API) from any custom application. The EyeLogic SDK is available for the programming languages C++, C#, C, and Python. It is also usable with any other programming language that is capable of importing dynamic link libraries (DLLs), e.g. Visual Basic or Matlab.
For each directly supported language, there is a short and simple sample program to help you get started with the development of your first EyeLogic application.
This guide describes the use of the EyeLogic API for C and gives a step-by-step introduction on how to start with your own C program.
For the system requirements of the EyeLogic Server and an installation guide, please refer to the Server's documentation.
The SDK has no additional requirements. It is built for Microsoft Windows only (32 bit or 64 bit). The included sample projects are written for Microsoft Visual Studio 2017 or newer. Any other compilers are not yet supported.
In order to use an EyeLogic eye tracking device from within your application, you need the EyeLogic Server and the EyeLogic SDK. Check the download-page to get the latest release of both packages: https://www.eyelogicsolutions.com/downloads/
The software is written to support backwards-compatibility, i.e. an update of the EyeLogic Server software will not break support for your device, irregardless of the model. The actual guide assumes that you are installing the newest version of the EyeLogic Server. Please always update to the newest server version before reporting an error to the EyeLogic support.
On the other hand, updating the SDK and API-DLLs is not always neccessary. Since you as a programmer would have to recompile your application with every SDK-update, we designed the SDK such that the server is able to communicate with older API versions. Therefore, when shipping your application, just add the EyeLogic API DLLs of the actual version to your package. It is compatible with servers of the actual and newer releases.
See Shipping your Application for a tutorial on how to ship your application.
The EyeLogic SDK does not need to be installed. It ships as .zip file which just needs to be extracted to some directory on your hard disk. Be sure, that you have user-rights to that directory, e.g. any directory inside C:\Program Files or similar is problematic, since it requires admin rights to access those files every time you start your program. It is recommended to use a user-local 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:
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 an output similarly to:
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 is an EyeLogic icon in the windows tray bar.
In the left part of the editor, there is a list of all projects / democlients. The active one is marked in bold (DemoClient). You might make any other demo client active (e.g. DualPC or Validation) by right-click on the desired name in the list and set it as the Startup Project.
Press F5 to compile and run the application.
Note that your firewall might 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 the windows defender, just click "accept").
If you reached this point, you have properly set up your EyeLogic SDK. You may now start with the development of you own application. See the next section Concepts for the basic programming concepts and for a tutorial on how to deploy and ship your application.
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 which can be used by your application to set up a connection to the EyeLogic Server, start tracking and receive eye tracking data.
The server is designed to run permanently on your computer as a background process. While not actively tracking the server requires an insignificant portion of your computer's resources. Once an EyeLogic eye tracking device is plugged in, the server application detects it automatically and allows the user to set it up via the servers' configuration dialog (see the server icon in the windows tray bar). If for any reason the server background process is not running (the tray icon is missing), you may start the server manually via the windows start menu.
The API is a set of .dll files which can be used by any custom program (called the user application). Using those DLLs the user application can establish a connection to the (running) server. Note that it the EyeLogic Server may run on the same computer than the user application, or they may run on different PCs. See Dual PC Setup for how to set up the setting with running the server and the user application on different computers.
For an easy start to develop a new application it is recommended to 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. Starting from this sample code, you can easily modify and extend the code to suit your customized experiment.
Alternatively you can start a new Visual Studio project from scratch. In that case be sure the compiler and linker are able to find the EyeLogic include and binary files. Therefore, apply the following changes to the project properties of your Visual Studio project:
<Location of your EyeLogic_SDK>\c\include. <Location of your EyeLogic_SDK>\c\bin. The usual control flow between the custom application/API and the server is characterized by the following steps:
GazeSamples to the user application, see also GazeSamples. All information which is passed from the server to the user application will be transmitted via asyncroneous callbacks. The application has to register it's own implementations of those callback functions with the API (see Example Program for an example implementation).
Note that you need to calibrate in order to obtain valid gaze samples (see GazeSamples). All gaze samples which are reported before the system is calibrated contain no valid eye data.
The Dual-PC setup is a special setting 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 who constrols the eye tracking device and a participant who has to perform a task. The participant uses a different PC (showing the experiment) than the operator (who can control the eye tracker via the EyeLogic Server software).
The computer of the operator (called Operator PC) needs to have the EyeLogic driver software (the EyeLogic Server) installed and running. The eye tracker is physically mounted to a screen which is connected to the computer of the participant (called Experiment PC). The USB cable of the eye tracker is plugged into the USB port of the Operator PC!
Now, the operator can use the server to detect the eye tracking device. On the Experiment PC, any custom application which shows an experiment to the participant, can use the EyeLogic API to connect to the server remotely. In order to do that, 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 has to allow remote connections in order to be found. You can enable that in the settings of the server window.
If connected successfully, the client can operate as usual as if it would be connected to a local server. See the demo application "dualpc" in the SDK for an example.
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 which are invoked from the EyeLogic software whenever an event occurs. Those functions are defined in the following lines. The example code simply prints the event to the console, but here you may write your custom implementation.
In the main( ) method the application implements its control flow. It consists of the following code lines:
elInitApi( "Demo Client" );
Always invoce elInitApi first before calling any other functions of EyeLogic C API. Is is essential in order to initialize 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 for the return value in order to find out whether 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. The parameter 0 specifies the frame rate mode. If your device is capable of multiple frame rate modes (60Hz, 120Hz or 250Hz), you can also enter a different number. The list of available frame rate modes is passed to the callback onDeviceConnected( ) whereas the first frame rate mode (0) is the default mode, which usually is the highest available speed mode of your system.
const enum ReturnCalibrate retCalibrate = elCalibrate( 0 );
Performs a calibration. This method blocks until the calibration ends - i.e. completed or aborted. The parameter 0 denotes 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( );
GazeSamples are the most essential data which is generated by the eye tracker. The eye tracker delivers one GazeSample per frame. Each sample contains information on the time of measurement, the position of the eyes, the pupil radius and the point where the user looks at on some stimulus plane (usually a computer monitor).
When you want to ship your application, be sure to include all relevant files so that it may run on different computers. The EyeLogic functionality will only work on computers which have the EyeLogic Server installed. The installed server needs to at least be of the same version as the shipped API DLLs (a newer server version is permissible).
Beside the relevant files of your application, you need to ship the content of the bin/ folder of your language (typically including some .dll files). Place the content of the bin/ folder inside the working directory of your application and ship them together.
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.
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
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.
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.
For technical support questions contact us via mail at: support@eyelogicsolutions.com
EyeLogic GmbH Schlesische Str. 28 10997 Berlin Germany www: https://www.eyelogicsolutions.com
Copyright © EyeLogic GmbH