This is example 11. This example demonstrates the following:

  1. Opening/closing an eye-traking data file

  2. Adding text messages to an eye-traking data file

This example is based on example 10. With additional calls for opening and closing a data file and for adding text messages to the data file.

Source code

Source file: example11.c

processInput()

The following single character commands are implemented here:
q: quit
o: open/close device
f: open/close data file
u: show/hide control window
x: toggle show gui on setup mode
X: toggle show gui on data mode
i: enter idle mode
s: enter setup mode
z: enter data mode
r: start/stop recording
m: toggle show mode-change events

When you press f then eyevec_open_data_file() or eyevec_close_data_file() will be called depending on whether the data file is currently open or not. Also a few text messages will be added to the data file using eyevec_add_data_file_message().

static int processInput(EyeVec* eyevec, ClientData* clientdata, int ch)
{
    .
    .
    .
    else if (ch == 'f') {
        bool datafileisopen;
        err = eyevec_is_data_file_open(eyevec, &datafileisopen); (1)
        if (err) {
            printError("eyevec_is_data_file_open()", err);
        }
        else if (!datafileisopen) {
            err = eyevec_open_data_file(eyevec, "example.bed", 0 (2)
                | EYEVEC_DATA_FILE_RIGHT
                | EYEVEC_DATA_FILE_LEFT
                | EYEVEC_DATA_FILE_MEAN
                | EYEVEC_DATA_FILE_PUPIL (3)
                | EYEVEC_DATA_FILE_CR (3)
                | EYEVEC_DATA_FILE_IRIS (3)
                | EYEVEC_DATA_FILE_GAZE (3)
                | EYEVEC_DATA_FILE_BLINK
                | EYEVEC_DATA_FILE_SACCADE
                | EYEVEC_DATA_FILE_FIXATION
                );
            printError("eyevec_open_data_file()", err);
            if (!err) {
                err = eyevec_add_data_file_message(eyevec, 0, (4)
                    "IGNORE", "Hello World!");
                printError("eyevec_add_data_file_message()", err);
            }
        }
        else {
            err = eyevec_add_data_file_message(eyevec, 0, (4)
                "IGNORE", "Goodbye");
            printError("eyevec_add_data_file_message()", err);

            err = eyevec_close_data_file(eyevec, true); (5)
            printError("eyevec_close_data_file()", err);
        }
    }
    .
    .
    .
}
1 Check if data file is currently open.
2 Open an eye-tracking data file called example.bed[1], defining which optional content include in the file.
3 You generally want to comment these out to keep the data file small.
4 Add custom messages to the data file.
5 Close the eye-tracking data file.

