tobii_research_calibration.h File Reference

Functionality for implementing calibration. More...

Go to the source code of this file.

Data Structures
struct	TobiiResearchCalibrationEyeData
struct	TobiiResearchCalibrationSample
struct	TobiiResearchCalibrationPoint
struct	TobiiResearchCalibrationResult
struct	TobiiResearchHMDCalibrationResult

Typedefs
typedef enum TobiiResearchSelectedEye	TobiiResearchSelectedEye

Enumerations
enum	TobiiResearchCalibrationStatus { TOBII_RESEARCH_CALIBRATION_FAILURE = 0, TOBII_RESEARCH_CALIBRATION_SUCCESS = 1, TOBII_RESEARCH_CALIBRATION_SUCCESS_LEFT_EYE = 2, TOBII_RESEARCH_CALIBRATION_SUCCESS_RIGHT_EYE = 3 }
enum	TobiiResearchSelectedEye { TOBII_RESEARCH_SELECTED_EYE_LEFT, TOBII_RESEARCH_SELECTED_EYE_RIGHT, TOBII_RESEARCH_SELECTED_EYE_BOTH }
enum	TobiiResearchCalibrationEyeValidity { TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_INVALID_AND_NOT_USED = -1, TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_VALID_BUT_NOT_USED = 0, TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_VALID_AND_USED = 1, TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_UNKNOWN }

Functions
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_calibration_enter_calibration_mode (TobiiResearchEyeTracker *eyetracker)
	Enters the screen based calibration mode and the eye tracker is made ready for collecting data and calculating new calibrations. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_calibration_leave_calibration_mode (TobiiResearchEyeTracker *eyetracker)
	Leaves the screen based calibration mode. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_calibration_collect_data (TobiiResearchEyeTracker *eyetracker, float x, float y)
	Starts collecting data for a calibration point. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_calibration_discard_data (TobiiResearchEyeTracker *eyetracker, float x, float y)
	Removes the collected data associated with a specific calibration point. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_calibration_compute_and_apply (TobiiResearchEyeTracker *eyetracker, TobiiResearchCalibrationResult **result)
	Uses the collected data and tries to compute calibration parameters. More...
TOBII_RESEARCH_API void TOBII_RESEARCH_CALL	tobii_research_free_screen_based_calibration_result (TobiiResearchCalibrationResult *result)
	Free memory allocation for the calibration result received via tobii_research_screen_based_calibration_compute_and_apply. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_monocular_calibration_collect_data (TobiiResearchEyeTracker *eyetracker, float x, float y, TobiiResearchSelectedEye eye_to_calibrate, TobiiResearchSelectedEye *collected_eyes)
	Starts collecting data for a calibration point. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_monocular_calibration_discard_data (TobiiResearchEyeTracker *eyetracker, float x, float y, TobiiResearchSelectedEye eye_to_calibrate)
	Removes the collected data associated with a specific calibration point. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_screen_based_monocular_calibration_compute_and_apply (TobiiResearchEyeTracker *eyetracker, TobiiResearchCalibrationResult **result)
	Uses the collected data and tries to compute calibration parameters. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_hmd_based_calibration_enter_calibration_mode (TobiiResearchEyeTracker *eyetracker)
	Enters the hmd based calibration mode and the eye tracker is made ready for collecting data and calculating new calibrations. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_hmd_based_calibration_leave_calibration_mode (TobiiResearchEyeTracker *eyetracker)
	Leaves the hmd based calibration mode. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_hmd_based_calibration_collect_data (TobiiResearchEyeTracker *eyetracker, float x, float y, float z)
	Starts collecting data for a calibration point. More...
TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL	tobii_research_hmd_based_calibration_compute_and_apply (TobiiResearchEyeTracker *eyetracker, TobiiResearchHMDCalibrationResult *result)
	Uses the collected data and tries to compute calibration parameters. More...

Detailed Description

Functionality for implementing calibration.

Copyright

COPYRIGHT 2019 - PROPERTY OF TOBII PRO AB

2019 TOBII PRO AB - KARLSROVAGEN 2D, DANDERYD 182 53, SWEDEN - All Rights Reserved.

NOTICE: All information contained herein is, and remains, the property of Tobii Pro AB and its suppliers, if any. The intellectual and technical concepts contained herein are proprietary to Tobii Pro AB and its suppliers and may be covered by U.S.and Foreign Patents, patent applications, and are protected by trade secret or copyright law. Dissemination of this information or reproduction of this material is strictly forbidden unless prior written permission is obtained from Tobii Pro AB.

