EyeVecPointi
EyeVecPointf
EyeVecPointd
EyeVecSizei
EyeVecSizef
EyeVecRecti
EyeVecBoundingBoxi
EyeVecEllipse
EyeVecEllipseShape
EyeVecThumbnail
EyeVecMarker
EyeVecEyeBox
EyeVecPupil
EyeVecCR
EyeVecIris
EyeVecGaze
EyeVecEye
EyeVecEyeFull
EyeVecImage
EyeVecLogicalTargetPosition
EyeVecTargetState
EyeVecBaselineResult
EyeVecCalibrationResult
EyeVecDriftCheckResult
EyeVecCalibrationPointResult
EyeVecIndexPair
EyeVecTestScreenInfo
EyeVecDisplayEventData
EyeVecModeChangeEventData
EyeVecEyeSampleEventData
EyeVecBlinkEventData
EyeVecSaccadeEventData
EyeVecFixationEventData
EyeVecTestItemEventData
EyeVecEvent
EyeVec

Details

EyeVecPointi

Integer point struct [px].

typedef struct _EyeVecPointi {
    int x;
    int y;
} EyeVecPointi;
Field Description

x

X-position [px]

y

Y-position [px]

EyeVecPointf

Float point struct [px].

typedef struct _EyeVecPointf {
    float x;
    float y;
} EyeVecPointf;
Field Description

x

X-position [px]

y

Y-position [px]

EyeVecPointd

Double point struct [px].

typedef struct _EyeVecPointd {
    double x;
    double y;
} EyeVecPointd;
Field Description

x

X-position [px]

y

Y-position [px]

EyeVecSizei

Integer size struct [px].

typedef struct _EyeVecSizei {
    int width;
    int height;
} EyeVecSizei;
Field Description

width

Width [px]

height

Height [px]

EyeVecSizef

Float size struct [px].

typedef struct _EyeVecSizef {
    float width;
    float height;
} EyeVecSizef;
Field Description

width

Width [px]

height

Height [px]

EyeVecRecti

Integer rect struct [px].

typedef struct _EyeVecRecti {
    EyeVecPointi position;
    EyeVecSizei size;
} EyeVecRecti;
Field Description

position

Position of upper-left corner

size

Size

EyeVecBoundingBoxi

Integer bounding box struct [px].

typedef struct _EyeVecBoundingBoxi {
    EyeVecPointi min;
    EyeVecPointi max;
} EyeVecBoundingBoxi;
Field Description

min

Position of upper-left corner

max

Position of lower-right corner

EyeVecEllipse

Ellipse struct.

typedef struct _EyeVecEllipse {
    EyeVecPointf center;
    float major;
    float minor;
    float angle;
} EyeVecEllipse;
Field Description

center

Ellipse center

major

Length of the semi-major axis [px]

minor

Length of semi-minor axis [px]

angle

Angle of major axis [rad]

EyeVecEllipseShape

Ellipse shape struct (i.e. ellipse without center).

typedef struct _EyeVecEllipseShape {
    float major;
    float minor;
    float angle;
} EyeVecEllipseShape;
Field Description

major

Length of the semi-major axis [px]

minor

Length of semi-minor axis [px]

angle

Angle of major axis [rad]

EyeVecThumbnail

Thumbnail data struct. If face blob detection is not enabled no image will be available and all other fields will be zero.

typedef struct _EyeVecThumbnail {
    float right;
    float left;
    float width;
    float center;
    float split;
    float yspan[2];
    float saturationratio;
} EyeVecThumbnail;
Field Description

right

Estimate of the right side (relative to full image) of the face blob

0 means left side of image, 1 means right side of image. If this is close to or greater than 1 then the face is far to the right in camera image. If this is 0 then no face blob was detected or thumbnail detection is disabled.

left

Estimate of the left side (relative to full image) of the face blob

0 means left side of image, 1 means right side of image. If this is close to or less than 0 then the face is far to the left in camera image.

Available iff thumbright > 0.

width

Average width of detected face blob

This is the average difference between right and left.

Available iff thumbright > 0.

center

Estimate of the horizontal center (relative to full image) of the face blob

0 means left side of image, 1 means right side of image.

Available iff thumbright > 0.

split

Adjusted estimate of the horizontal center (relative to full image) of the face blob

0 means left side of image, 1 means right side of image. This indicates the right/left split position used.

Available iff thumbright > 0.

yspan

Probable eye locations in vertical direction

0 means top side of image, 1 means bottom side of image. Consists of one or two values (0 means not defined). The first value identifies the most strongest location. Combined with the horizontal split these values roughy define the area(s) possibly containing the eyes.

Available iff thumbright > 0 and yspan[0] > 0.

saturationratio

Ratio of (almost) saturated thumbnail pixels over the thumbnail area [%]

