From 913b72b3176dfd4a613f9fb9de1c985fb13b8ad8 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Tue, 19 Sep 2023 13:49:02 +0200
Subject: Working on aruco markers pipeline.

---
 .../aruco_camera_configuration_and_execution.md    | 41 ++++++++++++----------
 1 file changed, 22 insertions(+), 19 deletions(-)

(limited to 'docs/user_guide/aruco_markers_pipeline/aruco_camera_configuration_and_execution.md')

diff --git a/docs/user_guide/aruco_markers_pipeline/aruco_camera_configuration_and_execution.md b/docs/user_guide/aruco_markers_pipeline/aruco_camera_configuration_and_execution.md
index 7b30fd1..824e466 100644
--- a/docs/user_guide/aruco_markers_pipeline/aruco_camera_configuration_and_execution.md
+++ b/docs/user_guide/aruco_markers_pipeline/aruco_camera_configuration_and_execution.md
@@ -1,11 +1,11 @@
 Configure and execute ArUcoCamera
 =================================
 
-Once [ArUco markers are placed into a scene](aruco_scene_creation.md) and [the camera optic have been calibrated](optic_parameters_calibration.md), everything is ready to setup an ArUco marker pipeline thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class.
+Once [ArUco markers are placed into a scene](aruco_markers_description.md) and [areas of interest are described](aoi_description.md), everything is ready to setup an ArUco marker pipeline thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class.
 
 As it inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class benefits from all the services described in [gaze analysis pipeline section](./user_guide/gaze_analysis_pipeline/introduction.md).
 
-![ArUco camera frame](../../img/aruco_camera_frame.png)
+![ArUco camera markers detection](../../img/aruco_camera_markers_detection.png)
 
 ## Load JSON configuration file
 
@@ -19,11 +19,11 @@ Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCa
 	"size": [1920, 1080],
 	"aruco_detector": {
         "dictionary": "DICT_APRILTAG_16h5",
-        "marker_size": 5,
-        "optic_parameters": "optic_parameters.json",
+        "marker_size": 5
     },
     "image_parameters": {
         "background_weight": 1,
+        ...
         "draw_detected_markers": {
             "color": [0, 255, 0],
             "draw_axes": {
@@ -55,36 +55,39 @@ The size of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera)
 
 ### ArUco Detector
 
-The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) pipeline step is to detect ArUco markers inside input image.
+The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) pipeline step is to detect ArUco markers inside input image and estimate their poses.
 
-The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector) is in charge to detect ...
+The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector) is in charge to detect all markers from a specific dictionary with a given size in centimeters.
 
 !!! warning
     JSON *aruco_detector* entry is mandatory.
 
-### Image parameters (inherited from ArFrame)
+### Image parameters - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
 
-...
+The usual [ArFrame visualisation parameters](./user_guide/gaze_analysis_pipeline/visualisation.md) plus one additional *draw_detected_markers* field.
 
 ## Pipeline execution
 
-Timestamped gaze positions have to be passed one by one to [ArFrame.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole intanciated pipeline.
+Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole intanciated pipeline.
 
 ```python
-# Assuming that live Full HD (1920x1080) video stream is enabled
+# Assuming that Full HD (1920x1080) video stream or file is opened
 ...
 
 # Assuming there is a way to escape the while loop
-...
-
-    while video_stream.is_alive():
+while ...:
 
-        # Capture image from video stream
-        image = video_stream.read()
+    # Capture image from video stream of file
+    image = video_capture.read()
 
-        # Detect ArUco markers in image
-        aruco_camera.watch(image)
+    # Detect ArUco markers and more...
+    aruco_camera.watch(image)
 
-        # Do something with ArUcoCamera frame image
-        ...
+    # Display ArUcoCamera frame image to check that ArUco markers are well detected and scene is well projected
+    ... aruco_camera.image()
 ```
+
+!!! warning
+    ArUco markers pose estimation algorithm can lead to errors due to geometric ambiguities as explain in [this article](https://ieeexplore.ieee.org/document/1717461). To discard such ambiguous cases, markers should **not be parallel to camera plan**.
+
+At this point, the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) only detects ArUco markers as no scene description is provided.
\ No newline at end of file
-- 
cgit v1.1