Overview

This document provides a detailed description of the API functions provided by the Deep Gaze library. This library allows for the initialization, calibration, and querying of eye gaze information.

Enum Definitions

ET_ReturnCode

The ET_ReturnCode enum defines possible return codes for the API functions:

  • ET_SUCCESS (0): Success; proceed to the next scene.

  • ET_CALI_CONTINUE (1): Calibration in progress; continue using the current calibration point.

  • ET_CALI_NEXT_POINT (2): Calibration in progress; switch to the next calibration point.

  • ET_FAILED (9): Operation failed.

API Functions

deep_gaze_init

ET_ReturnCode deep_gaze_init();

Description:

Initializes the Deep Gaze system.

Returns:

  • ET_SUCCESS on successful initialization.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_face_pos

ET_ReturnCode deep_gaze_face_pos(float* eyepos);

Description:

Retrieves the user’s face position.

Parameters:

  • eyepos: Array of 3 floats representing the eye position in millimeters.

    • x and y are the coordinates on the screen.

    • z is the depth value.

    Screen center: (172.08, 96.795)
    Screen size: [344.16, 193.59]
    Valid ranges:

    • x ∈ [172.08 - 32 - 30, 172.08 - 32 + 30]

    • y ∈ [96.795 - 40 - 30, 96.795 - 40 + 30]

    • z ∈ [-580 - 50, -580 + 50]

Returns:

  • ET_SUCCESS on success.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_cali

ET_ReturnCode deep_gaze_cali(const int cali_point_id);

Description:

Performs calibration at a specific point.

Parameters:

  • cali_point_id: Identifier for the calibration point.

Returns:

  • ET_SUCCESS if calibration is successful.

  • ET_CALI_CONTINUE if calibration needs to continue.

  • ET_CALI_NEXT_POINT if calibration needs to move to the next point.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_est

ET_ReturnCode deep_gaze_est(float* pt, long long* timeStamp);

Description:

Obtains gaze estimation information.

Parameters:

  • pt: Array of 11 floats providing gaze information:

    • pt[0] - Left eye gaze position x (0~1920)

    • pt[1] - Left eye gaze position y (0~1080)

    • pt[2] - Left eye pupil size (0~10) mm

    • pt[3] - Right eye gaze position x (0~1920)

    • pt[4] - Right eye gaze position y (0~1080)

    • pt[5] - Right eye pupil size (0~10) mm

    • pt[6] - Pixels per degree x

    • pt[7] - Pixels per degree y

    • pt[8] - Return flag (norm: 0; miss left eye: 1; miss right eye: 2; no eyes: 3)

    • pt[9] - Binocular gaze position x (0~1920)

    • pt[10] - Binocular gaze position y (0~1920)

  • timeStamp: Timestamp in hours, minutes, seconds, and milliseconds.

Returns:

  • ET_SUCCESS on successful retrieval.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_est_lr

ET_ReturnCode deep_gaze_est_lr(float* pt_l, float* pt_r, long long* timeStamp);

Description:

Obtains separate gaze estimation information for the left and right eyes.

Parameters:

  • pt_l: Array of 14 floats for left eye gaze information:

    • pt_l[0] - Left eye gaze position x (0~1920)

    • pt_l[1] - Left eye gaze position y (0~1080)

    • pt_l[2] - Left eye pupil diameter (0~10) mm

    • pt_l[3] - Left eye pupil position x

    • pt_l[4] - Left eye pupil position y

    • pt_l[5] - Left eye pupil position z

    • pt_l[6] - Left eye visual angle (theta)

    • pt_l[7] - Left eye visual angle (phi)

    • pt_l[8] - Left eye visual angle (x)

    • pt_l[9] - Left eye visual angle (y)

    • pt_l[10] - Left eye visual angle (z)

    • pt_l[11] - Left eye pixels per degree x

    • pt_l[12] - Left eye pixels per degree y

    • pt_l[13] - Left eye valid (0: invalid, 1: valid)

  • pt_r: Array of 14 floats for right eye gaze information:

    • pt_r[0] - Right eye gaze position x (0~1920)

    • pt_r[1] - Right eye gaze position y (0~1080)

    • pt_r[2] - Right eye pupil diameter (0~10) mm

    • pt_r[3] - Right eye pupil position x

    • pt_r[4] - Right eye pupil position y

    • pt_r[5] - Right eye pupil position z

    • pt_r[6] - Right eye visual angle (theta)

    • pt_r[7] - Right eye visual angle (phi)

    • pt_r[8] - Right eye visual angle (x)

    • pt_r[9] - Right eye visual angle (y)

    • pt_r[10] - Right eye visual angle (z)

    • pt_r[11] - Right eye pixels per degree x

    • pt_r[12] - Right eye pixels per degree y

    • pt_r[13] - Right eye valid (0: invalid, 1: valid)

  • timeStamp: Timestamp in hours, minutes, seconds, and milliseconds.

Returns:

  • ET_SUCCESS on successful retrieval.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_release

ET_ReturnCode deep_gaze_release();

Description:

Releases resources and performs cleanup when the program exits.

Returns:

  • ET_SUCCESS on successful release.

  • Other ET_ReturnCode values indicate failure or special conditions.

deep_gaze_get_version

const char *deep_gaze_get_version();

Description:

Retrieves the version information of the Deep Gaze library.

Returns:

  • A const char* representing the version string of the library.

deep_gaze_set_look_ahead

ET_ReturnCode deep_gaze_set_look_ahead(int look_ahead);

Description:

Sets the look-ahead parameter, which defines the number of future frames the system considers for gaze estimation.

Parameters:

  • look_ahead: An integer specifying the number of frames to look ahead.

Returns:

  • ET_SUCCESS on successful parameter update. Other ET_ReturnCode values indicate failure or invalid input.

deep_gaze_set_log

ET_ReturnCode deep_gaze_set_log(int valid, char *log_Path);

Description:

Configures logging for the Deep Gaze library.

Parameters:

  • valid: An integer indicating whether logging is enabled (1 for enabled, 0 for disabled). log_Path: A pointer to a character array specifying the path to the log file.

Returns:

  • ET_SUCCESS on successful log configuration. Other ET_ReturnCode values indicate failure or invalid parameters.

deep_gaze_recalibrate

ET_ReturnCode deep_gaze_recalibrate();

Description:

Triggers recalibration of the gaze tracking system to improve accuracy.

Returns:

  • ET_SUCCESS if recalibration is completed successfully. Other ET_ReturnCode values indicate failure or an inability to recalibrate.

deep_gaze_face_image

ET_ReturnCode deep_gaze_face_image(char **image_data, int *width, int *height);

Description:

Provides the current face image data being processed by the gaze tracking system.

Parameters:

  • image_data: A double pointer to hold the address of the image data buffer. width: A pointer to an integer to store the width of the image. height: A pointer to an integer to store the height of the image. Returns:

Returns:

  • ET_SUCCESS on successful retrieval of face image data. Other ET_ReturnCode values indicate failure or lack of image data.

deep_gaze_set_cali_mode

ET_ReturnCode deep_gaze_set_cali_mode(int mode, float *cali_points);

Description:

Sets the calibration mode and points for gaze tracking.

Parameters:

  • mode: An integer representing the calibration mode. cali_points: A pointer to an array of floats representing calibration points. Returns:

Returns:

  • ET_SUCCESS on successful calibration mode configuration. Other ET_ReturnCode values indicate failure or invalid input