EyeVecMarker

Marker data struct.

typedef struct _EyeVecMarker {
    int available;
    EyeVecPointf position[1+8];
    EyeVecBoundingBoxi boundingbox;
    EyeVecEllipse ellipse;
    float neutraldot;
    int sharpness;
    int maxsharpness;
} EyeVecMarker;
Field Description

available

Set (1) if marker detected; cleared (0) if marker detection disabled, not detected or lost; negative if not detected but not yet considered lost.

Other fields in this struct are only valid if available != 0.

position

Detected marker dots

Index 0 represents the center dot, indexes 1..7 represent the satellite dots, index 8 represents the missing satellite dot.

boundingbox

Bounding box around the satellite dots

ellipse

Ellipse fitted on the satellite dots

neutraldot

Fractional marker dot index indicating the neutral (i.e. horizontal) line determined on baseline measurement

sharpness

Marker sharpness indication [0,100+]

This value is to be displayed as a bar during camera focus calibration. With marker at desired subject distance the camera focus ring should be adjusted to make maximize the bar length. Value might occasionaly exceed 100, but generally will stay be below 100.

maxsharpness

Maximum value of determined marker sharpness

Value is the maximum of all sharpness values since the most recent camera start.

EyeVecEyeBox

Eyebox struct defined by center and size.

typedef struct _EyeVecEyeBox {
    EyeVecEyeBoxState state;
    EyeVecPointf position;
    EyeVecSizef size;
} EyeVecEyeBox;
Field Description

state

Eyebox state

This basically indicates what generated this eyebox.

position

Eyebox center

size

Eyebox size

EyeVecPupil

Pupil data struct. Fields are ony valid if status is EYEVEC_EYE_STATUS_DETECTED or above.

typedef struct _EyeVecPupil {
    EyeVecEyeStatus status;
    EyeVecPointf position;
    EyeVecPointf position_raw;
    float area;
    float visibility;
    EyeVecEllipseShape ellipse;
} EyeVecPupil;
Field Description

status

Pupil detection status

position

Pupil center position in camera image

Relative to full image.

position_raw

Raw pupil center position in camera image

Relative to full image.

area

Visible pupil area [px2]

Divide by squared resolution [px/mm] to get pupil area in mm2. See EyeVecEye or EyeVecEyeFull about resolution.

Note, This does not account for the case where the corneal reflection obscures part of the pupil.

visibility

Ratio of area and expected pupil area

ellipse

Ellipse fitted to pupil edge if applicable

Divide ellipse.major by resolution [px/mm] to get pupil radius in mm. See EyeVecEye or EyeVecEyeFull about resolution.

Note, if no ellipse fit has been done due to a too low pupil visibility or if not requested, then ellipse.major will have a value calculated from area, and ellipse.minor and ellipse.angle will be 0.

EyeVecCR

Corneal reflection data struct. Fields are ony valid if status is EYEVEC_EYE_STATUS_DETECTED or above.

typedef struct _EyeVecCR {
    EyeVecEyeStatus status;
    EyeVecPointf position;
    EyeVecPointf position_raw;
    float area;
} EyeVecCR;
Field Description

status

Corneal reflection detection status

position

Corneal reflection center position in camera image

Relative to full image.

position_raw

Raw corneal reflection center position in camera image

Relative to full image.

area

Corneal reflection area [px2]

EyeVecIris

Iris data struct. Fields are ony valid if status is EYEVEC_EYE_STATUS_DETECTED or above.

typedef struct _EyeVecIris {
    EyeVecEyeStatus status;
    EyeVecPointf position;
    EyeVecEllipseShape ellipse;
    float a1;
    float a2;
    float a3;
    float a4;
    float openness;
} EyeVecIris;
Field Description

status

Iris detection status

position

Iris center position in camera image

Relative to full image.

ellipse

Ellipse fitted to iris edge

a1

Rough indication of the begin angle of nasal side visible iris sector [deg]

Valid range: [-90,90).

a2

Rough indication of the end angle of nasal side visible iris sector [deg]

Valid range: [-90,90), a2 ≥ a1.

a3

Rough indication of the begin angle of temporal side visible iris sector [deg]

Valid range: [90,270).

a4

Rough indication of the end angle of temporal side visible iris sector [deg]

Valid range: [90,270), a4 ≥ a3.

openness

Vertical iris visibility [0,1]

Assume eye is (almost) closed if openness is < 0.2.

EyeVecGaze

Gaze data struct. Fields are ony valid if status is EYEVEC_EYE_STATUS_DETECTED or above.

typedef struct _EyeVecGaze {
    EyeVecEyeStatus status;
    EyeVecPointf position;
    EyeVecPointf position_raw;
    EyeVecPointf position_avg;
    EyeVecPointf velocity;
} EyeVecGaze;
Field Description

