An eye-tracking data file created by the EyeVec eye-tracking system is a binary file with a bed extension (binary EyeVec data). There are two utilities you can use to access the data in a bed-file:

On this page we provide a list of all possible columns that can appear in the CSV file.

The eyevec-convert program by default generates two seperate rows per eye sample record: one for the right eye and one for the left eye. If desired you can tell eyevec-convert to use wide mode. This causes eye sample records to occupy one row instead of two.

Columns defined in the CSV file

Columns shared by all record types

Column name Description

time

Timestamp [µs, ms or s]. In UTC [µs] if eyevec-convert -utc flag set, otherwise relative to the time the bed-file was created [s or ms depending on -s flag].

type

Record type. One of:
FILEINFO: file info record (i.e. header)
CONFIGURATION: configuration record
EYE: eye sample record
HEAD: head sample record
BLINK_START: blink start event record
BLINK_END: blink end event record
BLINK_UPDATE: blink update event record
SACCADE_START: saccade start event record
SACCADE_END: saccade end event record
FIXATION_START: fixation start event record
FIXATION_END: fixation end event record
FIXATION_UPDATE: fixation update event record
BASELINE_START: baseline procedure start record
BASELINE_END: baseline procedure end record
CALIBRATION_START: calibration procedure start record
CALIBRATION_END: calibration procedure end record
VALIDATION_START: validation procedure start record
VALIDATION_END: validation procedure end record
DRIFT_CHECK_START: drift-check procedure start record
DRIFT_CHECK_END: drift-check procedure end record
RECORDING_START: recording start record
RECORDING_END: recording end record
MESSAGE: text message record

Column shared by eye sample records and event records

Column name Description

side

Eye side. One of:
RIGHT: right eye
LEFT: left eye
MEAN: mean eye (only valid for fixation, saccade, blink)

Columns for eye sample records

In wide mode the following columns are included twice: first with the right_ prefix and then with the left_ prefix.

Column name Description

eye_state

Eye detection state. One of:
NONE: no eye detected
LOST: no eye detected, recently lost
DETECTED: eye detected but not yet considered stable
OPENING: eye detected, visible (pupil) area growing
STEADY: eye detected, visible (pupil) area steady
CLOSING: eye detected, visible (pupil) area shrinking

eye_pxpermm

Resolution in camera pixels per millimeter at estimated or assumed distance [px/mm].

eye_pupil_status

Pupil detection status. One of:
SKIPPED: detection skipped as per settings
REJECTED: detection result rejected
FAILED: detection not succesful
IDLE: no detection performed
DETECTED: detection succesful
UNCERTAIN: detection succesful, position uncertain

eye_pupil_position_x

Pupil center x-position in camera image [px]. Derived from raw position using a linear regression filter.

eye_pupil_position_y

Pupil center y-position in camera image [px]. Derived from raw position using a linear regression filter.

eye_pupil_position_raw_x

Raw pupil center x-position in camera image [px].

eye_pupil_position_raw_y

Raw pupil center y-position in camera image [px].

eye_pupil_area

Visible pupil area [px2].

eye_pupil_visibility

Ratio of area and expected pupil area.

eye_pupil_ellipse_major

Length of semi-major axis of the ellipse fitted onto the pupil edge if applicable [px]. Multiply by 2 to get an estimate of the pupil diameter.

eye_pupil_ellipse_minor

Length of semi-minor axis of the ellipse fitted onto pupil edge if applicable [px]. Will be 0 if no pupil edge ellipse fit is performed.

eye_pupil_ellipse_angle

Angle of the ellipse fitted onto pupil edge if applicable [rad]. Only valid if eye_pupil_ellipse_minor > 0.

eye_cr_status

Corneal reflection detection status. See eye_pupil_status.

eye_cr_position_x

Corneal reflection x-position in camera image [px]. Derived from raw position using a linear regression filter.

eye_cr_position_y

Corneal reflection y-position in camera image [px]. Derived from raw position using a linear regression filter.

eye_cr_position_raw_x

Raw corneal reflection center x-position in camera image [px].

eye_cr_position_raw_y

Raw corneal reflection center y-position in camera image [px].

eye_cr_area

Corneal reflection area [px2].

eye_iris_status

Iris detection status. See eye_pupil_status.

eye_iris_position_x

Iris center x-position in camera image [px].

eye_iris_position_y

Iris center y-position in camera image [px].

eye_iris_ellipse_major

Length of semi-major axis of the ellipse fitted onto the iris edge [px]. Multiply by 2 to get an estimate of the iris diameter.

