Converting the raw JCT output files to GDF format

The JASTAnalyser program is used to post-process data that is dumped out by the JCT Experimental Software, running either with the EyeLink II hardware and software or without.

The program is run as follows:

JASTAnalyser.exe clientasc serverasc [-options]

• clientasc – the ascii version of the JAST Experimental Software output from the client (or “slave”) subject’s PC
• serverasc – the ascii version of the JAST Experimental Software output from the server (or “master”) subject’s PC#
• options
  • -l (or -L) – the name of a csv-formatted file in which JASTAnalyser will record eye-gaze transfer lag information
  • -s (or -S) – the name of an mpeg file that JASTAnalyser will create; a representation of the world from the server (or “master”) subject’s point of view, with colour-coded event markers
  • -c (or -C) – the name of an mpeg file that JASTAnalyser will create; a representation of the world from the client (or “slave”) subject’s point of view, with colour-coded event markers
  • -f (or -F) – the frame-rate of the output mpegs; defaults to 30
  • -t (or -T) – the name of a temp directory where JASTAnalyser can store jpegs before they are combined into mpeg videos; defaults to the current directory
  • -o (or -O) – the name of the file that JASTAnalyser should dump higher-level analysed data to (such and coincidental gaze, etc.)
  • -g (or -G) – the name of the GDF file that JASTAnalyser should output analysed data to.

An example command line:

JASTAnalyser.exe d:\sample_data\CTEST.asc
    d:\sample_data\STEST.asc -ld:\sample_data\gazelag.csv
    -sd:\sample_data\images\srvrout.mpeg   
    -cd:\sample_data\images\clntout.mpeg -f30 -td:\temp 
    -od:\sample_data\output.dat -gd:\sample_data\test.gdf

JASTAnalyser uses the gd software library for creation of jpegs, and calls an external third-party program called ppmtompeg to join the jpegs into mpeg videos.

The execution of the program is as follows:

1. Search through the clientasc file
   • When the CONFIG_FILE: line is found, load the client configuration file
   • When the SYNCTIME line is found, record the client sync time
   • When the COMMENCING_TRIAL line is found, load the appropriate stimulus set
   • When NEW_PART_INIT lines are encountered, create and initialise the appropriate parts
2. Double-check to make sure the client config file was provided, if not, exit with an error message
3. Search through the serverasc file
   • When the CONFIG_FILE: line is found, load the server configuration file
   • When the SYNCTIME line is found, record the server sync time
   • When the COMMENCING_TRIAL line is found, load the appropriate stimulus set
   • When NEW_PART_INIT lines are encountered, create and initialise the appropriate parts
4. Double-check to make sure the server config file was provided, if not, exit with an error message
5. Double-check to make sure the client and server trial ids and stimulus set filenames are the same, if not then exit with an error message
6. Print out the client and server sync times, and the alignment lag between them
7. If we are outputting the eye-gaze lag, then attempt to open the eye-gaze lag file; if the file open fails, exit with an error message; if it passes, print column headers to the file
8. If we are doing the main output (option -o), then open the specified output file
9. Loop through the clientasc and serverasc files in step, reading one line from each file for each execution of the loop; do the following for each line of either file:
   • Check to see if we have gotten to a point in the data stream where a new video frame should be dumped…if we are dumping video frames, then dump it
   • If this is an eye-gaze line, enqueue the time and eye position; if we have over 100 eye-gaze records stored, delete the oldest one (NOTE: we might actually have to store more than 100 of these to be more accurate)
   • If this is a PT_MV line, move the appropriate part to its new position
   • If this is a PT_ROT line, rotate the appropriate part to its new position
   • If this is a NEW_PART_FROM_BTN line, create the new part in the appropriate location
   • If this is a PT_REMOVE line, delete the appropriate part
   • If this is a PT_JOINT line, join the two specified parts together, and store the new part under the id specified
   • If this is an MP line, check to see if it refers to the position of to subject’s own mouse, or the other subject’s mouse, and record the new mouse position in the global “mouse position” variables
   • If this is an EGP line, enqueue the time and eye position of the other subject; search for a single matching eye-gaze in the other subject’s own eye-gaze queue (single matching here means within 30 milliseconds without other matches within 30 milliseconds), if we find a match, calculate the lag between client and server and record it (if we are recording a lag file); dequeue the oldest time and eye position we have for the other subject
   • If this is an END line, delete all parts (NOTE: JASTAnalyser has not been tested on experiments with more then one trial)
   • If this is a COMMENCING_TRIAL line, load the appropriate stimulus set
   • If this is a NEW_PART_INIT line, create and initialise the new part
   • Check to see if the recorded state has changed, if so, record the state change in the output (option -o) file
10. If we’re recording an mpeg for the client subject: write out the client parameter file for ppmtompeg, run ppmtompeg with the client parameter file as input, delete the client intermediate jpegs from the temp directory
11. If we’re recording an mpeg for the server subject: write out the server parameter file for ppmtompeg, run ppmtompeg with the server parameter file as input, delete the server intermediate jpegs from the temp directory (NOTE: the temp file deletion doesn't seem to be working correctly…)
12. If we’re recording the eye-gaze lag; close the eye-gaze lag file
13. If we’re doing the main output; close the output file
14. Close the clientasc file
15. Close the serverasc file