status

Gaze estimation status

position

Estimated logical gaze position on calibration plane

Based on pupil position and/or cr position attributes. Relative to calibration plane (i.e. the screen defined in setup). Multiply by screen size in pixels or millimeters to convert to real-world coordinates.

position_raw

Raw estimated logical gaze position on calibration plane

Based on pupil position_raw and/or cr position_raw attributes. Relative to calibration plane (i.e. the screen defined in setup). Multiply by screen size in pixels or millimeters to convert to real-world coordinates.

position_avg

Average logical horizontal and vertical gaze position on calibration plane

Calculated from linear regression line through raw gaze points in the gaze analysis window centered at current frame. Multiply by screen size in pixels or millimeters to convert to real-world coordinates.

Not valid if velocity.x == 1000.0f.

Note, the calculation of this data is non-causal. It will therefore only be available online if output is delayed for one half of the gaze analysis window length or more.

velocity

Logical horizontal and vertical gaze velocities [/frame]

Calculated from linear regression lines through raw gaze points in the gaze analysis window centered at current frame. Multiply by screen size in pixels or millimeters to convert to real-world velocity in px/frame or mm/frame.

Not valid if velocity.x == 1000.0f.

To calculate magnitude make sure x- and y-velocity are on the same scale, so do:
   velocity[log/frame] = sqrt(v.x2 + (v.y*height/width)2)
or
   velocity[(px or mm)/frame] = sqrt((v.x*width)2 + (v.y*height)2)

Note, the calculation of this data is non-causal. It will therefore only be available online if output is delayed for one half of the gaze analysis window length or more.

EyeVecEye

Eye data struct.

typedef struct _EyeVecEye {
    EyeVecPupil pupil;
    EyeVecCR cr;
    EyeVecIris iris;
    EyeVecGaze gaze;
    EyeVecEyeState state;
    float pxpermm;
} EyeVecEye;
Field Description

pupil

Pupil detection data

A pupil.status of EYEVEC_EYE_STATUS_SKIPPED means the detection of concerned eye was skipped as per settings.

cr

Corneal reflection detection data

iris

Iris detection data

gaze

Gaze estimation data

state

Eye detection state

pxpermm

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

Use this value to calculate the pupil size or iris size in millimeters.

To get the estimated distance from eyes or forehead marker to camera lens in milimeters divide the focal-length[px] by the resolution[px/mm]:
  estimated-distance[mm] = focal-length[px] / resolution[px/mm]

To get the relative distance divide the estimated distance[mm] by the reference distance[mm]:
  relative-distance = estimated-distance[mm] / reference-distance[mm]
where the reference-distance is given by the baseline measurement.

EyeVecEyeFull

Eye data struct with pupil and iris edge points.

typedef struct _EyeVecEyeFull {
    EyeVecPupil pupil;
    EyeVecCR cr;
    EyeVecIris iris;
    EyeVecGaze gaze;
    EyeVecEyeState state;
    float pxpermm;
    int npupilpoints;
    EyeVecPointf pupilpoints[EYEVEC_MAX_PUPIL_POINTS];
    EyeVecPointf pupilcenter;
    int nirispoints;
    EyeVecPointf irispoints[EYEVEC_MAX_IRIS_POINTS];
} EyeVecEyeFull;
Field Description

pupil

Pupil detection data

A pupil.status of EYEVEC_EYE_STATUS_SKIPPED means the detection of concerned eye was skipped as per settings.

cr

Corneal reflection detection data

iris

Iris detection data

gaze

Gaze estimation data

state

Eye detection state

pxpermm

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

Use this value to calculate the pupil size or iris size in millimeters.

To get the estimated distance from eyes or forehead marker to camera lens in milimeters divide the focal-length[px] by the resolution[px/mm]:
estimated-distance[mm] = focal-length[px] / resolution[px/mm]

To get the relative distance divide the estimated distance [mm] by the reference distance [mm]:
relative-distance = estimated-distance[mm] / reference-distance[mm]
where the reference-distance is given by the baseline measurement.

npupilpoints

Number of valid pupil edge points detected

Can be 0 if not determined or on detection failure.

pupilpoints

Array of pupil edge points

Relative to pupilcenter.

pupilcenter

Reference pupil center position in camera image

Relative to full image. This is a copy of pupil.position_raw.

nirispoints

Number of valid iris edge points detected

Can be 0 if not determined or on detection failure.

irispoints

Array of iris edge points

Relative to iris.position.

EyeVecImage

Image struct.

typedef struct _EyeVecImage {
    EyeVecSizei size;
    int stride;
    int pixeloffset;
    const uint8_t* pixels;
} EyeVecImage;
Field Description

