aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/advanced_topics/gaze_position_calibration.md97
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/advanced_topics/module_loading.md4
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md6
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md2
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/introduction.md1
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/logging.md4
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/pipeline_modules/gaze_position_calibrators.md30
7 files changed, 138 insertions, 6 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')
+```
diff --git a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/module_loading.md b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/module_loading.md
index f2e84d6..f9174e2 100644
--- a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/module_loading.md
+++ b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/module_loading.md
@@ -1,5 +1,5 @@
-Loading modules from another package
-====================================
+Load modules from another package
+=================================
It possible to load [GazeMovementIdentifier](../../../argaze.md/#argaze.GazeFeatures.GazeMovementIdentifier), [ScanPathAnalyzer](../../../argaze.md/#argaze.GazeFeatures.ScanPathAnalyzer), [AOIMatcher](../../../argaze.md/#argaze.GazeFeatures.AOIMatcher) or [AOIScanPathAnalyzer](../../../argaze.md/#argaze.GazeFeatures.AOIScanPathAnalyzer) modules from another [python package](https://docs.python.org/3/tutorial/modules.html#packages).
diff --git a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
index eefeee1..4e2be92 100644
--- a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
+++ b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
@@ -72,7 +72,7 @@ for name, ar_layer in ar_frame.layers.items():
...
# Look ArFrame at a timestamped gaze position
- gaze_movement, scan_path_analysis, layers_analysis, execution_times, exception = ar_frame.look(timestamp, gaze_position)
+ gaze_position, gaze_movement, scan_path_analysis, layers_analysis, execution_times, exception = ar_frame.look(timestamp, gaze_position)
# Check if a gaze movement has been identified
if gaze_movement.valid and gaze_movement.finished:
@@ -106,6 +106,10 @@ for name, ar_layer in ar_frame.layers.items():
Let's understand the meaning of each returned data.
+### *gaze_position*
+
+This is the calibrated [GazePosition](../../../argaze.md/#argaze.GazeFeatures.GazePosition) returned by [GazePositionCalibrator](../../../argaze.md/#argaze.GazeFeatures.GazePositionCalibrator) if one is instanciated else, it is the given [GazePosition](../../../argaze.md/#argaze.GazeFeatures.GazePosition).
+
### *gaze_movement*
A [GazeMovement](../../../argaze.md/#argaze.GazeFeatures.GazeMovement) once it have been identified by [ArFrame.gaze_movement_identifier](../../../argaze.md/#argaze.ArFeatures.ArFrame) object from incoming consecutive timestamped gaze positions. If no gaze movement have been identified, it returns an [UnvalidGazeMovement](../../../argaze.md/#argaze.GazeFeatures.UnvalidGazeMovement).
diff --git a/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md b/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md
index 71d3c33..0edbef3 100644
--- a/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md
+++ b/docs/user_guide/gaze_analysis_pipeline/configuration_and_execution.md
@@ -94,7 +94,7 @@ In the example file, the choosen analysis algorithms are the [Basic](../../argaz
## Pipeline execution
-Timestamped gaze positions have to be passed one by one to [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole intanciated pipeline.
+Timestamped gaze positions have to be passed one by one to [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole instantiated pipeline.
```python
# Assuming that timestamped gaze positions are available
diff --git a/docs/user_guide/gaze_analysis_pipeline/introduction.md b/docs/user_guide/gaze_analysis_pipeline/introduction.md
index 65cc53a..16574e1 100644
--- a/docs/user_guide/gaze_analysis_pipeline/introduction.md
+++ b/docs/user_guide/gaze_analysis_pipeline/introduction.md
@@ -22,3 +22,4 @@ More advanced features are also explained like:
* [How to script gaze analysis pipeline](advanced_topics/scripting.md),
* [How to load module from another package](advanced_topics/module_loading.md).
+* [How to calibrate gaze position](advanced_topics/gaze_position_calibration.md).
diff --git a/docs/user_guide/gaze_analysis_pipeline/logging.md b/docs/user_guide/gaze_analysis_pipeline/logging.md
index 055a535..db3cf9a 100644
--- a/docs/user_guide/gaze_analysis_pipeline/logging.md
+++ b/docs/user_guide/gaze_analysis_pipeline/logging.md
@@ -47,8 +47,8 @@ for layer_name, layer in ar_frame.layers.items():
!!! note
[ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and its [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) logging are automatically done each time the [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method is called.
- [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) logging records each scan path analysis into a dedicated timestamped data buffer each time a new scan path step happens.
- [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) logging records each AOI scan path analysis into a dedicated timestamped data buffer each time a new AOI scan path step happens.
+ [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) logging records each scan path analysis into a dedicated timestamped data buffer each time a new scan step happens.
+ [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) logging records each AOI scan path analysis into a dedicated timestamped data buffer each time a new AOI scan step happens.
## Export gaze analysis logs to CSV file
diff --git a/docs/user_guide/gaze_analysis_pipeline/pipeline_modules/gaze_position_calibrators.md b/docs/user_guide/gaze_analysis_pipeline/pipeline_modules/gaze_position_calibrators.md
new file mode 100644
index 0000000..69139ed
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/pipeline_modules/gaze_position_calibrators.md
@@ -0,0 +1,30 @@
+Gaze position calibrators
+=========================
+
+ArGaze provides ready-to-use gaze position calibrator algorithms.
+
+Here are JSON samples to include the chosen module inside [ArFrame configuration](../advanced_topics/gaze_position_calibration.md) *gaze_position_calibrator* entry.
+
+## Linear regression
+
+```json
+"LinearRegression": {
+ "coefficients": [
+ [
+ 0.901167941442693,
+ 0.0345129853595345
+ ],
+ [
+ 0.11551395622739168,
+ 0.9315744785596141
+ ]
+ ],
+ "intercept": [
+ 65.43372920399452,
+ -52.23141937917768
+ ]
+}
+```
+
+[See in code reference](../../../argaze.md/#argaze.GazeAnalysis.LinearRegression.GazePositionCalibrator)
+