Typedef Documentation

TobiiResearchSelectedEye

typedef enum TobiiResearchSelectedEye TobiiResearchSelectedEye

Defines the selected eye.

Enumeration Type Documentation

TobiiResearchCalibrationEyeValidity

enum TobiiResearchCalibrationEyeValidity

Defines the validity of calibration eye data.

Enumerator
TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_INVALID_AND_NOT_USED	The eye tracking failed or the calibration eye data is invalid.
TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_VALID_BUT_NOT_USED	Eye Tracking was successful, but the calibration eye data was not used in calibration e.g. gaze was too far away.
TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_VALID_AND_USED	The calibration eye data was valid and used in calibration.
TOBII_RESEARCH_CALIBRATION_EYE_VALIDITY_UNKNOWN	The calibration eye data has an unexpected validity.

TobiiResearchCalibrationStatus

enum TobiiResearchCalibrationStatus

"Defines the overall status of a calibration process.

Enumerator
TOBII_RESEARCH_CALIBRATION_FAILURE	Indicates that the calibration process failed.
TOBII_RESEARCH_CALIBRATION_SUCCESS	Indicates that the calibration process succeeded for both eyes.
TOBII_RESEARCH_CALIBRATION_SUCCESS_LEFT_EYE	Indicates that the left eye calibration process succeeded.
TOBII_RESEARCH_CALIBRATION_SUCCESS_RIGHT_EYE	Indicates that the right eye calibration process succeeded.

TobiiResearchSelectedEye

enum TobiiResearchSelectedEye

Defines the selected eye.

Enumerator
TOBII_RESEARCH_SELECTED_EYE_LEFT	Left Eye
TOBII_RESEARCH_SELECTED_EYE_RIGHT	Right Eye
TOBII_RESEARCH_SELECTED_EYE_BOTH	Both Eyes

Function Documentation

tobii_research_free_screen_based_calibration_result()

TOBII_RESEARCH_API void TOBII_RESEARCH_CALL tobii_research_free_screen_based_calibration_result

(

TobiiResearchCalibrationResult *

result

)

Free memory allocation for the calibration result received via tobii_research_screen_based_calibration_compute_and_apply.

Parameters

result

Calibration result to free.

Examples

calibration.c.

tobii_research_hmd_based_calibration_collect_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_hmd_based_calibration_collect_data	(	TobiiResearchEyeTracker *	eyetracker,
		float	x,
		float	y,
		float	z
	)

Starts collecting data for a calibration point.

The argument used is the point the calibration user is assumed to be looking at and is given in the HMD coordinate system.

You must call tobii_research_screen_based_calibration_enter_calibration_mode before calling this function. This function is blocking while collecting data and may take up to 10 seconds.

Parameters

eyetracker	Eye tracker object.
x	x coordinate in the HMD coordinate system where the user is looking.
y	y coordinate in the HMD coordinate system where the user is looking.
z	z coordinate in the HMD coordinate system where the user is looking.

Returns

A TobiiResearchStatus code.

Examples

hmd_calibration.c.

tobii_research_hmd_based_calibration_compute_and_apply()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_hmd_based_calibration_compute_and_apply	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchHMDCalibrationResult *	result
	)

Uses the collected data and tries to compute calibration parameters.