size

Size

Empty if image not available.

stride

Offset between image rows [px]

pixeloffset

internal use only

pixels

Pixel data

NULL if image not available

EyeVecLogicalTargetPosition

Logical target position with ID.

typedef struct _EyeVecLogicalTargetPosition {
    unsigned int id;
    EyeVecPointf position;
} EyeVecLogicalTargetPosition;
Field Description

id

ID of target

See EyeVecTargetId for built-in target IDs.

position

Logical position of calibration target [0,1]

EyeVecTargetState

Target presentation state.

typedef struct _EyeVecTargetState {
    EyeVecProcedureType proctype;
    EyeVecTargetPhase phase;
    EyeVecTargetPhase prevphase;
    int duration;
    int offset;
    int64_t frametime;
    int64_t procstarttime;
    int64_t trialstarttime;
    int64_t phasestarttime;
    int64_t wakeupstarttime;
    int64_t wakeupendtime;
    EyeVecPointd position;
    double focussize;
    int number;
    bool prepare;
    bool startsymbol;
    bool showsymbol;
    bool rotatesymbol;
    bool running;
} EyeVecTargetState;
Field Description

proctype

Current procedure type

phase

Current target presentation phase

prevphase

Previous target presentation phase

duration

Duration rounded to multiple of refresh interval [µs]

Will be negative (meaning undefined) for attention phase if self-paced.

offset

Current time offset in phase [µs], runs from 0 to duration (exclusive)

During a phase this offset may occasionally jump back to 0 on eye-loss (e.g. during a blink). Will be negative for attention phase if self-paced.

frametime

Specified display frame time at target update call [µs]

procstarttime

Data collection procedure start display frame time [µs]

trialstarttime

Display frame time at start of current trial [µs]

phasestarttime

Display frame time at start of current phase in trial [µs]

wakeupstarttime

Display frame time at start of current wake-up

wakeupendtime

Timeout value for wake-up target

The wake-up target should be visible if wakeupendtime > 0 and frametime < wakeupendtime. Special value -1 signals the graphics update logic to begin the wake-up interval. Special value -2 it means wake-up is disabled.

position

Target position [logical]

focussize

If > 0 then a focus indicator is to be displayed

Will only be used for the baseline procedure

number

Unique item number

For text and image stimuli this is the index in the text or image item list.

prepare

If set, prepare stimulus presentation

startsymbol

If set, start display of target symbol

Implies showsymbol.

showsymbol

If set, show target symbol

rotatesymbol

If set, rotate target symbol, if shown, by 45 degrees

running

Set while target presentation procedure is running

EyeVecBaselineResult

Baseline procedure result (summary).

typedef struct _EyeVecBaselineResult {
    bool havedata;
    bool haveeye[2];
    float distance;
    float ipd;
    float irissize[2];
    float pupilsize[2];
    EyeVecPointf pupilrmse[2];
    EyeVecPointf crrmse[2];
} EyeVecBaselineResult;
Field Description

havedata

If set, then baseline data are available

If not set, then none of the attributes below are defined (will all be zeroed).

haveeye

Flags indicating whether right(0)/left(1) eye data is present

distance

Distance from camera [mm]

0 means not determined.

ipd

Interpupillary distance [mm]

0 means not determined.

irissize

Right(0)/left(1) iris diameter [mm]

0 means not determined.

pupilsize

Right(0)/left(1) baseline pupil diameter [mm]

0 means not determined.

pupilrmse

Mean right(0)/left(1) regression line RMSE for pupil [px]

0 means not determined.

crrmse

Mean right(0)/left(1) regression line RMSE for corneal reflection [px]

0 means not determined.

EyeVecCalibrationResult

Calibration/validation procedure result (summary). For calibration this refers to retrospective gaze mapping errors. For validation this refers to deviation from target positions.

typedef struct _EyeVecCalibrationResult {
    bool havedata;
    bool haveeye[3];
    int npoints;
    int npointsskipped;
    int npointsinvalid;
    int npointsbad;
    int npointspoor;
    int npointsfair;
    int npointsgood;
    int npointssynthetic;
    float mean_mm[3];
    float sd_mm[3];
    float min_mm[3];
    float max_mm[3];
    float mean_deg[3];
    float sd_deg[3];
    float min_deg[3];
    float max_deg[3];
} EyeVecCalibrationResult,
  EyeVecValidationResult;
Field Description

havedata

If set, then calibration/validation data are available

If not set, then none of the attributes below are defined (will all be zeroed).

haveeye

Flags indicating whether right(0)/left(1)/mean(2) data is present

npoints

Number of points presented

The sum of npointsskipped, npointsinvalid, npointsbad, npointspoor, npointsfair, npointsgood will yield the same number.

npointsskipped