eye_iris_ellipse_minor

Length of semi-minor axis of the ellipse fitted onto the iris edge [px].

eye_iris_ellipse_angle

Angle of the ellipse fitted onto the iris edge [rad].

eye_iris_a1

Rough indication of the begin angle of nasal side visible iris sector [deg]. Valid range: [-90,90).

eye_iris_a2

Rough indication of the begin angle of nasal side visible iris sector [deg]. Valid range: [-90,90).

eye_iris_a3

Rough indication of the end angle of nasal side visible iris sector [deg]. Valid range: [-90,90), a2 ≥ a1.

eye_iris_a4

Rough indication of the begin angle of temporal side visible iris sector [deg]. Valid range: [90,270).

eye_iris_openness

Vertical iris visibility [0,1].

eye_gaze_status

Gaze estimation status. See eye_pupil_status. Will be SKIPPED, IDLE or DETECTED.

eye_gaze_position_x

Estimated x-position on calibration plane [log, px or mm]. Based on pupil position and/or CR position attributes. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_position_y

Estimated y-position on calibration plane [log, px or mm]. Based on pupil position and/or CR position attributes. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_position_raw_x

Raw estimated x-position on calibration plane [log, px or mm]. Based on pupil position and/or CR position attributes. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_position_raw_y

Raw estimated y-position on calibration plane [log, px or mm]. Based on pupil position and/or CR position attributes. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_position_avg_x

Average estimated x-position on calibration plane [log, px or mm]. Calculated from linear regression line through raw gaze points in the gaze analysis window centered at current frame. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_position_avg_y

Average estimated y-position on calibration plane [log, px or mm]. Calculated from linear regression line through raw gaze points in the gaze analysis window centered at current frame. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

eye_gaze_velocity_x

Horizontal gaze velocity [log/frame, px/frame or mm/frame]. Calculated from linear regression line through raw gaze points in the gaze analysis window centered at current frame. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified. Not valid if ≥ 1000.0.

eye_gaze_velocity_y

Vertical gaze velocity [log/frame, px/frame or mm/frame]. Calculated from linear regression line through raw gaze points in the gaze analysis window centered at current frame. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified. Not valid if eye_gaze_velocity_x ≥ 1000.0.

Columns for head sample records

The current EyeVec eye-tracker software does not generate head samples.
Column name Description

head_x

Position on x-axis (left-right) [mm].

head_y

Position on y-axis (up-down) [mm].

head_z

Position on z-axis (i.e. distance from camera) [mm].

head_yaw

Rotation around y-axis [deg].

head_pitch

Rotation around x-axis [deg].

head_roll

Rotation around z-axis [deg].

Columns for fixation, saccade and blink event records

Column name Description

event_starttime

Start time of fixation, saccade or blink [µs, ms or s]. In UTC [µs] if eyevec-convert -utc flag set, otherwise relative to the time the bed-file was created [s or ms depending on -s flag].

event_endtime

End time (exclusive) of fixation, saccade or blink, or update time of fixation or blink [µs, ms or s]. In UTC [µs] if eyevec-convert -utc flag set, otherwise relative to the time the bed-file was created [s or ms depending on -s flag].

event_updstarttime

Update interval start time of fixation or blink [µs, ms or s]. In UTC [µs] if eyevec-convert -utc flag set, otherwise relative to the time the bed-file was created [s or ms depending on -s flag].

event_gaze_start_x

