aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md
blob: fa7a71e7eccc5721ef3725297c963189bac7590e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
Enable AOI analysis
===================

Once [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) is [configured](configuration_and_execution.md) and [2D AOI are described](aoi_2d_description.md), fixation can be matched with AOI to build an AOI scan path before analyzing it. 

![Layer](../../img/ar_layer.png)

## Add ArLayer to ArFrame JSON configuration file

The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class defines a space where to match fixations with AOI and inside which those matches need to be analyzed.

Here is an extract from the JSON [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) configuration file with a sample where one layer is added:

```json
{
	"argaze.ArFeatures.ArFrame": {
		"name": "My FullHD screen",
		"size": [1920, 1080],
		...
		"layers": {
			"MyLayer": {
				"aoi_scene" : {
				    "GeoSector": [[860, 160], [1380, 100], [1660, 400], [1380, 740], [1440, 960], [920, 920], [680, 800], [640, 560]],
				    "LeftPanel": {
				        "Rectangle": {
				            "x": 0,
				            "y": 0,
				            "width": 350,
				            "height": 1080
				        }
				    },
				    "CircularWidget": {
				        "Circle": {
				            "cx": 1800,
				            "cy": 120,
				            "radius": 80
				        }
				    }
	        	},
	        	"aoi_matcher": {
	                "argaze.GazeAnalysis.DeviationCircleCoverage.AOIMatcher": {
	                    "coverage_threshold": 0.5
	                }
	            },
	        	"aoi_scan_path": {
	        		"duration_max": 30000
	        	},
				"aoi_scan_path_analyzers": {
					"argaze.GazeAnalysis.Basic.AOIScanPathAnalyzer": {},
					"argaze.GazeAnalysis.TransitionMatrix.AOIScanPathAnalyzer": {},
					"argaze.GazeAnalysis.NGram.AOIScanPathAnalyzer": {
						"n_min": 3,
						"n_max": 5
					}
				}
			}
		}
	}
}
```

!!! note

	Timestamped gaze movements identified by the 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 the parent [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method call, as explained in the [previous chapter](configuration_and_execution.md).

Now, let's understand the meaning of each JSON entry.

### *layers*

An [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.

### MyLayer

The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualization purpose.

### *aoi_scene*

The set of 2D AOI into the layer as defined at [2D AOI description chapter](aoi_2d_description.md).

![AOI scene](../../img/aoi_2d_description.png)

### *aoi_matcher*

The first [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step aims to match identified gaze movement with the layer's AOI.

![AOI matcher](../../img/aoi_matcher.png)

The matching algorithm can be selected by instantiating a particular [AOIMatcher from the GazeAnalysis submodule](pipeline_modules/aoi_matchers.md) or [from another Python package](advanced_topics/module_loading.md).

In the example file, the chosen matching algorithm is the [Deviation Circle Coverage](../../argaze.md/#argaze.GazeAnalysis.DeviationCircleCoverage) which has one specific *coverage_threshold* attribute.

!!! warning "Mandatory"
	JSON *aoi_matcher* entry is mandatory. Otherwise, the [AOIScanPath](../../argaze.md/#argaze.GazeFeatures.AOIScanPath) and [AOIScanPathAnalyzers](../../argaze.md/#argaze.GazeFeatures.AOIScanPathAnalyzer) steps are disabled.

### *aoi_scan_path*

The second [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step aims to build an [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 the same AOI.

![AOI scan path](../../img/aoi_scan_path.png)

Once 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 "Optional"
	JSON *aoi_scan_path* entry is not mandatory. If *aoi_scan_path_analyzers* entry is not empty, the [AOIScanPath](../../argaze.md/#argaze.GazeFeatures.AOIScanPath) step is automatically enabled.

### *aoi_scan_path_analyzers*

Finally, the last [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) pipeline step consists of 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 from the GazeAnalysis submodule](pipeline_modules/aoi_scan_path_analyzers.md) or [from another Python package](advanced_topics/module_loading.md).

In the example file, the chosen analysis algorithms are the [Basic](../../argaze.md/#argaze.GazeAnalysis.Basic) module, the [TransitionMatrix](../../argaze.md/#argaze.GazeAnalysis.TransitionMatrix) module and the [NGram](../../argaze.md/#argaze.GazeAnalysis.NGram) module, which has two specific *n_min* and *n_max* attributes.