Calibrate gaze position
=======================

Gaze position calibration is an optional [ArFrame](../../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline step. It processes each new gaze position before any further pipeline steps.

The calibration algorithm can be selected by instantiating a particular [GazePositionCalibrator from the GazeAnalysis submodule](../pipeline_modules/gaze_position_calibrators.md) or [from another Python package](module_loading.md).

## Enable ArFrame calibration

Gaze position calibration can be enabled with a dedicated JSON entry.

Here is an extract from the JSON ArFrame configuration file where a [Linear Regression](../../../argaze.md/#argaze.GazeAnalysis.LinearRegression) calibration algorithm is selected with no parameters:

```json
{
    "argaze.ArFeatures.ArFrame": {
        "name": "My FullHD screen",
        "size": [1920, 1080],
        ...
        "gaze_position_calibrator": {
            "LinearRegression": {}
        },
        ...
    }
}
```
!!! note
    When a [GazePositionCalibrator](../../../argaze.md/#argaze.GazeFeatures.GazePositionCalibrator) is instantiated, each gaze position passed to [ArFrame.look](../../../argaze.md/#argaze.ArFeatures.ArFrame.look) method will be transformed before gaze movement identification step.

## Edit calibration parameters

```python
# Assuming the ArFrame is loaded
...

    # Start calibration process
    ar_frame.gaze_position_calibrator.reset()

    # Assuming that expected and observed gaze positions are available
    ...

        # If calibration process started
        if ar_frame.gaze_position_calibrator.is_calibrating():

            # Store calibration data
            ar_frame.gaze_position_calibrator.store(timestamp, observed_gaze_position, expected_gaze_position)

    # End calibration process
    score = ar_frame.gaze_position_calibrator.calibrate()
```

## Save calibration parameters as JSON file

Calibration parameters can be save as JSON file:

```python
ar_frame.gaze_position_calibrator.to_json('calibration.json')
```

Here is the saved JSON file where calibration parameters are stored:

```json
{
    "argaze.GazeAnalysis.LinearRegression": {
        "coefficients": [
            [
                0.901167941442693,
                0.0345129853595345
            ],
            [
                0.11551395622739168,
                0.9315744785596141
            ]
        ],
        "intercept": [
            65.43372920399452,
            -52.23141937917768
        ]
    }
}
```

## Load calibration parameters file

Saved calibration parameters can be loaded from JSON ArFrame configuration file:

```json
{
    "name": "My FullHD screen",
    "size": [1920, 1080],
    ...
    "gaze_position_calibrator": "calibration.json"
    ...
```

They also can be loaded from Python script:

```python
ar_frame.gaze_position_calibrator.from_json('calibration.json')
```