Number of points marked by user to be excluded

If all points where skipped the result was ignored.

npointsinvalid

Number of points marked invalid because data collection failed

If this is > 0 the result was ignored.

npointsbad

Number of points considered bad

npointspoor

Number of points considered poor

npointsfair

Number of points considered fair

npointsgood

Number of points considered good (and not synthetic)

npointssynthetic

Number of synthetic points used. Only applies to calibration

mean_mm

Right(0)/left(1)/mean(2) mean absolute error [mm]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

sd_mm

Right(0)/left(1)/mean(2) standard deviation [mm]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

min_mm

Right(0)/left(1)/mean(2) minimum absolute error [mm]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

max_mm

Right(0)/left(1)/mean(2) maximum absolute error [mm]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

mean_deg

Right(0)/left(1)/mean(2) mean absolute error [deg]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

sd_deg

Right(0)/left(1)/mean(2) standard deviation [deg]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

min_deg

Right(0)/left(1)/mean(2) minimum absolute error [deg]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

max_deg

Right(0)/left(1)/mean(2) maximum absolute error [deg]

Only defined if corresponding haveeye flag set. Only reflects points marked good, fair, poor and bad.

EyeVecDriftCheckResult

Drift-check procedure result (summary).

typedef struct _EyeVecDriftCheckResult {
    bool havedata;
    bool haveeye[3];
    EyeVecTargetStatus status;
    EyeVecPointf error_mm[3];
    EyeVecPointf error_deg[3];
} EyeVecDriftCheckResult;
Field Description

havedata

If set, then drift-check data are available

If not set, then none of the attributes below are defined (will all be zeroed).

haveeye

Flags indicating whether right(0)/left(1)/mean(2) data is present

status

Status of the drift-check: invalid, bad, poor, fair or good

error_mm

Right(0)/left(1)/mean(2) x and y error [mm]

Only defined if status is bad, poor, fair or good, and corresponding haveeye flag set.

error_deg

Right(0)/left(1)/mean(2) x and y error [deg]

Only defined if status is bad, poor, fair or good, and corresponding haveeye flag set.

EyeVecCalibrationPointResult

Calibration/validation/drift-check point result. For calibration the error and sd values refer to the retrospective gaze mapping error.

typedef struct _EyeVecCalibrationPointResult {
    bool havedata;
    EyeVecTargetStatus status;
    bool dummy;
    bool haveeye[2];
    EyeVecPointf target;
    int64_t windowstart;
    int windowlength;
    EyeVecPointf eye[2];
    EyeVecPointf gaze[2];
    EyeVecPointf error_mm[3];
    EyeVecPointf sd_mm[3];
    EyeVecPointf error_deg[3];
    EyeVecPointf sd_deg[3];
    EyeVecPointf pupilrmse[2];
    EyeVecPointf crrmse[2];
} EyeVecCalibrationPointResult,
  EyeVecValidationPointResult,
  EyeVecDriftCheckPointResult;
Field Description

havedata

If set, then data are available

If not set, then none of the attributes below are defined (will all be zeroed).

status

Status indicating whether the point is skipped, invalid, bad, poor, fair or good

There will only be position data for non-dummy points marked good, fair, poor or bad.

dummy

If set, this point was not part of the calibration pattern

After calibration, the data for this point may be synthetic (derived from other calibration points). Note, only calibration points can be dummies (have synthetic data).

haveeye

Flags indicating whether right(0)/left(1) data is present

target

Position of target on test screen [mm]

windowstart

Analysis window start time [µs]

This identifies the start of the analysis window during a target presentation where the eye-vector variance is the lowest. Only defined if good, fair, poor or bad. Not set for dummy points.

windowlength

Analysis window length [frames]

eye

Mean right(0)/left(1) raw eye vector in camera image [px]

Only defined if good, fair, poor or bad and corresponding haveeye flag set.

gaze

Right(0)/left(1) gaze position on test screen [mm]

Only defined if good, fair, poor or bad and corresponding haveeye flag set.

Calculated from eye vector (above) by applying current gaze mapping. For calibration points the difference between gaze and target defines the retrospective gaze mapping error.

error_mm

Right(0)/left(1)/mean(2) gaze error [mm]

Only defined if good, fair, poor or bad and !dummy and corresponding haveeye flag(s) set.

sd_mm

Right(0)/left(1)/mean(2) gaze standard deviation [mm]

Only defined if good, fair, poor or bad and !dummy and corresponding haveeye flag(s) set.

error_deg

Right(0)/left(1)/mean(2) gaze error [deg]

Only defined if good, fair, poor or bad and !dummy and corresponding haveeye flag(s) set.

sd_deg

Right(0)/left(1)/mean(2) gaze standard deviation [deg] Only defined if good, fair, poor or bad and !dummy and corresponding haveeye flag(s) set.

