aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guide/gaze_analysis_pipeline/ar_layer.md
diff options
context:
space:
mode:
Diffstat (limited to 'docs/user_guide/gaze_analysis_pipeline/ar_layer.md')
-rw-r--r--docs/user_guide/gaze_analysis_pipeline/ar_layer.md99
1 files changed, 99 insertions, 0 deletions
diff --git a/docs/user_guide/gaze_analysis_pipeline/ar_layer.md b/docs/user_guide/gaze_analysis_pipeline/ar_layer.md
new file mode 100644
index 0000000..893e50c
--- /dev/null
+++ b/docs/user_guide/gaze_analysis_pipeline/ar_layer.md
@@ -0,0 +1,99 @@
+Add an ArLayer
+==============
+
+The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class defines a space where to make matching of gaze movements and AOIs and inside which those matchings need to be analyzed.
+
+![Empty layer area](../../img/ar_layer_empty.png)
+
+## Add ArLayer to ArFrame JSON configuration file
+
+An [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer).
+
+Here is an extract from the JSON ArFrame configuration file with a sample where one layer is added:
+
+```json
+{
+ "name": "My FullHD screen",
+ "size": [1920, 1080],
+ ...
+ "layers": {
+ "MyLayer": {
+ "aoi_color": [0, 0, 255],
+ "aoi_scene" : {
+ "upper_left_area": [[0, 0], [960, 0], [960, 540], [0, 540]],
+ "upper_right_area": [[960, 0], [1920, 0], [1920, 540], [960, 540]],
+ "lower_left_area": [[0, 540], [960, 540], [960, 1080], [0, 1080]],
+ "lower_right_area": [[960, 540], [1920, 540], [1920, 1080], [960, 1080]]
+ },
+ "aoi_matcher": {
+ "DeviationCircleCoverage": {
+ "coverage_threshold": 0.5
+ }
+ },
+ "aoi_scan_path": {
+ "duration_max": 30000
+ },
+ "aoi_scan_path_analyzers": {
+ "Basic": {},
+ "TransitionMatrix": {},
+ "NGram": {
+ "n_min": 3,
+ "n_max": 5
+ }
+ }
+ }
+ }
+}
+```
+
+!!! note
+
+ Timestamped gaze movements identified by parent [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) are passed one by one to each [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). So, the execution of all [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) is done during parent [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method call as explained in [previous chapter](ar_frame_configuration_and_execution.md).
+
+Now, let's understand the meaning of each JSON entry.
+
+### Name
+
+The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
+
+### AOI Color
+
+The color of [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer)'s AOI. Basically useful for visualisation purpose.
+
+### AOI Scene
+
+The [AOIScene](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AOIScene) defines a set of 2D [AreaOfInterest](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) registered by name.
+
+![AOI Scene](../../img/ar_layer_aoi_scene.png)
+
+### AOI Matcher
+
+The first [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step aims to make match identified gaze movement with an AOI of the scene.
+
+![AOI Matcher](../../img/ar_layer_aoi_matcher.png)
+
+The matching algorithm can be selected by instantiating a particular [AOIMatcher](../../argaze.md/#argaze.GazeFeatures.AOIMatcher) from the [argaze.GazeAnalysis](../../argaze.md/#argaze.GazeAnalysis) submodule or [from another python package](advanced_topics/module_loading.md).
+
+In the example file, the choosen matching algorithm is the [Deviation Circle Coverage](../../argaze.md/#argaze.GazeAnalysis.DeviationCircleCoverage) which has one specific *coverage_threshold* attribute.
+
+!!! warning
+ JSON *aoi_matcher* entry is mandatory. Otherwise, the AOIScanPath and AOIScanPathAnalyzers steps are disabled.
+
+### AOI Scan Path
+
+The second [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step aims to build a [AOIScanPath](../../argaze.md/#argaze.GazeFeatures.AOIScanPath) defined as a list of [AOIScanSteps](../../argaze.md/#argaze.GazeFeatures.AOIScanStep) made by a set of successive fixations/saccades onto a same AOI.
+
+![AOI Scan Path](../../img/ar_layer_aoi_scan_path.png)
+
+Once identified gaze movements are matched to AOI, they are automatically appended to the AOIScanPath if required.
+
+The [AOIScanPath.duration_max](../../argaze.md/#argaze.GazeFeatures.AOIScanPath.duration_max) attribute is the duration from which older AOI scan steps are removed each time new AOI scan steps are added.
+
+!!! note
+ JSON *aoi_scan_path* entry is not mandatory. If aoi_scan_path_analyzers entry is not empty, the AOIScanPath step is automatically enabled.
+
+### AOI Scan Path Analyzers
+
+Finally, the last [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step consists in passing the previously built [AOIScanPath](../../argaze.md/#argaze.GazeFeatures.AOIScanPath) to each loaded [AOIScanPathAnalyzer](../../argaze.md/#argaze.GazeFeatures.AOIScanPathAnalyzer).
+
+Each analysis algorithm can be selected by instantiating a particular [AOIScanPathAnalyzer](../../argaze.md/#argaze.GazeFeatures.AOIScanPathAnalyzer) from the [argaze.GazeAnalysis](../../argaze.md/#argaze.GazeAnalysis) submodule or [from another python package](advanced_topics/module_loading.md).