Menu
▾
▴
Code
- Overview and credits
- How to install the toolbox
- Stereoscopic Calibration
- Code explanation
- Device Evaluation
- Experimental Suite
Code Explanation
UDP Server Interface
The Tobii EyeX Eye Tracking Controller provides an User Datagram Protocol (UDP) server which Matlab can connect with. In this regards, the Matlab implementation is a client UDP application used to provide the eye controller with the necessary information to define the proper sequence of events for a desired experiment.
Basic Connection Functions
The tobii_connect function opens the server application, connects the Tobii EyeX on the IP address, and opens an UDP port for data transmission and receiving.
% START SERVER AND OPEN UDP PORT
function tobii = tobii_connect(server_path,ip_address)
% INPUT:
% server_path - path to the server
% ip_address - IP of the machine where EyeX is connected
% OUTPUT:
% tobii - Matlab udp object
The tobii_command function is used for the general reception and transmission of data and commands from/to the server. In particular, it is used to: 1) initialize the device (command='init'), 2) start the gaze data acquisition and saving of raw data to a txt file (command='init',arg='file_name'), 3) acquire a single datum from the device (command='read'), 4) interrupt the gaze data acquisition (command='stop').
function [msg DATA]= tobii_command(tobii,command,arg)
% function [msg DATA]= tobii_command(tobii,command,arg)
% INPUT:
% tobii - Matlab udp object
% command - command to be sent to the server ('init', 'start', 'read', 'stop')
% arg - argument of the command to be sent to the server
% OUTPUT:
% msg - message check of correct data received
% DATA - data requested to the EyeX
The tobii_close function closes the server application and the UDP port.
% CLOSE SERVER AND UDP PORT
tobii_close(tobii);
% function [msg DATA]= tobii_close(tobii)
% INPUT:
% tobii - Matlab udp object
The following get functions are dedicated to receive the selected data from the device, and have been implemented to avoid the use of the general purpose tobii_command function in order to both save the computational time used by the switch, and to obtain a more clean and readable code. The Matlab Toolbox provides direct access to: the left and right eye gaze position of the screen, in millimeters (tobii_getGPM) or normalized to the screen size (tobii_getGPN), the actual 3D position of the two eyes with respect to the screen center, in millimeters (tobii_getEPM) or normalized to the trackbox size (tobii_getEPN), a combination of the normalized eye and gaze position (tobii_getGPN_EPN), or the current timestamp (tobii_getTime).
Since these functions are similar to each other in terms of input and output parameters, we only report selected examples.
% GET GAZE POINT IN mm
function [L, R, time] = tobii_getGPM(tobii)
% function [L, R, time] = tobii_getGPM(tobii)
% INPUT:
% tobii - Matlab udp object
% OUTPUT:
% L - left gaze position in mm
% R - right gaze position in mm
% Time - timestamp
% GET GAZE POINT NORMALIZED ON DISPLAY AND EYE POSITION NORMALIZED IN TRACKBOX
function [Leye, Reye, Lgaze, Rgaze, time] = tobii_getGPN_EPN(tobii)
% function [Leye, Reye, Lgaze, Rgaze, time] = tobii_getGPN_EPN(tobii)
% INPUT:
% tobii - Matlab udp object
% OUTPUT:
% Leye - left normalized gaze position
% Reye - right normalized gaze position
% Lgaze - left normalized gaze position
% Rgaze - right normalized gaze position
% Time - timestamp
% GET TIMESTAMP
function Time = tobii_getTIME(tobii)
% function time = tobii_getTIME(tobii)
% INPUT:
% tobii - Matlab udp object
% OUTPUT:
% Time - timestamp
Routines
Since the user's position in front of the monitor affects the accuracy of the device, the PositionGuide function, similarly to the one implemented in the EyeX Engine, provides feedback to the users on their current position with respect to the optimal positioning for eye tracking.
The routine provides a graphical interface, implemented with Matlab Psychotoolbox, which visualizes the subject's position with respect to the center of the screen. The user's eyes are rendered in red when the user is too far or too near to the device. The rendered eye size changes as the user's move closer or farther from the display. When the user is correctly positioned near the center of the trackbox, the eye color turns green.
%
function [Lpos Rpos] = PositionGuide(tobii,window,windowRect)
% VISUALIZE THE EYE POSITION AND DISTANCE WITH RESPECT TO THE SCREEN CENTER
% RETURN THE EYE POSITION (IN mm) WITH RESPECT TO THE SCREEN CENTER
%(requires the PsychoToolbox)
% function [Lpos Rpos] = PositionGuide(tobii,window,windowRect)
% INPUT:
% tobii - Matlab udp object
% window - window index (PTB)
% windowRect - window size in pixel (PTB)
% OUTPUT:
% Lpos - mean left normalized eye position kept during the last second
% Rpos - mean right normalized eye position kept during the last second
The CalibrationProcedure function is the core of the calibration procedure. The function takes as input an Nx2 vector containing the N normalized coordinates (X and Y) of the targets to be used for calibration, and returns two structure, for the left and the right eye, containing the calibration fit functions for the X and Y gaze estimation. In the present work we investigated whole screen device calibration, but the procedure can be easily tuned to the requirements of different experiments or applications. For instance, in a vergence experiment presented (see the related paper), the relevant portion of the screen was a central area, only. Accordingly, the calibration procedure can be modified to eight targets positioned on a circle of radius 2.5 degrees, plus one in the exact center of the screen. For a deeper explanation of the difference between the monocular and the binocular procedures, see the related link.
%
\begin{lstlisting*
function [CalibL CalibR] = CalibrationProcedure...(tobii,Target,save_dir,window,windowRect,calibType)
% CALIBRATION PROCEDURE
%(requires the PsychoToolbox)
% CalibrationBinocularSetPrecise(tobii,Target,save_dir,window,windowRect,calibType)
% INPUT:
% tobii - Matlab udp object
% Target - Nx2 vector containing the N normalized coordinates (X and Y) of the
% targets used for the calibration
% save_dir - directory where the calibration parameters are saved
% window - window index (PTB)
% windowRect - window size in pixel (PTB)
% calybType - flag defining whic calibration to perform: 'B' binocular (default),
%'L' left monocular, 'R' right monocular
% OUTPUT:
% CalibL - 1x2 structure containing the calibration fit function for the X and Y
% gaze estimation for the left eye
% CalibR - 1x2 structure containing the calibration fit function for the X and Y
% gaze estimation for the right eye
The CalibFit function is used by CalibrationProcedure to fit the gaze estimation error. The error, computed for each target on the X and Y screen position, is fed to the function together with the targets' position. The function fits a biharmonic function to the data and outputs the surface that best describes the error over the screen area. Other types of fitting (lowess and cubic interpolation) are available.
function [fitresult, gof] = CalibFit(xData, yData, ErrorData, show_fig, ft)
% FIT THE ESTIMATION ERROR OF THE NORMALIZED GAZE POSITION WITH A SURFACE
% [fitresult, gof] = CalibFit(xData, yData, ErrorData, show_fig, ft)
% INPUT:
% xData - X target coordinates
% yData - Y target coordinates
% ErrorData - X or Y estimation error in the target coordinates
% show_fig - flag to show the fit results
% ft - type of fitting: biharmonic (default), lowess, cubicintep
% OUTPUT:
% fitresult - fit object representing the surface
% gof - goodness of fit indexes
The tobii_getGPNcalib function is a modified version of tobii_getGPN. In addition to acquiring the current gaze point normalized to the screen size, it applies to the acquired gaze point the calibration surfaces computed by CalibFit and returns, in real time, the calibrated left and right gaze point.
%
function [Lc, Rc, time] = tobii_getGPNcalib(tobii, CalibL, CalibR)
% ACQUIRE THE GAZE POINT NORMALIZED ON DISPLAY AND APPLY THE CALIBRATION ONLINE
% function [Lc, Rc] = tobii_getGPNcalib(tobii, CalibL, CalibR)
% INPUT:
% tobii - Matlab udp object
% CalibL - calibration fit object for left eye
% CalibR - calibration fit object for right eye
% OUTPUT:
% Lc - calibrated left normalized gaze position
% Rc - calibrated right normalized gaze position
The tobii_GPNcalib function is a modified version of tobii_getGPNcalib, dedicated to calibrating acquired data offline. %If a higher accuracy is not required online
The function takes as input a 2xN array of normalized gaze points and applies to these points the calibration functions computed by CalibFit.
%
function [Lc, Rc] = tobii_GPNcalib(L, R, CalibL, CalibR)
% APPLY THE CALIBRATION TO the GAZE POINT NORMALIZED ON DISPLAY
% function [Lc, Rc] = tobii_GPNcalib(L, R, CalibL, CalibR)
% INPUT:
% L - left normalized gaze position
% R - right normalized gaze position
% CalibL - calibration fit object for left eye
% CalibR - calibration fit object for right eye
% OUTPUT:
% Lc - calibrated left normalized gaze position
% Rc - calibrated right normalized gaze position
The CalibrationCheck function is a modified version of PositionGuide, conceived to provide a visual check of the calibration achieved. The routine provides a graphical interface, implemented with Matlab Psychotoolbox, that visualizes the measurement error of the device. All the targets used for calibration are shown on the screen. While the subject is fixating one them, it becomes red, and the left and right rendered eyes change color, depending on the measurement error, green for small and red for large errors. Since possible misfixations of the subject may affect the calibration, CalibrationCheck is a useful and easy-to-use tool to verify the result of the calibration procedure, and possibly run it again, in order to avoid collecting biased or wrong data.
%
function [Lpos Rpos] = CalibrationCheck(tobii,window,windowRect,Target,CalibL,CalibR)
% VISUALIZE THE EYE POSITION AND DISTANCE WITH RESPECT TO THE SCREEN CENTER
% VISUALIZE A SET OF TARGETS AND A GAZE THRESHOLD ERROR
% RETURN THE EYE POSITION (IN mm) WITH RESPECT TO THE SCREEN CENTER
%(requires the PsychoToolbox)
% function [Lpos Rpos] = PositionGuide(tobii,window,windowRect)
% INPUT:
% tobii - Matlab udp object
% window - window index (PTB)
% windowRect - window size in pixel (PTB)
% Target - 2xN array containing the target position
% CalibL - calibration fit function for the left eye
% CalibR - calibration fit function for the right eye
% OUTPUT:
% Lpos - mean left normalized eye position kept during the last second
% Rpos - mean right normalized eye position kept during the last second
Sample Code
The script EXAMPLE_SALIENCY is the MATLAB code used for the measurement of visual exploration eye movements on an image, presented in Sec.~\ref{subsec:saliency*. After having activated and initialized the Tobii EyeX, a window is opened via Psychotoolbox with a gray background. The window is first used to perform a 9PC, and next to display the image to be explored. The left and right eye position measured during the experiment are used to compute a bidimensional histogram from which we obtain the salient points on the image.
This code is provided as an example that can be easily modified by a user for their specific purposes. Regarding the calibration, the target position can be easily modified in the script, in order to take into account the different requirements of the experiment. Likewise, the code relative to the eye tracker is conceived to be easily integrated in a pre-developed code.
Hello,
I have encountered an error message. I do not know the sequence with which I need to run these matlab files. When I run EyeXMatlabServer located within matlab_server folder of the project file, I get the error. What should be done to fix it ? Even if i download and reinstall it again, I am getting the same error.
Hi Rasa,
You just have to search the missing dll, download and copy it in the matlab
server folder.
Regarding the workflow of the program, you can find anyhing I could say on
the wiki page of the project on surceforge
https://sourceforge.net/p/matlabtoolboxeyex/wiki/Home/
If you Hve a more specific question I can try to help.
Best,
Agostino
On Wed, Sep 12, 2018, 10:25 Rasa Bhattarai lmagneto@users.sourceforge.net
wrote:
Dear Agostino,
This is Owen. I am studying electrical engineering. I got a final year project to analysis the effectiveness of UHD display by using the eye tracker. May i know the sequence for running the matlab files as i am not good at matlab, many thanks.
Sincerely,
Owen