aboutsummaryrefslogtreecommitdiff
path: root/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
blob: 81efa409795b6fa425128e851673d4d297028cbe (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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
Script the pipeline
===================

All gaze analysis pipeline objects are accessible from Python script.
This could be particularly useful for realtime gaze interaction applications.

## Load ArFrame configuration from dictionary

First of all, [ArFrame](../../../argaze.md/#argaze.ArFeatures.ArFrame) configuration can be loaded from a python dictionary.

```python
from argaze import ArFeatures

# Edit a dict with ArFrame configuration
configuration = {
	"name": "My FullHD screen",
    "size": (1920, 1080),
    ...
    "gaze_movement_identifier": {
        ...
    },
    "scan_path": {
        ...
    },
    "scan_path_analyzers": {
        ...
    },
    "heatmap": {
        ...
    },
    "layers": {
        "MyLayer": {
            ...
        },
        ...
    },
    "image_parameters": {
        ...
    }
}

# Load ArFrame
ar_frame = ArFeatures.ArFrame.from_dict(configuration)

# Do something with ArFrame
...
```

## Access to ArFrame and ArLayers attributes

Then, once the configuration is loaded, it is possible to access to its attributes: [read ArFrame code reference](../../../argaze.md/#argaze.ArFeatures.ArFrame) to get a complete list of what is available.

Thus, the [ArFrame.layers](../../../argaze.md/#argaze.ArFeatures.ArFrame) attribute allows to access each loaded layer and so, access to their attributes: [read ArLayer code reference](../../../argaze.md/#argaze.ArFeatures.ArLayer) to get a complete list of what is available.

```python
from argaze import ArFeatures

# Assuming the ArFrame is loaded
...

# Iterate over each ArFrame layers
for name, ar_layer in ar_frame.layers.items():
    ...
```

## Pipeline execution outputs

[ArFrame.look](../../../argaze.md/#argaze.ArFeatures.ArFrame.look) method returns many data about pipeline execution.

```python
# Assuming that timestamped gaze positions are available
...

    # Look ArFrame at a timestamped 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:

        # Do something with identified fixation
        if GazeFeatures.is_fixation(gaze_movement):
            ...

        # Do something with identified saccade
        elif GazeFeatures.is_saccade(gaze_movement):
            ...

        # Do something with scan path analysis
        for module, analysis in scan_path_analysis.items():
            for data, value in analysis.items():
                ...

        # Do something with each layer AOI scan path analysis
        for layer_name, layer_aoi_scan_path_analysis in layers_analysis.items():
            for module, analysis in layer_aoi_scan_path_analysis.items():
                for data, value in analysis.items():
                    ...

    # Do something with pipeline execution times
    ...

    # Do something with pipeline exception
    if exception:
        ...
```

Let's understand the meaning of each returned data.

### 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). 

This could also be the current gaze movement if [ArFrame.filter_in_progress_identification](../../../argaze.md/#argaze.ArFeatures.ArFrame) attribute is false.
In that case, the returned gaze movement *finished* flag is false.

Then, the returned gaze movement type can be tested thanks to [GazeFeatures.is_fixation](../../../argaze.md/#argaze.GazeFeatures.is_fixation) and [GazeFeatures.is_saccade](../../../argaze.md/#argaze.GazeFeatures.is_saccade) functions.

### Scan path analysis

A dictionary with all last scan path analysis if new scan step have been added to the [ArFrame.scan_path](../../../argaze.md/#argaze.ArFeatures.ArFrame) object.

### Layers analysis

A dictionary with all layers AOI scan path analysis if new AOI scan step have been added to an [ArLayer.aoi_scan_path](../../../argaze.md/#argaze.ArFeatures.ArLayer) object.

### Execution times

A dictionary with each pipeline step execution time.

### Exception

A [python Exception](https://docs.python.org/3/tutorial/errors.html#exceptions) object raised during pipeline execution.

## Setup ArFrame image parameters

[ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) method parameters can be configured thanks to a python dictionary.

```python
# Assuming ArFrame is loaded
...

# Edit a dict with ArFrame image parameters
image_parameters = {
    "draw_scan_path": {
        ...
    },
    "draw_layers": {
        "MyLayer": {
            ...
        }
    },
    ...
}

# Pass image parameters to ArFrame
ar_frame_image = ar_frame.image(**image_parameters)

# Do something with ArFrame image
...
```