diff options
Diffstat (limited to 'docs')
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) + |