From 52e64be5bdbbb63ec81d1ba285c6f974845a434c Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 3 Jul 2024 18:51:14 +0200
Subject: Refactoring aruco marker pipeline documentation.

---
 .../advanced_topics/scripting.md                   | 77 +++++++++++++++++++---
 1 file changed, 68 insertions(+), 9 deletions(-)

(limited to 'docs/user_guide/aruco_marker_pipeline/advanced_topics')

diff --git a/docs/user_guide/aruco_marker_pipeline/advanced_topics/scripting.md b/docs/user_guide/aruco_marker_pipeline/advanced_topics/scripting.md
index c81d57d..d3a340b 100644
--- a/docs/user_guide/aruco_marker_pipeline/advanced_topics/scripting.md
+++ b/docs/user_guide/aruco_marker_pipeline/advanced_topics/scripting.md
@@ -74,35 +74,80 @@ from argaze import ArFeatures
         ...
 ```
 
-## Pipeline execution outputs
+## Pipeline execution
 
-The [ArUcoCamera.watch](../../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method returns data about 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 timestamped images are available
+# Assuming that Full HD (1920x1080) images are available with timestamp values
 ...:
 
+    # Edit timestamped image
+    timestamped_image = DataFeatures.TimestampedImage(image, timestamp=timestamp)
+
     try:
 
-        # Watch image with ArUco camera
-        aruco_camera.watch(image, timestamp=timestamp)
+        # Detect ArUco markers, estimate scene pose then, project 3D AOI into camera frame
+        aruco_camera.watch(timestamped_image)
 
     # Do something with pipeline exception
     except Exception as e:
 
         ...
 
-    # Do something with detected_markers
-    ... aruco_camera.aruco_detector.detected_markers()
+    # Display ArUcoCamera frame image to display detected ArUco markers, scene pose, 2D AOI projection and ArFrame visualization.
+    ... aruco_camera.image()
+```
+
+### Detection outputs
+
+The [ArUcoCamera.watch](../../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method returns data about pipeline execution.
+
+```python
+# Assuming that watch method has been called
+
+# Do something with detected_markers
+... aruco_camera.aruco_detector.detected_markers()
     
 ```
 
 Let's understand the meaning of each returned data.
 
-### *aruco_camera.aruco_detector.detected_markers()*
+#### *aruco_camera.aruco_detector.detected_markers()*
 
 A dictionary containing all detected markers is provided by [ArUcoDetector](../../../argaze.md/#argaze.ArUcoMarker.ArUcoDetector) class.
 
+### 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.
+
+!!! 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:
+
+        # Look ArUcoCamera frame at a timestamped gaze position
+        aruco_camera.look(timestamped_gaze_position)
+
+    # Do something with pipeline exception
+    except Exception as e:
+        
+        ...
+```
+
 ## Setup ArUcoCamera image parameters
 
 Specific [ArUcoCamera.image](../../../argaze.md/#argaze.ArFeatures.ArFrame.image) method parameters can be configured thanks to a Python dictionary.
@@ -133,4 +178,18 @@ aruco_camera_image = aruco_camera.image(**image_parameters)
 ```
 
 !!! note
-    [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../../argaze.md/#argaze.ArFeatures.ArFrame) and, so, benefits from all image parameters described in [gaze analysis pipeline visualization section](../../gaze_analysis_pipeline/visualization.md).
\ No newline at end of file
+    [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarker.ArUcoCamera) inherits from [ArFrame](../../../argaze.md/#argaze.ArFeatures.ArFrame) and, so, benefits from all image parameters described in [gaze analysis pipeline visualization section](../../gaze_analysis_pipeline/visualization.md).
+
+
+## Display ArUcoScene frames
+
+All [ArUcoScene](../../argaze.md/#argaze.ArUcoMarker.ArUcoScene) frames image can be displayed as any [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame).
+
+```python
+    ...
+
+    # Display all ArUcoScene frames
+    for frame in aruco_camera.scene_frames():
+
+        ... frame.image()
+```
\ No newline at end of file
-- 
cgit v1.1