Head-Mounted System Calibration
10.1 Linux Tobii Client Application Program Interface
The Linux Tobii client API was ported to Linux at Clemson University in an independent effort (not written by Tobii Technology). Porting of the client code was achieved via TCP/IP socket programming (referencing the very readable texts of Comer and Stevens (1993,2001)). The library was developed with Tobii’s permission and was last tested with Tobii’s TET Server v2.8.6 (ClearView Full Install Kit v2.5.1).
The code may not function with future TET Server versions but will be ported to work with future TET Server versions if Tobii sanctions the effort and provides sufficient cooperation.
The remainder of this chapter discusses the Linux Tobii client API. Although it is specific to the Tobii eye tracker, it is expected that most eye trackers will contain similar functionality, for example connection to the eye tracker (TCP/IP or serial port), calibration, and data streaming.
10.1 Linux Tobii Client Application Program Interface 107 flag to issueTet_Stopfrom another thread). These as well as the remaining “Tet”
function calls are explained in detail below.
10.1.1
Tet_Initl o n g T e t _ I n i t (v o i d);
Listing 10.1 Tet_Initdeclaration
TheTet_Initcall must be called once at thread initialization. This sets up thread- specific data and initializes the internal timer library. (This function is only relevant in the Linux/Mac OS X environments.)
Example:Tet_Init();
10.1.2
Tet_Connect, Tet_Disconnectl o n g T e t _ C o n n e c t ( c h a r* p S e r v e r A d d r e s s , u n s i g n e d s h o r t p o r t n u m b e r , c h a r* p D e b u g L o g F i l e );
l o n g T e t _ D i s c o n n e c t (v o i d);
Listing 10.2 Tet_ConnectandTet_Disconnectdeclarations
TheTet_Connectcall connects to a (possibly remote) Tobii eye tracking server. The argumentpServerAddressis a null-terminated array of characters that contains the eye tracking server’s host’s name or IP address. If, for example, the server were running on the local machine,pServerAddresswould be set to either127.0.0.1 orlocalhost. The argumentportnumbershould be set to4455(orNULL, which defaults to4455). The argumentpDebugLogFileis the pathname to a log file. Gen- erally,Tet_Connectmust be called prior to calling any otherTet_function.
Tet_Disconnectdisconnects from the eye tracking server. Each call should only be made once.
Example:Tet_Connect("tobii.cs.clemson.edu",4455,"logfile");
Example:Tet_Disconnect();
l o n g T e t _ S t a r t ( T e t _ C a l l b a c k F u n c t i o n func ,
v o i d* pAppData ,
u n s i g n e d l o n g i n t e r v a l );
l o n g T e t _ S t o p (v o i d);
Listing 10.3 Tet_StartandTet_Stopdeclarations
10.1.3
Tet_Start, Tet_StopTet_Startis a blocking function that starts gaze data streaming. When new data are available the callback functionfuncis called immediately with fresh data (see Tet_CallbackFunctionbelow). The argumentpAppDatais optional and points to a user-defined structure that can be passed tofunc. Theintervalargument denotes an interval in milliseconds when the callback function will be called; if it is set to 0, the callback will never be called for a timer reason (but will be called when new gaze data are available).
The callback function may be set up for periodic calls even though there are no new gaze data. Set the interval parameter to something other than 0 and the callback func- tion will be called with ETet_CallbackReasonset toTET_CALLBACK_TIMER andpDataset toNULL.
Example:Tet_Start(gazeDataReceiver,NULL,0);
Example:Tet_Stop();
10.1.4
Tet_CalibClear,
Tet_CalibLoadFromFile,
Tet_CalibSaveToFile
,
Tet_CalibAddPoint,
Tet_CalibRemovePoints
,
Tet_CalibGetResult,
Tet_CalibCalculateAndSet
FunctionTet_CalibClearis used when calibration is to be performed. This clears all points on whichTet_CalibCalculateAndSetbases its calculations. Alternatively, functionTet_CalibRemovePointscan be used to clear only those points within a radiusfrom the point at coordinates(x,y). Units for(x,y)andradiusrange from 0to1where(0,0)is the screen’s upper left and(1,1)is the screen bottom right. The argumentETet_Eyeis one ofTET_EYE_LEFT,TET_EYE_RIGHT, orTET_EYE_BOTH. The blocking functionTet_CalibAddPointis used to perform the calibration.
This function adds a new calibration point at coordinates(x,y). Normal usage is to simultaneously display something on the screen at the same (normalized) coor- dinates, making sure that the viewer gazes at this point at this time. Then call Tet_CalibAddPoint to make the eye tracker record calibration samples at this location. The eye tracker will obtainnrofdatacalibration samples at this calibration point. With a largernrofdata, the longer the calibration point will be displayed. If
10.1 Linux Tobii Client Application Program Interface 109
l o n g T e t _ C a l i b C l e a r (v o i d);
l o n g T e t _ C a l i b L o a d F r o m F i l e (c h a r* pFile );
l o n g T e t _ C a l i b S a v e T o F i l e (c h a r* pFile );
l o n g T e t _ C a l i b A d d P o i n t (f l o a t x ,
f l o a t y ,
u n s i g n e d l o n g nrofdata ,
T e t _ C a l l b a c k F u n c t i o n func ,
v o i d* pAppData ,
u n s i g n e d l o n g i n t e r v a l );
l o n g T e t _ C a l i b R e m o v e P o i n t s (E T e t _ E y e eye ,
f l o a t x ,
f l o a t y ,
f l o a t r a d i u s );
l o n g T e t _ C a l i b G e t R e s u l t (c h a r* pFile ,
S T e t _ C a l i b A n a l y z e D a t a* pData ,
l o n g* pLen );
l o n g T e t _ C a l i b C a l c u l a t e A n d S e t (v o i d);
Listing 10.4 Tet_CalibClear, Tet_CalibSaveToFile, Tet_CalibAddPoint, Tet_CalibRemovePoints,Tet_CalibGetResult, Tet_CalibCalculateAndSet declarations
nrofdatais too large, the entire calibration may be too time consuming. Generally, five calibration points displayed at the screen center and screen corners are adequate (although as few as two calibration points at two opposing corners may be sufficient).
The total number of calibration samples must not exceed 200. A good number of calibration samples per point seems to be in the 16–24 range. With five calibration points, this leads to a total of 80–120 calibration samples.
The functionTet_CalibAddPointbehaves in a manner similar toTet_Start in that it blocks and calls theTet_CallbackFunctionfuncto consume gaze data.
When all calibration points have been displayed by the application program and sampled by the eye tracker, the function Tet_CalibCalculateAndSet must be called to invoke the new calibration.
FunctionTet_CalibGetResultretrieves diagnostic information regarding a par- ticular calibration. If pFileis NULL, results from the current calibration will be returned. Data returned include the target calibration points, the resulting sampled mapped points, and an indication if the calibration point was discarded for some reason (see Listing 10.5 for specification of theSTet_CalibAnalyzeDatadata structure).
The argumentpLenwill be altered by this function to indicate the number of elements returned in pData. If the returned data exceed the initial dimension of pData,pDatawill be filled to its limit, making it possible to reallocatepDatato its true size and reissuing the call toTet_CalibGetResult. IfpFileis not null but a null terminated array of characters containing the path and filename to a personal calibration file saved byTet_CalibSaveToFile, diagnostic (error) information from that calibration will be returned.
The functionTet_CalibSaveToFileprovides the capability to save a calibra- tion run to a file. This way, a returning user may read in the previous calibration
t y p e d e f s t r u c t _ S T e t _ C a l i b A n a l y z e D a t a {
f l o a t t r u e P o i n t X ;
f l o a t t r u e P o i n t Y ;
f l o a t l e f t M a p X ;
f l o a t l e f t M a p Y ;
l o n g l e f t V a l i d i t y ;
f l o a t l e f t Q u a l i t y ;
f l o a t r i g h t M a p X ;
f l o a t r i g h t M a p Y ;
l o n g r i g h t V a l i d i t y ;
f l o a t r i g h t Q u a l i t y ; } S T e t _ C a l i b A n a l y z e D a t a;
Listing 10.5 STet_CalibAnalyzeDatadata structure
via Tet_CalibLoadFromFilewithout having to recalibrate (provided the seating position is roughly the same).
Example:Tet_CalibClear(void);
Example:Tet_CalibLoadFromFile(myCalibration);
Example:Tet_CalibSaveToFile(myCalibration);
Example:Tet_CalibAddPoint(x,y,samples,gazeDataReceiver,NULL,0);
Example:Tet_CalibRemovePoints(TET_EYE_BOTH,x,y,radius);
Example:Tet_CalibGetResult(NULL,pData,255);
Example:Tet_CalibCalculateAndSet();
10.1.5
Tet_SynchronizeTime, Tet_PerformSystemCheckl o n g T e t _ S y n c h r o n i z e T i m e (u n s i g n e d l o n g* pSec ,
u n s i g n e d l o n g* p M i c r o S e c );
l o n g T e t _ P e r f o r m S y s t e m C h e c k (v o i d);
Listing 10.6 Tet_SynchronizeTimeandTet_PerformSystemCheckdeclarations
The functionTet_PerformSystemCheckis used to obtain the current status of the Tobii eye tracking server; it is mainly used to find out if the camera and diodes are attached.
The functionTet_SynchronizeTimesets up the Tobii server’s time module and should enable local routines to convert local timestamps to and from the Tobii server’s timestamps. ArgumentspSecandpMicroSecshould denote the difference between the local (client-side) time and the remote (server-side) time.
Note: Depending on how the client’s and server’s hardware clocks differ, drift causing an error is likely to increase as time goes. If the Tobii server is running
10.1 Linux Tobii Client Application Program Interface 111
on the same host (client-side), this will be detected and handled properly only if the loopback interface was used (IP address 127.0.0.1) to connect. If any other address is used to connect tolocalhost, an unnecessary error will be introduced in the timestamps.
In the Linux environment, as of version v2.8.6, these functions were not fully tested. It seemed, however, that the time obtained viaTet_SynchronizeTimeshould at least be useful in establishing the network lag, assuming the data returned denotes the difference between local and remote hosts. However, this was never fully con- firmed and so should be used with caution.
Example:Tet_SynchronizeTime(&pSec,&pMicroSec);
Example:Tet_PerformSystemCheck();
10.1.6
Tet_GetSerialNumber, Tet_GetLastError, Tet_GetLastErrorAsTextl o n g T e t _ G e t S e r i a l N u m b e r (c h a r* p S e r i a l D i o d e C o n t r o l l e r , c h a r* p S e r i a l C a m e r a );
l o n g T e t _ G e t L a s t E r r o r (v o i d);
l o n g T e t _ G e t L a s t E r r o r A s T e x t (c h a r* p E r r o r );
Listing 10.7 Tet_GetSerialNumber,Tet_GetLastError, andTet_GetLastError AsTextdeclarations
FunctionTet_GetSerialNumberobtains the hardware serial numbers, if present, from the diode controller and the camera. ArgumentspSerialDiodeController andpSerialCameraare null terminated arrays of characters that will never be larger than 64 bytes including the null terminator. Both arrays must be allocated by the caller.
Whenever aTET_ERRORis returned from anyTet_function, a call toTet_Get- LastErrorwill return the specific last error. The error will be overwritten as soon as another error occurs.
Note: TheTet_GetLastErrorfunction was never fully tested in the Linux envi- ronment; functionTet_GetLastErrorAsTextshould be used instead.
Function Tet_GetLastErrorAsText behaves similarly to function Tet_Get- LastErrorexcept the error is copied to argumentpError, a null terminated array of characters that will never require more than 255 bytes.
Example:Tet_GetSerialNumber(SerialDiodeController,SerialCamera);
Example:Tet_GetLastError();
Example:Tet_GetLastErrorAsText(Error);
10.1.7
Tet_CallbackFunctiont y p e d e f v o i d (*T e t _ C a l l b a c k F u n c t i o n)(
E T e t _ C a l l b a c k R e a s o n reason ,
v o i d* pData ,
v o i d* p A p p D a t a );
Listing 10.8 Tet_CallbackFunctiondeclaration
The*Tet_CallbackFunction’sETet_CallbackReasonargument will be set toTET_CALLBACK_GAZE_DATAorTET_CALLBACK_TIMER. The optional argu- ment pAppDatacan point to any user-defined structure, and the argumentpData should be cast to(STet_GazeData *)if the reason for the callback was set to TET_CALLBACK_GAZE_DATA(see Listing 10.9 for specification of theSTet_Gaze- Datadata structure).