Gaze x-position at fixation start or saccade start [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_start_y

Gaze y-position at fixation start or saccade start [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_end_x

Gaze x-position at fixation end, fixation update or saccade end [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_end_y

Gaze y-position at fixation end, fixation update or saccade end [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_avg_x

Average gaze x-position during fixation or saccade [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_avg_y

Average gaze y-position during fixation or saccade [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_var_x

Variance of gaze x-position during fixation [log2, px2 or mm2]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_var_y

Variance of gaze y-position during fixation [log2, px2 or mm2]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_updavg_x

Average gaze x-position during fixation update interval [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_updavg_y

Average gaze y-position during fixation update interval [log, px or mm]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_updvar_x

Variance of gaze x-position during fixation update interval [log2, px2 or mm2]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_gaze_updvar_y

Variance of gaze y-position during fixation update interval [log2, px2 or mm2]. The unit depends on whether the eyevec-convert -px flag, -mm flag, or neither was specified.

event_pupil_start

Estimated pupil diameter at fixation start or saccade start [mm].

event_pupil_end

Estimated pupil diameter at fixation start or saccade end [mm].

event_pupil_avg

Average estimated diameter size during fixation or saccade [mm].

event_pupil_var

Variance of estimated diameter size during fixation or saccade [mm].

event_pupil_updavg

Average estimated diameter size during fixation update interval [mm].

event_pupil_updvar

Variance of estimated diameter size during fixation update interval [mm2].

Column for procedure exit status

Column name Description

exit_status

Exit value of baseline, calibration, validation, drift-check procedure or recording. One of:
NONE: status not set
OK: procedure finished succesfully
ABORTED: procedure aborted
FAILED: procedure failed due to unusable data
ERROR: procedure failed due to device error

Columns for text based record types

Column name Description

message_type

String identifying the message type [ASCII]. User defined. Will be empty except for the MESSAGE record type.

message_text

Message text [UTF-8] for the following record types:
FILEINFO
CONFIGURATION
BASELINE_START
BASELINE_END
CALIBRATION_START
CALIBRATION_END
VALIDATION_START
VALIDATION_END
DRIFT_CHECK_START
DRIFT_CHECK_END
RECORDING_START
RECORDING_END
MESSAGE

Contents of the message_text column

For all record types (except MESSAGE) listed under Columns for text based record types the format of the message text is predefined.

If the eyevec_convert program was called without the -r flag the messages are formatted for human consumption. If however the program was called with the -r flag (aka the R-friendly option) the messages are formatted as key-value pairs separated by semicolons. e.g.:

screen_width_px=1920;screen_height_px=1080;...

This allows easy parsing in your analysis scripts. However while parsing:

  • you should accept any order of key-value pairs

  • you should ignore unknown key-value pairs

  • you should be prepared that some key-value pairs might be missing

Key-value pairs in FILEINFO message text

Key name Description

file_name

The name of the original bed-file.

create_time

File creation time in UTC [µs]

timezone_offset

Timezone offset [s]

file_version

Format version of the bed-file.

eyevec_version

EveVec version string.

help

Vendor URL.

Key-value pairs in CONFIGURATION message text

Key name Description

screen_width_px

Screen width [px].

screen_height_px

Screen height [px].

screen_width_mm

Screen width [mm].

screen_height_mm

Screen height [mm].

screen_center_height

Vertical distance from base (desktop) to vertical screen center [mm].

camera_screen_dist

Horizontal distance from camera pivot axis to vertical screen center [mm].

camera_height

Vertical distance from base (desktop) to camera pivot axis [mm].

camera_lens_dist

Euclidian distance from camera pivot axis to camera lens [mm].

subject_distance

Subject distance from camera [mm].

eye_height

Vertical distance from base (desktop) to eye [mm].

position_noise_filter

Pupil and CR position noise suppression filter weight [%].

lr_filter_length

Linear regression filter length [ms].

lr_filter_pupil_threshold

Linear regression filter RMSE threshold for pupil position [px].

lr_filter_cr_threshold

Linear regression filter RMSE threshold for CR position [px].

lr_filter_weight_steepness

Linear regression filter weight function steepness.

eye_features_filter_order

Eye features filter order used for filtering pupil, CR and iris features. 0 means no filtering performed.

gaze_estimation_method

Gaze estimation method. One of:
NONE: don’t estimate gaze
PUPIL_CR: estimate gaze from pupil-CR vector
PUPIL_ONLY: estimate gaze from pupil only
CR_ONLY: estimate gaze from CR only

framerate

Camera frame rate [Hz].

frames_averaged

Number of frames used in moving average.

base_gain

Camera base gain [dB].

duty_cycle

Camera duty-cycle [%].

camera_focal_length_px

Focal length of the camera-lens system [px].

camera_focal_length_mm

Metric focal length of the camera lens [mm].

camera_focal_ratio

Focal ratio (i.e. f-number) of the camera lens.

Key-value pairs in BASELINE_START message text

None.

Key-value pairs in BASELINE_END message text

Key name Description

distance_from_camera

Distance from camera [mm].

interpupillary_dist

Interpupillary distance [mm].

right_iris_diameter

Right iris diameter [mm].

left_iris_diameter

Left iris diameter [mm].

right_pupil_diameter

Right baseline pupil diameter [mm].

left_pupil_diameter

Left baseline pupil diameter [mm].

right_pupil_rmse

Mean right regression line RMSE for pupil [px].

left_pupil_rmse

Mean left regression line RMSE for pupil [px].

right_cr_rmse

Mean right regression line RMSE for CR [px].

left_cr_rmse

Mean left regression line RMSE for CR [px].

Key-value pairs in CALIBRATION_START message text

None.

Key-value pairs in CALIBRATION_END message text

Key name Description

presented_targets

Number of points presented.

skippped

Number of points marked by user to be excluded.

invalid

Number of points marked invalid because data collection failed.

bad

Number of points considered bad.

poor

Number of points considered poor.

fair

Number of points considered fair.

good

Number of points considered good (and not synthetic).

valid

Sum of bad, poor, fair and good.

synthetic_targets

Number of synthetic points used.

error_mean_mean_mm

Mean mean absolute error [mm].

error_mean_max_mm

Mean maximum absolute error [mm].

error_mean_min_mm

Mean minimum absolute error [mm].

error_right_mean_mm

Right mean absolute error [mm].

error_right_max_mm

Right maximum absolute error [mm].

error_right_min_mm

Right minimum absolute error [mm].

error_left_mean_mm

Left mean absolute error [mm].

error_left_max_mm

Left maximum absolute error [mm].

error_left_min_mm

Left minimum absolute error [mm].

error_mean_mean_deg

Mean mean absolute error [deg].

error_mean_max_deg

Mean maximum absolute error [deg].

error_mean_min_deg

Mean minimum absolute error [deg].

error_right_mean_deg

Right mean absolute error [deg].

error_right_max_deg

Right maximum absolute error [deg].

error_right_min_deg

Right minimum absolute error [deg].

error_left_mean_deg

Left mean absolute error [deg].

error_left_max_deg

Left maximum absolute error [deg].

error_left_min_deg

Left minimum absolute error [deg].

Key-value pairs in VALIDATION_START message text

None.

Key-value pairs in VALIDATION_END message text

Key name Description

presented_targets

Number of points presented.

skippped

Number of points marked by user to be excluded.

invalid

Number of points marked invalid because data collection failed.

bad

Number of points considered bad.

poor

Number of points considered poor.

fair

Number of points considered fair.

good

Number of points considered good.

valid

Sum of bad, poor, fair and good.

error_mean_mean_mm

Mean mean absolute error [mm].

error_mean_max_mm

Mean maximum absolute error [mm].

error_mean_min_mm

Mean minimum absolute error [mm].

error_right_mean_mm

Right mean absolute error [mm].

error_right_max_mm

Right maximum absolute error [mm].

error_right_min_mm

Right minimum absolute error [mm].

error_left_mean_mm

Left mean absolute error [mm].

error_left_max_mm

Left maximum absolute error [mm].

error_left_min_mm

Left minimum absolute error [mm].

error_mean_mean_deg

Mean mean absolute error [deg].

error_mean_max_deg

Mean maximum absolute error [deg].

error_mean_min_deg

Mean minimum absolute error [deg].

error_right_mean_deg

Right mean absolute error [deg].

error_right_max_deg

Right maximum absolute error [deg].

error_right_min_deg

Right minimum absolute error [deg].

error_left_mean_deg

Left mean absolute error [deg].

error_left_max_deg

Left maximum absolute error [deg].

error_left_min_deg

Left minimum absolute error [deg].

Key-value pairs in DRIFT_CHECK_START message text

None.

Key-value pairs in DRIFT_CHECK_END message text

Key name Description

result

Status of the drift-check. One of:
SKIPPED: point is marked by user to be excluded
INVALID: data collection failed for this point
BAD: gaze error for this point is classified as bad
POOR: gaze error for this point is classified as poor
FAIR: gaze error for this point is classified as fair
GOOD: gaze error for this point is classified as good

error_mean_mm

Mean Euclidean error [mm].

error_mean_x_mm

Mean x error [mm].

error_mean_y_mm

Mean y error [mm].

error_right_mm

Right Euclidean error [mm].

error_right_x_mm

Right x error [mm].

error_right_y_mm

Right y error [mm].

error_left_mm

Left Euclidean error [mm].

error_left_x_mm

Left x error [mm].

error_left_y_mm

Left y error [mm].

error_mean_deg

Mean Euclidean error [deg].

error_right_deg

Right Euclidean error [deg].

error_left_deg

Left Euclidean error [deg].

window_start

Analysis window start [µs, ms or s]. In UTC [µs] if eyevec-convert -utc flag set, otherwise relative to the time the bed-file was created [s or ms, depending on -s flag].

window_length

Analysis window length [frames].

Key-value pairs in RECORDING_START message text

None.

Key-value pairs in RECORDING_END message text

None.