Defining a new PipelineStep decorator to assess time execution and catch exceptions. Improving logging scope.

1 files changed, 36 insertions, 50 deletions

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 9c20c7a..837c8ff 100644
--- a/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
+++ b/docs/user_guide/gaze_analysis_pipeline/advanced_topics/scripting.md
@@ -63,74 +63,68 @@ for name, ar_layer in ar_frame.layers.items():
     ...
 ```
 
-## Pipeline execution outputs
+## Pipeline execution updates
 
-[ArFrame.look](../../../argaze.md/#argaze.ArFeatures.ArFrame.look) method returns many data about pipeline execution.
+Calling [ArFrame.look](../../../argaze.md/#argaze.ArFeatures.ArFrame.look) method leads to update many data into the pipeline.
 
 ```python
 # Assuming that timestamped gaze positions are available
 ...
 
     # Look ArFrame at a timestamped gaze position
-    gaze_position, gaze_movement, scan_path_analysis, execution_times, exception, layers = ar_frame.look(timestamp, gaze_position).values()
+    execution_time, exception = ar_frame.look(timestamp, gaze_position).values()
+
+    # Do something with calibrated gaze position
+    ... ar_frame.gaze_position
 
     # Check if a gaze movement has been identified
-    if gaze_movement.valid and gaze_movement.finished:
+    if ar_frame.gaze_movement.valid and ar_frame.gaze_movement.finished:
 
         # Do something with identified fixation
-        if GazeFeatures.is_fixation(gaze_movement):
+        if GazeFeatures.is_fixation(ar_frame.gaze_movement):
             ...
 
         # Do something with identified saccade
-        elif GazeFeatures.is_saccade(gaze_movement):
+        elif GazeFeatures.is_saccade(ar_frame.gaze_movement):
             ...
 
-        # Do something with scan path analysis
-        for module, analysis in scan_path_analysis.items():
-            for data, value in analysis.items():
-                ...
+    # Check if new scan path analysis are available
+    if ar_frame.new_analysis_available:
 
-        # Do something with ArFrame look execution times
-        ...
+        # Access to each scan path analyzer
+        for analyzer_name, analyzer in ar_frame.scan_path_analyzers.items():
 
-        # Do something with ArFrame look exception
-        if exception:
-            ...
+            # Do something with analysis results
+            ... analyzer.analysis
 
-        # Do something with each ArLayer look data
-        for layer_name, layer_look_data in layers.items():
-            
-            gaze_movement, looked_aoi_name, looked_aoi, aoi_scan_path_analysis, layer_execution_times, layer_exception = layer_look_data.values()
+    # Iterate over each ArFrame layers
+    for name, ar_layer in ar_frame.layers.items():
+    
+        # Check if new aoi scan path analysis are available
+        if ar_layer.new_analysis_available:
 
-            # Do something with gaze movement
-            ...
+            # Access to each aoi scan path analyzer
+            for analyzer_name, analyzer in ar_layer.aoi_scan_path_analyzers.items():
 
-            # Do something with looked AOI name
-            ...
+                # Do something with analysis results
+                ... analyzer.analysis
+```
 
-            # Do something with looked AOI shape
-            ...
+Let's understand the meaning of each data.
 
-            # Do something with ArLayer AOI scan path analysis
-            for module, analysis in aoi_scan_path_analysis.items():
-                for data, value in analysis.items():
-                    ...
+### *execution_times*
 
-            # Do something with ArLayer look execution times
-            ...
+A dictionary with each pipeline step execution time.
 
-            # Do something with ArLayer look exception
-            if exception:
-                ...
-```
+### *exception*
 
-Let's understand the meaning of each returned data.
+A [python Exception](https://docs.python.org/3/tutorial/errors.html#exceptions) object raised during pipeline execution.
 
-### *gaze_position*
+### *ar_frame.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*
+### *ar_frame.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). 
 
@@ -139,21 +133,13 @@ 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.
+### *ar_frame.new_analysis_available* and *ar_layer.new_analysis_available*
 
-### *execution_times*
+This flag allows to now when new scan path and aoi scan path analysis are available.
 
-A dictionary with each pipeline step execution time.
+### *analyzer.analysis*
 
-### *exception*
-
-A [python Exception](https://docs.python.org/3/tutorial/errors.html#exceptions) object raised during pipeline execution.
+A dict containing all data produced by an analyzer.
 
 ## Setup ArFrame image parameters