Documenting gaze position calibration features.

1 files changed, 97 insertions, 0 deletions

diff --git a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/gaze_position_calibration.md b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/gaze_position_calibration.md
new file mode 100644
index 0000000..c413e84
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/gaze_position_calibration.md
@@ -0,0 +1,97 @@
+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 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 thanks to 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
+{
+    "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.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')
+```