UvA facelab 5 extension for Presentation a Presentation IEyeTracker2 interface Filename : UvA EyeTracker Author : B. Molenkamp 1/7
UvA facelab IEyeTracker2 interface for Presentation Installation of the DLL file To install the extension on your computer simply double click the facelab_et2.msi file. The default installation folder is C:\Program Files\Common Files\faceLAB_ET2. The installer will take care of registering the extension with Presentation, so no additional steps are required to start using the eyetracker functionality within your code. In Presentation the extension is registered with the name facelab and should be loaded with the following command: eye_tracker tracker = new eye_tracker( facelab );. The extension uses the TCP/IP or UDP network protocol to communicate with the facelab computer. The current version of facelab 5 starts sending tracking data over TCP/IP once the Start Tracking button is pressed. The current version of the extension was built with the SeeingMachines Coredata SDK version 3.0.2.61534. IEyeTracker2 implementation The UvA interface implements two ways of acquiring data from the eyetracker: a direct mode using the tracker.sendmessage() method to read the latest data from the eyetracker, and the preferred method of acquiring data through the tracker.get_nnn_data() and tracker.last_nnn_data() methods as documented in the Presentation Help Guide. When the eyetracker extension is loaded in the PCL script the extension starts polling the eyetracker hardware for data. After calling tracker.start_data( dt_type ) for a particular data type, Presentation takes care of storing the data. When tracker.start_data( dt_type ) was not called, the extension keeps only the last sample from the eyetracker hardware in memory. Filename : UvA EyeTracker Author : B. Molenkamp 2/7
Sendmessage functions By using the tracker.send_message()method specific data fields can be acquired from the eyetracker: output_value = tracker.send_message( value_type ); output_value is a string which should be converted to the appropriate type: double x; x = double( tracker.send_message( GetFixation_X ) ); Currently the following messages are supported: Message: GetHeadPosition_X GetHeadPosition_Y GetHeadPosition_Z Return value: (double) position of the head in world coordinates (meter) (double) (double) GetHeadPosition_Conf (double) confidence value ranging from 0.0 to 1.0 GetHeadPosition_Time Message: GetPosition_X GetPosition_Y (int) sample time as reported by the tracker (ms from 1-1-1970 GMT) Return value: (int) gaze position on the target surface (pixels) (int) GetPupil_L GetPupil_R (double) pupil diameter in mm (double) GetSaccade* GetFrame GetTime (bool) true when saccade going, false otherwise (int) frame-number of the last data sample (int) time of the last data sample (ms from 1-1-1970 GMT) * saccade data is only available when Track Eyes is checked in the facelab 5 Controls/options window The times returned by the send_message() samples are times as reported by the eye tracker, and are not necessarily synchronous to Presentation time. Polling for eyetracker data fields in PCL code will produce many equal data points, as the sample speed of the tracker is considerably lower than the polling speed. Filename : UvA EyeTracker Author : B. Molenkamp 3/7
The functions above retrieve the latest data sent by the eyetracker. For HeadPositionData the interface can be instructed to store the samples from the eyetracker. The following send_message calls are available in PCL language: StartHeadPosition StopHeadPosition GetHeadPosition, -1 GetHeadPosition, 1 initiates storing of head position data stops adding head position data to the queue returns the number of head position events in the queue retrieves the first head position data element from the queue The maximum number of head position data elements is limited to 65536. When this amount of data events is reached, the interface simply stops storing data. To request the number of elements in the queue, call tracker.send_message( GetHeadPosition, -1 ). The function tracker.send_message( GetHeadPosition, 1 ) retrieves and removes the first element from the queue. The PCL code to use the commands: tracker.send_message( "StartHeadPosition" ); ##### PRESENT TRIAL ##### tracker.send_message( "StopHeadPosition" ); string snumberofevents = tracker.send_message( "GetHeadPosition, -1" ); int nr_events = int( snumberofevents ); loop n = 1; until n > nr_events begin end; out_file.print( tracker.send_message( "GetHeadPosition, 1" ) + "\n" ); n = n + 1; The output produced by the send_message( GetHeadPosition, 1 ) function is always a string with a fixed length, containing the acquisition time of the sample (integer, 10 positions), X, Y and Z positions (double, 6 positions per value), the confidence of the data (double, 6 positions) and the sample Filename : UvA EyeTracker Author : B. Molenkamp 4/7
frame number (integer, 8 positions) separated by single space characters. Retrieve individual measures by using the substring() method on the returned string: double Z_pos = double( tracker.send_message( GetHeadPosition, 1 ).substring( 26, 6) ); Filename : UvA EyeTracker Author : B. Molenkamp 5/7
The built-in Presentation IEyeTracker2 functions The Presentation help file explains how communication between the interface and pcl code should be programmed. The current version supports eye gaze position, pupil diameter, saccade, and blink events as reported by the eyetracker. Selected events will only be available when the eyetracker is set to send these events. The event.time field reports the number of milliseconds since the eyetracker interface was loaded in pcl code ( eye_tracker tracker = new eye_tracker("facelab"); ). This means that the time reported in the event s time field starts at 0 and increases in the pace of the eyetracker s sample clock. eye_tracker tracker = new eye_tracker( "facelab" ); tracker.send_string( "ip: 145.18.151.147" ); tracker.send_string( "port: 3000" ); tracker.send_string( "WorldModelItem: Plane (1)" ); eye_position_data eye_pos; tracker.set_max_buffer_size(dt_position,10000); tracker.start_tracking(); ######## PRESENT TRIAL ######## tracker.start_data( dt_position, false ); tracker.clear_buffer(dt_position); loop int i = 1; until i > tracker.buffer_position( dt_position ) begin eye_pos = tracker.get_position_data( i ); ### do something with your eye-position data ### i = i + 1; end; Filename : UvA EyeTracker Author : B. Molenkamp 6/7
Miscellaneous commands The tracker.send_string() method is used to send properties required to communicate with the eyetracker. The extension communicates through TCP/IP or UDP protocols with the facelab 5 computer. The port and ip address can be set using the send_string() command. TCP/IP requires both a port number and ip-address to be set, UDP only requires the port number. tracker.send_string( "ip: 145.18.151.147" ); sets the IP-address of the eyetracker PC. tracker.send_string( port: 3000 ); sets the port on the target PC to listen to. The target surface for eye-gaze position can be set as follows: tracker.send_string( WorldModelItem: Plane (1) ); This command sets the target surface for which eye gaze position data are calculated. Plane (1) is the name of the target surface as defined in the World - Desk window (Configuration tab -> Label). Filename : UvA EyeTracker Author : B. Molenkamp 7/7