Refactoring aruco marker pipeline documentation.

1 files changed, 23 insertions, 65 deletions

diff --git a/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md b/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md
index f4bd2d4..c2ee1b9 100644
--- a/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md
+++ b/docs/user_guide/aruco_marker_pipeline/configuration_and_execution.md
@@ -1,17 +1,17 @@
-Load and execute pipeline
+Edit and execute pipeline
 =========================
 
 Once [ArUco markers are placed into a scene](aruco_marker_description.md), they can be detected thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class.
 
 As [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) class also benefits from all the services described in the [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).
 
-![ArUco camera frame](../../img/aruco_camera_frame.png)
+Once defined, an ArUco marker pipeline needs to embedded inside a context that will provides it both gaze positions and camera images to process.
 
-## Load JSON configuration file
+![ArUco camera frame](../../img/aruco_camera_frame.png)
 
-An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) pipeline can be loaded from a JSON configuration file thanks to [argaze.load](../../argaze.md/#argaze.load) package method. 
+## Edit JSON configuration
 
-Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) configuration file example:
+Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) configuration example:
 
 ```json
 {
@@ -52,19 +52,7 @@ Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCam
 }
 ```
 
-Then, here is how to load the JSON file:
-
-```python
-import argaze
-
-# Load ArUcoCamera
-with argaze.load('./configuration.json') as aruco_camera:
-
-	# Do something with ArUcoCamera
-	...
-```
-
-Now, let's understand the meaning of each JSON entry.
+Let's understand the meaning of each JSON entry.
 
 ### argaze.ArUcoMarker.ArUcoCamera.ArUcoCamera
 
@@ -101,62 +89,32 @@ The usual [ArFrame visualization parameters](../gaze_analysis_pipeline/visualiza
 
 ## Pipeline execution
 
-### Detect ArUco markers, estimate scene pose and project 3D AOI
-
-Pass each camera image with timestamp information to the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco marker detection, scene pose estimation and 3D AOI projection.
-
-!!! warning "Mandatory"
-
-	The [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method must be called from a *try* block to catch pipeline exceptions.
-
-```python
-# Assuming that Full HD (1920x1080) images are available with timestamp values
-...:
-
-	# Edit timestamped image
-	timestamped_image = DataFeatures.TimestampedImage(image, timestamp=timestamp)
-
-	try:
+A pipeline needs to be embedded into a context to be executed.
 
-		# Detect ArUco markers, estimate scene pose then, project 3D AOI into camera frame
-		aruco_camera.watch(timestamped_image)
+Copy the gaze analysis pipeline configuration defined above inside the following context configuration.
 
-	# Do something with pipeline exception
-	except Exception as e:
-
-		...
-
-	# Display ArUcoCamera frame image to display detected ArUco markers, scene pose, 2D AOI projection and ArFrame visualization.
-	... aruco_camera.image()
+```json
+{
+    "argaze.utils.contexts.OpenCV.Movie": {
+        "name": "Movie player",
+        "path": "./src/argaze/utils/demo/tobii_record/segments/1/fullstream.mp4",
+        "pipeline": JSON CONFIGURATION
+    }
+}
 ```
 
-### Analyse timestamped gaze positions into the camera frame
-
-As mentioned above, [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and, so, benefits from all the services described in the [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).
-
-Particularly, timestamped gaze positions can be passed one by one to the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole pipeline dedicated to gaze analysis.
+Then, use the [*load* command](../utils/main_commands.md) to execute the context.
 
-!!! warning "Mandatory"
-
-	The [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method must be called from a *try* block to catch pipeline exceptions.
-
-```python
-# Assuming that timestamped gaze positions are available
-...
-
-	try:
+```shell
+python -m argaze load CONFIGURATION
+```
 
-		# Look ArUcoCamera frame at a timestamped gaze position
-		aruco_camera.look(timestamped_gaze_position)
+This command should open a GUI window with the detected markers and identified cursor fixations circles when the mouse moves over the window.
 
-	# Do something with pipeline exception
-	except Exception as e:
-		
-		...
-```
+![ArGaze load GUI](../../img/argaze_load_gui_opencv_pipeline.png)
 
 !!! note ""
 
-	At this point, the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method only detects ArUco marker and the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method only processes gaze movement identification without any AOI support as no scene description is provided into the JSON configuration file.
+	At this point, the pipeline only processes gaze movement identification without any AOI support as no scene description is provided into the JSON configuration file.
 
 	Read the next chapters to learn [how to estimate scene pose](pose_estimation.md), [how to describe a 3D scene's AOI](aoi_3d_description.md) and [how to project them into the camera frame](aoi_3d_projection.md).
\ No newline at end of file