pupilrmse

Mean right(0)/left(1) regression line RMSE for pupil [px]

0 means not determined.

crrmse

Mean right(0)/left(1) regression line RMSE for corneal reflection [px]

0 means not determined.

EyeVecIndexPair

Indexes of two neighboring calibration points.

typedef struct _EyeVecIndexPair {
    int index1;
    int index2;
} EyeVecIndexPair;
Field Description

index1

Index of point 1 iff ≥ 0, or -1

index2

Index of point 2 iff ≥ 0, or -1

EyeVecTestScreenInfo

Test screen size and refresh interval.

typedef struct _EyeVecTestScreenInfo {
    EyeVecSizei size_px;
    EyeVecSizei size_mm;
    double refreshinterval;
} EyeVecTestScreenInfo;
Field Description

size_px

Test screen size [px]

size_mm

Test screen [mm]

refreshinterval

Refresh interval [s]

EyeVecDisplayEventData

Display data struct.

typedef struct _EyeVecDisplayEventData {
    int load;
    int frcount;
    EyeVecRecti viewport;
    EyeVecRecti roi;
    EyeVecThumbnail thumbnail;
    EyeVecMarker marker;
    EyeVecRecti scanbox1;
    EyeVecRecti scanbox2;
    EyeVecEyeBox eyebox[2];
    EyeVecEyeFull eye[2];
    float distance;
    float pxpermm;
    float pupilpeak[2];
    float pupilthreshold[2];
    float irispeak[2];
    float iristhreshold[2];
    EyeVecImage eyeimage[2];
    EyeVecImage thumbimage;
    EyeVecImage mainimage;
} EyeVecDisplayEventData;
Field Description

load

Processing time divided by frame interval [%]; averaged

frcount

Frame counter set on image capture

viewport

Offset and size of camera viewport

When necessary the viewport offset will be adjusted during eye-tracking. The viewport size is fixed for each frame rate.

roi

Offset and size of ROI in viewport

thumbnail

Thumbnail data

marker

Marker data. Position is relative to full image

scanbox1

Scanbox 1 defined when trying to find lost eye(s)

If not defined scanbox width will be 0. Position is relative to camera viewport.

scanbox2

Scanbox 2 defined when trying to find lost eye(s)

If not defined scanbox width will be 0. Position is relative to camera viewport.

eyebox

Right(0)/left(1) eyebox

If not defined eyebox state will be EYEVEC_EYEBOX_STATE_NONE. Position is relative to full image.

eye

Right(0)/left(1) eye data

Positions are relative to full image.

distance

Estimated distance from eyes or forehead marker to camera lens [mm]

pxpermm

Camera pixels per millimeter at estimated distance [px/mm]

pupilpeak

Right(0)/left(1) pupil peak level

This identifies the first peak in the eye histogram, where the histogram is calculated over the area containing the pupil and part of the iris.

pupilthreshold

Right(0)/left(1) pupil threshold level

This identifies the dip following the first peak in the eye histogram.

irispeak

Right(0)/left(1) iris peak level

This identifies the second peak in the eye histogram. Will be 0 if not defined.

iristhreshold

Right(0)/left(1) iris threshold level

This identifies the dip following the second peak in the eye histogram. Will be 0 if not defined.

eyeimage

Right(0)/left(1) eye image

If not defined, attributes will be 0.

thumbimage

Thumbnail image

If not defined, attributes will be 0.

mainimage

Main image containing ROI (option 1) or full viewport image (option 2)