If the calculation is successful, the result is applied to the eye tracker. If there is insufficient data to compute a new calibration or if the collected data is not good enough then calibration is failed and will not be applied.

    /* Define the points we should calibrate at. */
    /* The coordinates are in HMD coordinates (x,y,z) */
    {
        #define NUM_OF_POINTS  3U
 
        TobiiResearchPoint3D points_to_calibrate[NUM_OF_POINTS] = \
                {{0.0f, 0.0f, 1000.0f}, {20.0f, 0.0f, 1000.0f}, {0.0f, 20.0f, 1000.0f}};
        size_t i = 0;
 
 
        for(; i < NUM_OF_POINTS; i++) {
            TobiiResearchPoint3D* point = &points_to_calibrate[i];
            printf("Show a point on screen at (%f,%f).\n", point->x, point->y);
 
            //  Wait a little for user to focus.
            sleep_ms(700);
 
            printf("Collecting data at (%f,%f,%f).\n", point->x, point->y, point->z);
            if (tobii_research_hmd_based_calibration_collect_data(eyetracker, point->x, point->y, point->z) != TOBII_RESEARCH_STATUS_OK) {
                /* Try again if it didn't go well the first time. */
                /* Not all eye tracker models will fail at this point, but instead fail on ComputeAndApply. */
                tobii_research_hmd_based_calibration_collect_data(eyetracker, point->x, point->y, point->z);
            }
        }
 
 
        printf("Computing and applying calibration.\n");
        TobiiResearchHMDCalibrationResult calibration_result;
        status = tobii_research_hmd_based_calibration_compute_and_apply(eyetracker, &calibration_result);
 
        if (status == TOBII_RESEARCH_STATUS_OK) {
            if (calibration_result.status == TOBII_RESEARCH_CALIBRATION_SUCCESS)
                printf("Calibration was successful!\n");
            else if (calibration_result.status == TOBII_RESEARCH_CALIBRATION_FAILURE)
                printf("Calibration failed!\n");
        }
 

Parameters

eyetracker	Eye tracker object.
result	Represents the result of the calculated HMD calibration.

Returns

A TobiiResearchStatus code.

Examples

hmd_calibration.c.

tobii_research_hmd_based_calibration_enter_calibration_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_hmd_based_calibration_enter_calibration_mode

(

TobiiResearchEyeTracker *

eyetracker

)

Enters the hmd based calibration mode and the eye tracker is made ready for collecting data and calculating new calibrations.

 
    /* Enter calibration mode. */
    TobiiResearchStatus status = tobii_research_hmd_based_calibration_enter_calibration_mode(eyetracker);
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Entered calibration mode for eye tracker with serial number %s \n.", serial_number);
 
    tobii_research_free_string(serial_number);

Parameters

eyetracker

Eye tracker object.

Returns

A TobiiResearchStatus code.

Examples

hmd_calibration.c.

tobii_research_hmd_based_calibration_leave_calibration_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_hmd_based_calibration_leave_calibration_mode

(

TobiiResearchEyeTracker *

eyetracker

)

Leaves the hmd based calibration mode.

    /* The calibration is done. Leave calibration mode. */
    status = tobii_research_hmd_based_calibration_leave_calibration_mode(eyetracker);
 
    printf("Left calibration mode.\n");

Parameters

eyetracker

Eye tracker object.

Returns

A TobiiResearchStatus code.

Examples

hmd_calibration.c.

tobii_research_screen_based_calibration_collect_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_calibration_collect_data	(	TobiiResearchEyeTracker *	eyetracker,
		float	x,
		float	y
	)

Starts collecting data for a calibration point.

The argument used is the point the calibration user is assumed to be looking at and is given in the active display area coordinate system.

You must call tobii_research_calibration_enter_calibration_mode before calling this function. This function is blocking while collecting data and may take up to 10 seconds.

    /* Define the points on screen we should calibrate at. */
    /* The coordinates are normalized, i.e. (0.0, 0.0) is the upper left corner and (1.0, 1.0) is the lower right corner. */
    {
        #define NUM_OF_POINTS  5U
 
        TobiiResearchNormalizedPoint2D points_to_calibrate[NUM_OF_POINTS] = \
                {{0.5f, 0.5f}, {0.1f, 0.1f}, {0.1f, 0.9f}, {0.9f, 0.1f}, {0.9f, 0.9f}};
        size_t i = 0;
 
 
        for(; i < NUM_OF_POINTS; i++) {
            TobiiResearchNormalizedPoint2D* point = &points_to_calibrate[i];
            printf("Show a point on screen at (%f,%f).\n", point->x, point->y);
 
            //  Wait a little for user to focus.
            sleep_ms(700);
 
            printf("Collecting data at (%f,%f).\n", point->x, point->y);
            if (tobii_research_screen_based_calibration_collect_data(eyetracker, point->x, point->y) != TOBII_RESEARCH_STATUS_OK) {
                /* Try again if it didn't go well the first time. */
                /* Not all eye tracker models will fail at this point, but instead fail on ComputeAndApply. */
                tobii_research_screen_based_calibration_collect_data(eyetracker, point->x, point->y);
            }
        }
 
 
        printf("Computing and applying calibration.\n");
        TobiiResearchCalibrationResult* calibration_result = NULL;
        status = tobii_research_screen_based_calibration_compute_and_apply(eyetracker, &calibration_result);
 
        if (status == TOBII_RESEARCH_STATUS_OK && calibration_result->status == TOBII_RESEARCH_CALIBRATION_SUCCESS) {
            printf("Compute and apply returned %i and collected at %zu points.\n", status, calibration_result->calibration_point_count);
        } else {
            printf("Calibration failed!\n");
        }
 
        /* Free calibration result when done using it */
        tobii_research_free_screen_based_calibration_result(calibration_result);

Parameters

eyetracker	Eye tracker object.
x	Normalized x coordinate on active display area where the user is looking.
y	Normalized y coordinate on active display area where the user is looking.

Returns

A TobiiResearchStatus code.

Examples

calibration.c.

tobii_research_screen_based_calibration_compute_and_apply()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_calibration_compute_and_apply	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchCalibrationResult **	result
	)

Uses the collected data and tries to compute calibration parameters.

If the calculation is successful, the result is applied to the eye tracker. If there is insufficient data to compute a new calibration or if the collected data is not good enough then calibration is failed and will not be applied.

    /* Define the points on screen we should calibrate at. */
    /* The coordinates are normalized, i.e. (0.0, 0.0) is the upper left corner and (1.0, 1.0) is the lower right corner. */
    {
        #define NUM_OF_POINTS  5U
 
        TobiiResearchNormalizedPoint2D points_to_calibrate[NUM_OF_POINTS] = \
                {{0.5f, 0.5f}, {0.1f, 0.1f}, {0.1f, 0.9f}, {0.9f, 0.1f}, {0.9f, 0.9f}};
        size_t i = 0;
 
 
        for(; i < NUM_OF_POINTS; i++) {
            TobiiResearchNormalizedPoint2D* point = &points_to_calibrate[i];
            printf("Show a point on screen at (%f,%f).\n", point->x, point->y);
 
            //  Wait a little for user to focus.
            sleep_ms(700);
 
            printf("Collecting data at (%f,%f).\n", point->x, point->y);
            if (tobii_research_screen_based_calibration_collect_data(eyetracker, point->x, point->y) != TOBII_RESEARCH_STATUS_OK) {
                /* Try again if it didn't go well the first time. */
                /* Not all eye tracker models will fail at this point, but instead fail on ComputeAndApply. */
                tobii_research_screen_based_calibration_collect_data(eyetracker, point->x, point->y);
            }
        }
 
 
        printf("Computing and applying calibration.\n");
        TobiiResearchCalibrationResult* calibration_result = NULL;
        status = tobii_research_screen_based_calibration_compute_and_apply(eyetracker, &calibration_result);
 
        if (status == TOBII_RESEARCH_STATUS_OK && calibration_result->status == TOBII_RESEARCH_CALIBRATION_SUCCESS) {
            printf("Compute and apply returned %i and collected at %zu points.\n", status, calibration_result->calibration_point_count);
        } else {
            printf("Calibration failed!\n");
        }
 
        /* Free calibration result when done using it */
        tobii_research_free_screen_based_calibration_result(calibration_result);

Parameters

eyetracker	Eye tracker object.
result	Represents the result of the calculated calibration.

Returns

A TobiiResearchStatus code.

Examples

calibration.c.

tobii_research_screen_based_calibration_discard_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_calibration_discard_data	(	TobiiResearchEyeTracker *	eyetracker,
		float	x,
		float	y
	)

Removes the collected data associated with a specific calibration point.

        /* Analyze the data and maybe remove points that weren't good. */
        TobiiResearchNormalizedPoint2D* recalibrate_point = &points_to_calibrate[1];
        printf("Removing calibration point at (%f,%f).\n", recalibrate_point->x, recalibrate_point->y);
        status = tobii_research_screen_based_calibration_discard_data(eyetracker, recalibrate_point->x, recalibrate_point->y);
 
        /* Redo collection at the discarded point */
        printf("Show a point on screen at (%f,%f).\n", recalibrate_point->x, recalibrate_point->y);
        tobii_research_screen_based_calibration_collect_data(eyetracker, recalibrate_point->x, recalibrate_point->y);
 
        /* Compute and apply again. */
        printf("Computing and applying calibration.\n");
        status = tobii_research_screen_based_calibration_compute_and_apply(eyetracker, &calibration_result);
 
        if (status == TOBII_RESEARCH_STATUS_OK && calibration_result->status == TOBII_RESEARCH_CALIBRATION_SUCCESS) {
            printf("Compute and apply returned %i and collected at %zu points.\n", status, calibration_result->calibration_point_count);
        } else {
            printf("Calibration failed!\n");
        }
 
        /* Free calibration result when done using it */
        tobii_research_free_screen_based_calibration_result(calibration_result);
        /* See that you're happy with the result. */

Parameters

eyetracker	Eye tracker object.
x	Normalized x coordinate of point to discard.
y	Normalized y coordinate of point to discard.

Returns

A TobiiResearchStatus code.

Examples

calibration.c.

tobii_research_screen_based_calibration_enter_calibration_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_calibration_enter_calibration_mode

(

TobiiResearchEyeTracker *

eyetracker

)

Enters the screen based calibration mode and the eye tracker is made ready for collecting data and calculating new calibrations.

 
    /* Enter calibration mode. */
    TobiiResearchStatus status = tobii_research_screen_based_calibration_enter_calibration_mode(eyetracker);
    char* serial_number = NULL;
    tobii_research_get_serial_number(eyetracker, &serial_number);
 
    printf("Entered calibration mode for eye tracker with serial number %s \n.", serial_number);
 
    tobii_research_free_string(serial_number);

Parameters

eyetracker

Eye tracker object.

Returns

A TobiiResearchStatus code.

Examples

calibration.c, and notifications.c.

tobii_research_screen_based_calibration_leave_calibration_mode()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_calibration_leave_calibration_mode

(

TobiiResearchEyeTracker *

eyetracker

)

Leaves the screen based calibration mode.

    /* The calibration is done. Leave calibration mode. */
    status = tobii_research_screen_based_calibration_leave_calibration_mode(eyetracker);
 
    printf("Left calibration mode.\n");

Parameters

eyetracker

Eye tracker object.

Returns

A TobiiResearchStatus code.

Examples

calibration.c, and notifications.c.

tobii_research_screen_based_monocular_calibration_collect_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_monocular_calibration_collect_data	(	TobiiResearchEyeTracker *	eyetracker,
		float	x,
		float	y,
		TobiiResearchSelectedEye	eye_to_calibrate,
		TobiiResearchSelectedEye *	collected_eyes
	)

Starts collecting data for a calibration point.

The argument used is the point the calibration user is assumed to be looking at and is given in the active display area coordinate system.

You must call tobii_research_calibration_enter_calibration_mode before calling this function. This function is blocking while collecting data and may take up to 10 seconds.

Parameters

eyetracker	Eye tracker object.
x	Normalized x coordinate on active display area where the user is looking.
y	Normalized y coordinate on active display area where the user is looking.
eye_to_calibrate	TobiiResearchSelectedEye instance that selects for which eye to collect data for the monocular calibration.
collected_eyes	TobiiResearchSelectedEye instance that indicates for which eyes data was collected for the monocular calibration.

Returns

A TobiiResearchStatus code.

tobii_research_screen_based_monocular_calibration_compute_and_apply()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_monocular_calibration_compute_and_apply	(	TobiiResearchEyeTracker *	eyetracker,
		TobiiResearchCalibrationResult **	result
	)

Uses the collected data and tries to compute calibration parameters.

If the calculation is successful, the result is applied to the eye tracker. If there is insufficient data to compute a new calibration or if the collected data is not good enough then calibration is failed and will not be applied.

Parameters

eyetracker	Eye tracker object.
result	TobiiResearchCalibrationResult instance the calibration result.

Returns

A TobiiResearchStatus code.

tobii_research_screen_based_monocular_calibration_discard_data()

TOBII_RESEARCH_API TobiiResearchStatus TOBII_RESEARCH_CALL tobii_research_screen_based_monocular_calibration_discard_data	(	TobiiResearchEyeTracker *	eyetracker,
		float	x,
		float	y,
		TobiiResearchSelectedEye	eye_to_calibrate
	)

Removes the collected data associated with a specific calibration point.

Parameters

eyetracker	Eye tracker object.
x	Normalized x coordinate of point to discard.
y	Normalized y coordinate of point to discard.
eye_to_calibrate	TobiiResearchSelectedEye instance that selects for which eye to discard data for the monocular calibration.

Returns

A TobiiResearchStatus code.