By default eye sample records and/or gaze analysis event records will only be saved to the data file when the eye-tracker is in recording mode (see state diagram). If for some reason you also want save the eye sample and gaze event records when in data mode and drift-check mode (the green circles in the state diagram, then call eyevec_set_eye_data_enabled() and/or eyevec_set_gaze_events_enabled(), like this:

eyevec_set_eye_data_enabled(eyevec, 0, EYEVEC_ENABLE_SAVE_WHILE_IN_DATA_MODE);
eyevec_set_gaze_events_enabled(eyevec, 0, EYEVEC_ENABLE_SAVE_WHILE_IN_DATA_MODE);

Running

After a succesful build run the program:

  1. Press x to call eyevec_set_show_gui_on_setup_mode(). This sets the show-gui-on-setup-mode flag to make the user-interface show on setup mode enter. If however you prefer to keep the user-interface visible at all times while testing press u to call eyevec_show_control_window(). If you don’t want to call eyevec_show_control_window() explicity but do want the user-interface to show when in data mode, press X to call eyevec_set_show_gui_on_data_mode(). This sets the show-gui-on-data-mode flag to make the user-interface show on data mode enter.

  2. Press o to call eyevec_open(). Eye-tracker should go from off mode to idle mode.

  3. Press f to call eyevec_open_data_file() and eyevec_add_data_file_message(). This creates an eye-tracking data file and adds a text message to it (just for demonstation purposes).

  4. Press s to call eyevec_enter_setup_mode(). Eye-tracker should go from idle mode to setup mode and the user-interface should appear. Now perform a baseline measurement and calibration in the user-interface.

  5. In the user-interface press Esc or click Proceed make the eye-tracker go from setup mode to data mode (calling eyevec_enter_data_mode() would also work). The user-interface should disappear (unless you pressed u or X in step 1).

  6. Press r to call eyevec_start_recording(). Eye-tracker should go from data mode to recording mode.

  7. Press r to call eyevec_stop_recording(). Eye-tracker should go from recording mode to data mode.

  8. Press f call eyevec_add_data_file_message() and eyevec_close_data_file(). This add a final text message and closes the data file.

  9. Press q to quit.

Output might look like this (empty lines added for clarity):

eyevec_create_thread(): OK
eyevec_initialize(): OK
Type q to quit, ? for help.

[x]
eyevec_set_show_gui_on_setup_mode(true): OK

[X]
eyevec_set_show_gui_on_data_mode(true): OK

[o]
eyevec_open(): OK
onModeChange:
    eventtime:                  1750667839124898
    oldmode:                    TRACKER_MODE_OFF
    newmode:                    TRACKER_MODE_IDLE

[f]
eyevec_open_data_file(): OK
eyevec_add_data_file_message(): OK

[s]
onModeChange:
    eventtime:                  1750667845434341
    oldmode:                    TRACKER_MODE_IDLE
    newmode:                    TRACKER_MODE_SETUP
eyevec_enter_setup_mode(): OK

onModeChange:
    eventtime:                  1750667847733382
    oldmode:                    TRACKER_MODE_SETUP
    newmode:                    TRACKER_MODE_SETUP_BASELINE
onModeChange:
    eventtime:                  1750667850787151
    oldmode:                    TRACKER_MODE_SETUP_BASELINE
    newmode:                    TRACKER_MODE_SETUP

onModeChange:
    eventtime:                  1750667853224915
    oldmode:                    TRACKER_MODE_SETUP
    newmode:                    TRACKER_MODE_SETUP_CALIBRATION
onModeChange:
    eventtime:                  1750667863844151
    oldmode:                    TRACKER_MODE_SETUP_CALIBRATION
    newmode:                    TRACKER_MODE_SETUP

onModeChange:
    eventtime:                  1750667870844519
    oldmode:                    TRACKER_MODE_SETUP
    newmode:                    TRACKER_MODE_DATA

[r]
eyevec_start_recording(): OK
onModeChange:
    eventtime:                  1750667876364199
    oldmode:                    TRACKER_MODE_DATA
    newmode:                    TRACKER_MODE_RECORDING

[r]
eyevec_stop_recording(): OK
onModeChange:
    eventtime:                  1750667885115133
    oldmode:                    TRACKER_MODE_RECORDING
    newmode:                    TRACKER_MODE_DATA

[f]
eyevec_add_data_file_message(): OK
eyevec_close_data_file(): OK

[q]
eyevec_cleanup(): OK
eyevec_destroy_thread(): OK

Opening the data file before doing a calibration causes the calibration results to be included in the data file. Eye-tracking data (fixation events etc. and eye samples) will be added to the file while the recording is running.

During the course of your experiment you’ll usually want to add text messages at important events such as the start and finish of blocks, trials and stimuli, e.g.:

eyevec_add_data_file_message(eyevec, 0,
    "STIMULUS_START", "trial=10;item_type=CONTROL;item_id=C5");

Here is the data file created in the session: example.bed

To dump the contents of this binary eye-tracking data file in human readable format you can run this command (see also eyevec-dump user manual):

eyevec-dump -all -v=1 example.bed

0                               FILEINFO
    file name:                  example.bed
    create time:                2025-06-23T08:37:23 UTC
    create time [us]:           1750667843058793
    timezone offset [s]:        7200
    file version:               3
    eyevec version:             1.1.0
    help:                       https://www.eyevec.com
0                               MESSAGE IGNORE
    "Hello World!"
4675                            CONFIGURATION
    device model:
    screen width [px]:          1920
    screen height [px]:         1080
    screen width [mm]:          480
.
.
.
42056                           RECORDING_END
47381                           MESSAGE IGNORE
    "Goodbye"

Note, you probably only want to run the eyevec-dump program if the number of records in the file is not too large (let’s say, only if the file size is less than a few Mb). For a large file its best to first run with -v=0 to limit the amount of output.

We can convert the binary eye-tracking data file to CSV format as described in the eyevec-convert user manual).

Using defaults:

eyevec-convert example.bed

This yields: example.csv

Now without saccade events and expressing gaze positions in pixels and making message texts "R-friendly":

eyevec-convert -sac=no -px -r example.bed -out=example-short.csv

This yields: example-short.csv

Including eye sample data (off by default) if present in the bed-file:

eyevec-convert -eye -pp -cr -ir -gz -px -r example.bed -out=example-full.csv

This yields: example-full.csv

1. The file extension "bed" stands for binary EyeVec data.