If width exceeds roi.size.width or height exceeds roi.size.height then option 2 applies and `mainimg is the full viewport image, otherwise option 1 applies and mainimg is the ROI image and size will match roi.size. See viewport and roi above. If not defined, attributes will be 0.

EyeVecModeChangeEventData

Data for event id EYEVEC_EVENT_MODE_CHANGE.

typedef struct _EyeVecModeChangeEventData {
    EyeVecTrackerMode newmode;
    EyeVecTrackerMode oldmode;
    EyeVecExitStatus exitstatus;
    int deviceerror;
} EyeVecModeChangeEventData;
Field Description

newmode

New operating mode

oldmode

Old operating mode

exitstatus

Exit value of baseline, calibration, validation or drift-check procedure or recording (set when leaving corresponding mode)

Also used to indicate user wants to proceed with experiment when going from setup mode to data mode. To test this:
exitstatus == EYEVEC_EXIT_STATUS_OK &&
newmode == EYEVEC_TRACKER_MODE_DATA &&
oldmode == EYEVEC_TRACKER_MODE_SETUP

deviceerror

Device error level

0: OK,
1: suddenly disconnected,
2: error (bad cable?),
3: camera too hot

EyeVecEyeSampleEventData

Data for event id EYEVEC_EVENT_EYE_DATA.

typedef struct _EyeVecEyeSampleEventData {
    int side;
    EyeVecEye eye[2];
} EyeVecEyeSampleEventData;
Field Description

side

Bitmask defining which eye data present

Bit 0: EYEVEC_RIGHT_EYE, bit 1: EYEVEC_LEFT_EYE

eye

Right(0)/left(1) eye data

EyeVecBlinkEventData

Data for event id EYEVEC_EVENT_BLINK_START, EYEVEC_EVENT_BLINK_END and

EYEVEC_EVENT_BLINK_UPDATE.

typedef struct _EyeVecBlinkEventData {
    int64_t starttime;
    int64_t endtime;
    int64_t updatestarttime;
    int side;
} EyeVecBlinkEventData;
Field Description

starttime

Blink start time [µs]

endtime

Blink end time (exclusive) or blink update time [µs]

For EYEVEC_EVENT_BLINK_START: Not used, always 0.

For EYEVEC_EVENT_BLINK_END: Blink end time if > 0 (exclusive). Special values: 0 means blink timed out; -1 means blink lost.

For EYEVEC_EVENT_BLINK_UPDATE: End time of current update interval (exclusive) and also start time of the next update interval (inclusive).

updatestarttime

Blink update interval start time [µs]

side

Which eye: EYEVEC_RIGHT_EYE, EYEVEC_LEFT_EYE or EYEVEC_MEAN_EYE

EyeVecSaccadeEventData

Data for event id EYEVEC_EVENT_SACCADE_START and EYEVEC_EVENT_SACCADE_END.

typedef struct _EyeVecSaccadeEventData {
    int64_t starttime;
    int64_t endtime;
    EyeVecPointf gaze_start;
    EyeVecPointf gaze_end;
    EyeVecPointf gaze_avg;
    float pupil_start;
    float pupil_end;
    float pupil_avg;
    int side;
} EyeVecSaccadeEventData;
Field Description

starttime

Saccade start time [µs].

endtime

Saccade end time (exclusive) [µs]

For EYEVEC_EVENT_SACCADE_START: Not used, always 0.

For EYEVEC_EVENT_SACCADE_END: Saccade end time if ≥ 0 (exclusive). Special values: -1 means saccade lost.

gaze_start

Logical gaze position at saccade start

This is a linear regression based average of the estimated gaze position at starttime.

gaze_end

Logical gaze position at saccade end

For EYEVEC_EVENT_SACCADE_START: Copy of gaze_start.

For EYEVEC_EVENT_SACCADE_END: Linear regression based average of the estimated gaze position at endtime minus one frame duration.

gaze_avg

Average logical gaze position during saccade

For EYEVEC_EVENT_SACCADE_START: Copy of gaze_start.

For EYEVEC_EVENT_SACCADE_END: Average of the linear regression based averages of the estimated gaze position.

pupil_start

Estimated pupil diameter at saccade start [mm]

This is the estimated pupil diameter at starttime.

If possible length of the major axis of the estimated pupil ellipse will be used. Otherwise the the diameter will be based on detected pupil area.

pupil_end

Estimated pupil diameter at saccade end [mm]

For EYEVEC_EVENT_SACCADE_START: Copy of pupil_start.

For EYEVEC_EVENT_SACCADE_END: Estimated pupil diameter at endtime minus one frame duration.

pupil_avg

Average estimated pupil diameter during saccade [mm]

For EYEVEC_EVENT_SACCADE_START: Copy of pupil_start.

For EYEVEC_EVENT_SACCADE_END: Average of the estimated pupil diameters.

side

Which eye: EYEVEC_RIGHT_EYE, EYEVEC_LEFT_EYE or EYEVEC_MEAN_EYE

EyeVecFixationEventData

Data for event id EYEVEC_EVENT_FIXATION_START, EYEVEC_EVENT_FIXATION_END and EYEVEC_EVENT_FIXATION_UPDATE.

typedef struct _EyeVecFixationEventData {
    int64_t starttime;
    int64_t endtime;
    int64_t updatestarttime;
    EyeVecPointf gaze_start;
    EyeVecPointf gaze_end;
    EyeVecPointf gaze_avg;
    EyeVecPointf gaze_var;
    EyeVecPointf gaze_updavg;
    EyeVecPointf gaze_updvar;
    float pupil_start;
    float pupil_end;
    float pupil_avg;
    float pupil_var;
    float pupil_updavg;
    float pupil_updvar;
    int side;
} EyeVecFixationEventData;
Field Description

starttime

Fixation start time [µs]

endtime

Fixation end time (exclusive) or fixation update time [µs]

For EYEVEC_EVENT_FIXATION_START: Not used, always 0.

For EYEVEC_EVENT_FIXATION_END: Fixation end time if ≥ 0 (exclusive). Special values: -1 means fixation lost.

For EYEVEC_EVENT_FIXATION_UPDATE: End time of current update interval (exclusive) and also start time of the next update interval (inclusive).

updatestarttime

Fixation update interval start time [µs]

gaze_start

Logical gaze position at fixation start

This is a linear regression based average of the estimated gaze position at starttime.

gaze_end

Logical gaze position at fixation end or fixation update

For EYEVEC_EVENT_FIXATION_START: Copy of gaze_start.

For EYEVEC_EVENT_FIXATION_END: Linear regression based average of the estimated gaze position at endtime minus one frame duration.

For EYEVEC_EVENT_FIXATION_UPDATE: Linear regression based average of the estimated gaze position at endtime.

gaze_avg

Average logical gaze position during fixation

For EYEVEC_EVENT_FIXATION_START: Copy of gaze_start.

For EYEVEC_EVENT_FIXATION_END: Average of the linear regression based averages of the estimated gaze position.

For EYEVEC_EVENT_FIXATION_UPDATE: Average of the linear regression based averages of the estimated gaze position so far.

gaze_var

Variance of logical gaze position during fixation

For EYEVEC_EVENT_FIXATION_START: 0.

For EYEVEC_EVENT_FIXATION_END: Variance of the linear regression based averages of the estimated gaze position.

For EYEVEC_EVENT_FIXATION_UPDATE: Variance of the linear regression based averages of the estimated gaze position so far.

gaze_updavg

Average logical gaze position during fixation update interval

For EYEVEC_EVENT_FIXATION_START: Copy of gaze_start.

For EYEVEC_EVENT_FIXATION_END, EYEVEC_EVENT_FIXATION_UPDATE: Average of the linear regression based averages of the estimated gaze position over the fixation update interval.

gaze_updvar

Variance of logical gaze position during fixation update interval

For EYEVEC_EVENT_FIXATION_START: 0.

For EYEVEC_EVENT_FIXATION_END, EYEVEC_EVENT_FIXATION_UPDATE: Variance of the linear regression based averages of the estimated gaze position over the fixation update interval.

pupil_start

Estimated pupil diameter at fixation start [mm]

This is the estimated pupil diameter at starttime.

If possible length of the major axis of the estimated pupil ellipse will be used. Otherwise the the diameter will be based on detected pupil area.

pupil_end

Estimated pupil diameter at fixation end [mm]

For EYEVEC_EVENT_FIXATION_START: Copy of pupil_start.

For EYEVEC_EVENT_FIXATION_END: Estimated pupil diameter at endtime minus one frame duration.

For EYEVEC_EVENT_FIXATION_UPDATE: Estimated pupil diameter at endtime.

pupil_avg

Average estimated pupil diameter during fixation [mm]

For EYEVEC_EVENT_FIXATION_START: Copy of pupil_start.

For EYEVEC_EVENT_FIXATION_END: Average of the estimated pupil diameters.

For EYEVEC_EVENT_FIXATION_UPDATE: Average of the estimated pupil diameters so far.

pupil_var

Variance of estimated pupil diameter during fixation [mm2]

For EYEVEC_EVENT_FIXATION_START: 0.

For EYEVEC_EVENT_FIXATION_END: Variance of the estimated pupil diameters.

For EYEVEC_EVENT_FIXATION_UPDATE: Variance of the estimated pupil diameters so far.

pupil_updavg

Average estimated pupil diameter during fixation update interval [mm]

For EYEVEC_EVENT_FIXATION_START: Copy of pupil_start.

For EYEVEC_EVENT_FIXATION_END, EYEVEC_EVENT_FIXATION_UPDATE: Average of the estimated pupil diameters over the fixation update interval.

pupil_updvar

Variance of estimated pupil diameter during fixation update interval [mm2]

For EYEVEC_EVENT_FIXATION_START: 0.

For EYEVEC_EVENT_FIXATION_END, EYEVEC_EVENT_FIXATION_UPDATE: Variance of the estimated pupil diameters over the fixation update interval.

side

Which eye: EYEVEC_RIGHT_EYE, EYEVEC_LEFT_EYE or EYEVEC_MEAN_EYE

EyeVecTestItemEventData

Data for event id EYEVEC_EVENT_TEST_ITEM_START and EYEVEC_EVENT_TEST_ITEM_END.

typedef struct _EyeVecTestItemEventData {
    int id;
} EyeVecTestItemEventData;
Field Description

id

Item id

EyeVecEvent

Opaque EyeVecEvent struct.

typedef struct _EyeVecEvent EyeVecEvent;

EyeVec

Opaque EyeVec struct.

typedef struct _EyeVec EyeVec;