Merge branch 'master' of ssh://git.recherche.enac.fr/interne-ihm-aero/eye-tracking/argaze

11 files changed, 508 insertions, 158 deletions

diff --git a/docs/user_guide/aruco_markers_pipeline/advanced_topics/aruco_detector_configuration.md b/docs/user_guide/aruco_markers_pipeline/advanced_topics/aruco_detector_configuration.md
new file mode 100644
index 0000000..f5b66c6
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/advanced_topics/aruco_detector_configuration.md
@@ -0,0 +1,40 @@
+Improve ArUco markers detection
+===============================
+
+As explain in [OpenCV ArUco documentation](https://docs.opencv.org/4.x/d1/dcd/structcv_1_1aruco_1_1DetectorParameters.html), ArUco markers detection is highly configurable.
+
+## Load ArUcoDetector parameters
+
+[ArUcoCamera.detector.parameters](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.Parameters) can be loaded thanks to a dedicated JSON entry.
+
+Here is an extract from the JSON [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file with ArUco detector parameters:
+
+```json
+{
+    "name": "My FullHD camera",
+    "size": [1920, 1080],
+    "aruco_detector": {
+        "dictionary": "DICT_APRILTAG_16h5",
+        "marker_size": 5,
+        "parameters": {
+		    "cornerRefinementMethod": 3,
+		    "aprilTagQuadSigma": 2,
+		    "aprilTagDeglitch": 1,
+            "useAruco3Detection": 1
+		}
+    },
+    ...
+```
+
+## Print ArUcoDetector parameters
+
+```python
+# Assuming ArUcoCamera is loaded
+...
+
+# Print all ArUcoDetector parameters
+print(aruco_camera.aruco_detector.parameters)
+
+# Print only modified ArUcoDetector parameters
+print(f'{aruco_camera.aruco_detector.parameters:modified}')
+```
diff --git a/docs/user_guide/aruco_markers_pipeline/advanced_topics/optic_parameters_calibration.md b/docs/user_guide/aruco_markers_pipeline/advanced_topics/optic_parameters_calibration.md
index 455d95a..3277216 100644
--- a/docs/user_guide/aruco_markers_pipeline/advanced_topics/optic_parameters_calibration.md
+++ b/docs/user_guide/aruco_markers_pipeline/advanced_topics/optic_parameters_calibration.md
@@ -3,11 +3,11 @@ Calibrate optic parameters
 
 A camera device have to be calibrated to compensate its optical distorsion.
 
-![Optic parameters calibration](../../img/optic_calibration.png)
+![Optic parameters calibration](../../../img/optic_calibration.png)
 
 ## Print calibration board
 
-The first step to calibrate a camera is to create an [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) like in the code below:
+The first step to calibrate a camera is to create an [ArUcoBoard](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) like in the code below:
 
 ``` python
 from argaze.ArUcoMarkers import ArUcoMarkersDictionary, ArUcoBoard
@@ -29,9 +29,9 @@ Let's print the calibration board before to go further.
 
 ## Capture board pictures 
 
-Then, the calibration process needs to make many different captures of an [ArUcoBoard](../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) through the camera and then, pass them to an [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.ArUcoDetector) instance to detect board corners and store them as calibration data into an [ArUcoOpticCalibrator](../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator) for final calibration process.
+Then, the calibration process needs to make many different captures of an [ArUcoBoard](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoBoard) through the camera and then, pass them to an [ArUcoDetector](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector.ArUcoDetector) instance to detect board corners and store them as calibration data into an [ArUcoOpticCalibrator](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator) for final calibration process.
 
-![Calibration step](../../img/optic_calibration_step.png)
+![Calibration step](../../../img/optic_calibration_step.png)
 
 The sample of code below illustrates how to:
 
@@ -131,3 +131,61 @@ Below, an optic_parameters JSON file example:
     ]
 }
 ```
+
+## Load and display optic parameters
+
+[ArUcoCamera.detector.optic_parameters](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator.OpticParameters) can be enabled thanks to a dedicated JSON entry.
+
+Here is an extract from the JSON [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file where optic parameters are loaded and displayed:
+
+```json
+{
+    "name": "My FullHD Camera",
+    "size": [1920, 1080],
+    "aruco_detector": {
+        "dictionary": "DICT_APRILTAG_16h5",
+        "marker_size": 5,
+        "optic_parameters": {
+            "rms": 0.6688921504088245,
+            "dimensions": [
+                1920,
+                1080
+            ],
+            "K": [
+                [
+                    1135.6524381415752,
+                    0.0,
+                    956.0685325355497
+                ],
+                [
+                    0.0,
+                    1135.9272506869524,
+                    560.059099810324
+                ],
+                [
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "D": [
+                0.01655492265003404,
+                0.1985524264972037,
+                0.002129965902489484,
+                -0.0019528582922179365,
+                -0.5792910353639452
+            ]
+        }
+    },
+    ...
+    "image_parameters": {
+        ...
+        "draw_optic_parameters_grid": {
+            "width": 192,
+            "height": 108,
+            "z": 100,
+            "point_size": 1,
+            "point_color": [0, 0, 255]
+        }
+    }
+```
\ No newline at end of file
diff --git a/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md b/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
new file mode 100644
index 0000000..892d6dd
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
@@ -0,0 +1,136 @@
+Script the pipeline
+===================
+
+All aruco markers pipeline objects are accessible from Python script.
+This could be particularly useful for realtime AR interaction applications.
+
+## Load ArUcoCamera configuration from dictionary
+
+First of all, [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration can be loaded from a python dictionary.
+
+```python
+from argaze.ArUcoMarkers import ArUcoCamera
+
+# Edit a dict with ArUcoCamera configuration
+configuration = {
+	"name": "My FullHD camera",
+    "size": (1920, 1080),
+    ...
+    "aruco_detector": {
+        ...
+    },
+    "scenes": {
+        "MyScene" : {
+             "aruco_markers_group": {
+                ...
+            },
+            "layers": {
+                "MyLayer": {
+                    "aoi_scene": {
+                    ...
+                    }
+                },
+                ...
+            }
+        },
+        ...
+    }
+    "layers": {
+        "MyLayer": {
+            ...
+        },
+        ...
+    },
+    "image_parameters": {
+        ...
+    }
+}
+
+# Load ArUcoCamera
+aruco_camera = ArUcoCamera.ArUcoCamera.from_dict(configuration)
+
+# Do something with ArUcoCamera
+...
+```
+
+## Access to ArUcoCamera and ArScenes attributes
+
+Then, once the configuration is loaded, it is possible to access to its attributes: [read ArUcoCamera code reference](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) to get a complete list of what is available.
+
+Thus, the [ArUcoCamera.scenes](../../../argaze.md/#argaze.ArFeatures.ArCamera) attribute allows to access each loaded aruco scene and so, access to their attributes: [read ArUcoScene code reference](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) to get a complete list of what is available.
+
+```python
+from argaze import ArFeatures
+
+# Assuming the ArUcoCamera is loaded
+...
+
+# Iterate over each ArUcoCamera scene
+for name, aruco_scene in aruco_camera.scenes.items():
+    ...
+```
+
+## Pipeline execution outputs
+
+[ArUcoCamera.watch](../../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method returns data about pipeline execution.
+
+```python
+# Assuming that images are available
+...:
+
+    # Watch image with ArUco camera
+    detection_time, projection_time, exception = aruco_camera.watch(image)
+
+    # Do something with pipeline times
+    ...
+
+    # Do something with pipeline exception
+    if exception:
+        ...
+```
+
+Let's understand the meaning of each returned data.
+
+### *detection_time*
+
+ArUco marker detection time in ms.
+
+### *projection_time*
+
+Scenes projection time in ms.
+
+### *exception*
+
+A [python Exception](https://docs.python.org/3/tutorial/errors.html#exceptions) object raised during pipeline execution.
+
+## Setup ArUcoCamera image parameters
+
+Specific [ArUcoCamera.image](../../../argaze.md/#argaze.ArFeatures.ArFrame.image) method parameters can be configured thanks to a python dictionary.
+
+```python
+# Assuming ArUcoCamera is loaded
+...
+
+# Edit a dict with ArUcoCamera image parameters
+image_parameters = {
+    "draw_detected_markers": {
+        ...
+    },
+    "draw_scenes": {
+        ...   
+    },
+    "draw_optic_parameters_grid": {
+        ...
+    },
+    ...
+}
+
+# Pass image parameters to ArUcoCamera
+aruco_camera_image = aruco_camera.image(**image_parameters)
+
+# Do something with ArUcoCamera image
+...
+```
+
+!!! note
+    [ArUcoCamera](../../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) inherits from [ArFrame](../../../argaze.md/#argaze.ArFeatures.ArFrame) and so, benefits from all image parameters described in [gaze analysis pipeline visualisation section](../../gaze_analysis_pipeline/visualisation.md).
\ No newline at end of file
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
new file mode 100644
index 0000000..b02bc9e
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
@@ -0,0 +1,53 @@
+Describe 3D AOI
+===============
+
+Now [scene pose is estimated](aruco_markers_description.md) thanks to ArUco markers description, [areas of interest (AOI)](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) need to be described into the same 3D referential.
+
+In the example scene, the screen and the sheet are considered as areas of interest.
+
+![3D AOI description](../../img/aoi_3d_description.png)
+
+All AOI need to be described from same origin than markers in a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where:
+
+* +X is pointing to the right,
+* +Y is pointing to the top,
+* +Z is pointing to the backward.
+
+!!! warning
+	All AOI spatial values must be given in **centimeters**.
+
+### Edit OBJ file description
+
+OBJ file format could be exported from most 3D editors.
+
+``` obj
+o Sheet
+v 14.200000 -3.000000 28.350000
+v 35.200000 -3.000000 28.350000
+v 14.200000 -3.000000 -1.35
+v 35.200000 -3.000000 -1.35
+f 1 2 4 3
+o Screen
+v 2.750000 2.900000 -0.500000
+v 49.250000 2.900000 -0.500000
+v 2.750000 29.100000 -0.500000
+v 49.250000 29.100000 -0.500000
+f 5 6 8 7
+```
+
+Here are common OBJ file features needed to describe AOI:  
+
+* Object lines (starting with *o* key) indicate AOI name.
+* Vertice lines (starting with *v* key) indicate AOI vertices.
+* Face (starting with *f* key) link vertices together.
+
+### Edit JSON file description
+
+JSON file format allows to describe AOI vertices.
+
+``` json
+{
+    "Sheet": [[14.2, -3, 28.35], [35.2, -3, 28.35], [14.2, -3, -1.35], [35.2, -3, -1.35]],
+    "Screen": [[2.75, 2.9, -0.5], [49.25, 2.9, -0.5], [2.75, 29.1, -0.5], [49.25, 29.1, -0.5]]
+}
+```
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md
new file mode 100644
index 0000000..f1ae1f6
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md
@@ -0,0 +1,128 @@
+Define a 3D AOI as a frame
+==========================
+
+When an 3D AOI of the scene contains others coplanar 3D AOI, like a screen with GUI elements displayed on, it is better to described them as 2D AOI inside 2D coordinates system related to the containing 3D AOI.
+
+![3D AOI frame](../../img/aruco_camera_aoi_frame.png)
+
+## Add ArFrame to ArUcoScene
+
+The [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) class defines a rectangular area where timestamped gaze positions are projected in and inside which they need to be analyzed.
+
+Here is the previous extract where "Screen" AOI is defined as a frame into [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) configuration:
+
+```json
+{
+    "name": "My FullHD camera",
+    "size": [1920, 1080],
+    ...
+    "scenes": {
+        "MyScene" : {
+            "aruco_markers_group": {
+                ...
+            },
+            "layers": {
+                "MyLayer": {
+                    "aoi_scene": {
+                        "Sheet": [[14.2, -3, 28.35], [35.2, -3, 28.35], [14.2, -3, -1.35], [35.2, -3, -1.35]],
+                        "Screen": [[2.75, 2.9, -0.5], [49.25, 2.9, -0.5], [2.75, 29.1, -0.5], [49.25, 29.1, -0.5]]
+                    }
+                }
+            },
+            "frames": {
+            	"Screen": {
+            		"size": [1920, 1080],
+            		"layers": {
+            			"MyLayer": {
+            				"aoi_scene": {
+                                "GeoSector": [[860, 160], [1380, 100], [1660, 400], [1380, 740], [1440, 960], [920, 920], [680, 800], [640, 560]],
+                                "LeftPanel": {
+                                    "Rectangle": {
+                                        "x": 0,
+                                        "y": 0,
+                                        "width": 350,
+                                        "height": 1080
+                                    }
+                                },
+                                "CircularWidget": {
+                                    "Circle": {
+                                        "cx": 1800,
+                                        "cy": 120,
+                                        "radius": 80
+                                    }
+                                }
+                            }
+            			}
+            		}
+            	}
+            }
+        }
+    }
+    ...
+}
+```
+Now, let's understand the meaning of each JSON entry.
+
+### *frames*
+
+An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can contains multiples [ArFrames](../../argaze.md/#argaze.ArFeatures.ArFrame) stored by name.
+
+### Screen
+
+The name of a 3D AOI **and** an [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically useful for visualisation purpose.
+
+!!! warning "AOI / Frame names policy"
+
+    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layer 3D AOI is defined as an [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frame, **provided they have the same name**.
+
+!!! warning "Layer name policy"
+
+    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frame layer is projected into [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layer, **provided they have the same name**.
+
+!!! note
+
+    [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frame layers are projected into their dedicated [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layers when the JSON configuration file is loaded.
+
+## Pipeline execution
+
+### Map ArUcoCamera image into ArUcoScenes frames
+
+After camera image is passed to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method, it is possible to apply a perpective transformation in order to project watched image into each [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) [frames background](../../argaze.md/#argaze.ArFeatures.ArFrame) image.
+
+```python
+# Assuming that Full HD (1920x1080) video stream or file is opened
+...
+
+# Assuming that the video reading is handled in a looping code block
+...:
+
+    # Capture image from video stream of file
+    image = video_capture.read()
+
+    # Detect ArUco markers, estimate scene pose then, project 3D AOI into camera frame
+    aruco_camera.watch(image)
+
+    # Map watched image into ArUcoScenes frames background
+    aruco_camera.map()
+```
+
+### Analyse timestamped gaze positions into ArUcoScenes frames
+
+[ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).
+
+!!! note
+
+    Timestamped gaze positions passed to [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method are projected into [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames if applicable.
+
+### Display each ArUcoScenes frames
+
+All [ArUcoScenes](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) frames image can be displayed as any [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame).
+
+```python
+    ...
+
+    # Display all ArUcoScenes frames
+    for frame in aruco_camera.scene_frames:
+
+        ... frame.image()
+```
\ No newline at end of file
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_projection.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
index 027f805..8c7310b 100644
--- a/docs/user_guide/aruco_markers_pipeline/aoi_projection.md
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
@@ -1,15 +1,15 @@
-Project AOI into camera frame
-=============================
+Project 3D AOI into camera frame
+================================
 
-Once [ArUcoScene pose is estimated](pose_estimation.md) and [AOI are described](aoi_description.md), AOI can be projected into [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame.
+Once [ArUcoScene pose is estimated](pose_estimation.md) and [3D AOI are described](aoi_3d_description.md), AOI can be projected into [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame.
 
-![AOI projection](../../img/aruco_camera_aoi_projection.png)
+![3D AOI projection](../../img/aruco_camera_aoi_projection.png)
 
-## Add ArLayer to ArUcoScene to load AOI
+## Add ArLayer to ArUcoScene to load 3D AOI
 
-The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class allows to load areas of interest description. An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer).
+The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class allows to load 3D AOI description. 
 
-Here is the previous extract where one layer is added to the [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) configuration:
+Here is the previous extract where one layer is added to [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) configuration:
 
 ```json
 {
@@ -24,9 +24,8 @@ Here is the previous extract where one layer is added to the [ArUcoScene](../../
             "layers": {
                 "MyLayer": {
                     "aoi_scene": {
-                        "YellowSquare": [[6.2, -7.275252, 25.246159], [31.2, -7.275252, 25.246159], [31.2, 1.275252, 1.753843], [6.2, 1.275252, 1.753843]],
-                        "GrayRectangle": [[2.5, 2.5, -0.5], [37.5, 2.5, -0.5], [37.5, 27.5, -0.5], [2.5, 27.5, -0.5]],
-                        "BlueTriangle": [[12.5, 7.5, -0.5], [27.5, 7.5, -0.5], [20, 22.5, -0.5]]
+                        "Sheet": [[14.2, -3, 28.35], [35.2, -3, 28.35], [14.2, -3, -1.35], [35.2, -3, -1.35]],
+                        "Screen": [[2.75, 2.9, -0.5], [49.25, 2.9, -0.5], [2.75, 29.1, -0.5], [49.25, 29.1, -0.5]]
                     }
                 }
             } 
@@ -38,17 +37,21 @@ Here is the previous extract where one layer is added to the [ArUcoScene](../../
 
 Now, let's understand the meaning of each JSON entry.
 
-### "MyLayer"
+### *layers*
 
-The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
+An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.
 
-### AOI Scene
+### MyLayer
 
-The [AOIScene](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AOIScene) defines a set of 3D [AreaOfInterest](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) registered by name.
+The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
 
-## Add ArLayer to ArUcoCamera to project AOI
+### *aoi_scene*
 
-Here is the previous extract where one layer is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) and displayed:
+The set of 3D AOI into the layer as defined at [3D AOI description chapter](aoi_3d_description.md).
+
+## Add ArLayer to ArUcoCamera to project 3D AOI into
+
+Here is the previous extract where one layer is added to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration and displayed:
 
 ```json
 {
@@ -91,21 +94,25 @@ Here is the previous extract where one layer is added to the [ArUcoCamera](../..
 
 Now, let's understand the meaning of each JSON entry.
 
-### "MyLayer"
+### *layers*
+
+An [ArUcoCamera](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.
+
+### MyLayer
 
-The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
+The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
 
 !!! warning "Layer name policy"
 
-    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layer is projected into [an ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer, **provided they have the same name**.
+    An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layer is projected into an [ ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer, **provided they have the same name**.
 
 !!! note
 
     [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) layers are projected into their dedicated [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layers when calling the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method.
 
-## Add AOI analysis
+## Add AOI analysis features to ArUcoCamera layer
 
-When a scene layer is projected into a camera layer, it means that the 3D [ArLayer.aoi_scene](../../argaze.md/#argaze.ArFeatures.ArLayer.aoi_scene) description of the scene becomes the 2D camera's [ArLayer.aoi_scene](../../argaze.md/#argaze.ArFeatures.ArLayer.aoi_scene) description of the camera.
+When a scene layer is projected into a camera layer, it means that the 3D scene's AOI are transformed into 2D camera's AOI.
 
 Therefore, it means that [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) benefits from all the services described in [AOI analysis pipeline section](../gaze_analysis_pipeline/aoi_analysis.md).
 
@@ -156,4 +163,4 @@ Here is the previous extract where AOI matcher, AOI scan path and AOI scan path
 
 !!! warning
 
-    Adding scan path and scan path analyzers to an [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer doesn't make sense if the camera is moving.
+    Adding scan path and scan path analyzers to an [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer doesn't make sense as the space viewed thru camera frame doesn't necessary reflect the space the gaze is covering.
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_description.md b/docs/user_guide/aruco_markers_pipeline/aoi_description.md
deleted file mode 100644
index 101ec9f..0000000
--- a/docs/user_guide/aruco_markers_pipeline/aoi_description.md
+++ /dev/null
@@ -1,62 +0,0 @@
-Describe AOI
-============
-
-Once [ArUco markers are placed into a scene](aruco_markers_description.md), areas of interest need to be described into the same 3D referential.
-
-In the example scene, each screen is considered as an area of interest more the blue triangle area inside the top screen.
-
-![AOI description](../../img/aoi_description.png)
-
-All AOIs need to be described from same origin than markers in a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where:
-
-* +X is pointing to the right,
-* +Y is pointing to the top,
-* +Z is pointing to the backward.
-
-!!! warning
-	All AOIs spatial values must be given in **centimeters**.
-
-### Edit OBJ file description
-
-OBJ file format could be exported from most 3D editors.
-
-``` obj
-o YellowSquare
-v 6.200003 -7.275252 25.246159
-v 31.200003 -7.275252 25.246159
-v 6.200003 1.275252 1.753843
-v 31.200003 1.275252 1.753843
-s off
-f 1 2 4 3
-o GrayRectangle
-v 2.500000 2.500000 -0.500000
-v 37.500000 2.500000 -0.500000
-v 2.500000 27.500000 -0.500000
-v 37.500000 27.500000 -0.500000
-s off
-f 5 6 8 7
-o BlueTriangle
-v 12.500002 7.500000 -0.500000
-v 27.500002 7.500000 -0.500000
-v 20.000002 22.500000 -0.500000
-s off
-f 9 10 11
-```
-
-Here are common OBJ file features needed to describe AOIs:  
-
-* Object lines (starting with *o* key) indicate AOI name.
-* Vertice lines (starting with *v* key) indicate AOI vertices.
-* Face (starting with *f* key) link vertices together.
-
-### Edit JSON file description
-
-JSON file format allows to describe AOIs vertices.
-
-``` json
-{
-    "YellowSquare": [[6.2, -7.275252, 25.246159], [31.2, -7.275252, 25.246159], [31.2, 1.275252, 1.753843], [6.2, 1.275252, 1.753843]],
-    "GrayRectangle": [[2.5, 2.5, -0.5], [37.5, 2.5, -0.5], [37.5, 27.5, -0.5], [2.5, 27.5, -0.5]],
-    "BlueTriangle": [[12.5, 7.5, -0.5], [27.5, 7.5, -0.5], [20, 22.5, -0.5]]
-}
-```
diff --git a/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md b/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md
index 1c13013..6380f88 100644
--- a/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md
+++ b/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md
@@ -3,11 +3,11 @@ Set up ArUco markers
 
 First of all, ArUco markers needs to be printed and placed into the scene. 
 
-Here is an example scene where markers are surrounding a multi-screen workspace with a triangle area inside one of them.
+Here is an example scene where markers are surrounding a workspace with a screen and a sheet on the table (considering the sheet stays static for the moment).
 
 ![Scene](../../img/scene.png)
 
-## Print ArUco markers from a ArUco dictionary
+## Print ArUco markers from an ArUco dictionary
 
 ArUco markers always belongs to a set of markers called ArUco markers dictionary.
 
@@ -65,24 +65,18 @@ v 0.000000 0.000000 0.000000
 v 5.000000 0.000000 0.000000
 v 0.000000 5.000000 0.000000
 v 5.000000 5.000000 0.000000
-vn 0.0000 0.0000 1.0000
-s off
 f 1//1 2//1 4//1 3//1
 o DICT_APRILTAG_16h5#1_Marker
-v -1.767767 23.000002 3.767767
-v 1.767767 23.000002 0.232233
-v -1.767767 28.000002 3.767767
-v 1.767767 28.000002 0.232233
-vn 0.7071 0.0000 0.7071
-s off
+v -0.855050 24.000002 4.349232
+v 0.855050 24.000002 -0.349231
+v -0.855050 29.000002 4.349232
+v 0.855050 29.000002 -0.349231
 f 5//2 6//2 8//2 7//2
 o DICT_APRILTAG_16h5#2_Marker
-v 33.000000 -1.767767 4.767767
-v 38.000000 -1.767767 4.767767
-v 33.000000 1.767767 1.232233
-v 38.000000 1.767767 1.232233
-vn 0.0000 0.7071 0.7071
-s off
+v 44.000000 0.000000 9.500000
+v 49.000000 0.000000 9.500000
+v 44.000000 -0.000000 4.500000
+v 49.000000 -0.000000 4.500000
 f 9//3 10//3 12//3 11//3
 ```
 
@@ -90,7 +84,6 @@ Here are common OBJ file features needed to describe ArUco markers places:
 
 * Object lines (starting with *o* key) indicate markers dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker.
 * Vertice lines (starting with *v* key) indicate markers corners. The marker size will be automatically deducted from the geometry.
-* Plane normals (starting with *vn* key) need to be exported for further pose estimation.
 * Face (starting with *f* key) link vertices and normals indexes together.
 
 !!! warning
@@ -110,12 +103,12 @@ JSON file format allows to describe markers places using translation and euler a
             "rotation": [0, 0, 0]
         },
         "1": {
-            "translation": [0, 25.5, 2],
-            "rotation": [0, 45, 0]
+            "translation": [0, 26.5, 2],
+            "rotation": [0, 70, 0]
         },
         "2": {
-            "translation": [35.5, 0, 3],
-            "rotation": [-45, 0, 0]
+            "translation": [46.5, 0, 7],
+            "rotation": [-90, 0, 0]
         }
     }
 }
diff --git a/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md b/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
index 81c577f..60a1115 100644
--- a/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
+++ b/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
@@ -3,7 +3,7 @@ Load and execute pipeline
 
 Once [ArUco markers are placed into a scene](aruco_markers_description.md), they can be detected thanks to [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class.
 
-As [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class also benefits from all the services described in [gaze analysis pipeline section](./user_guide/gaze_analysis_pipeline/introduction.md).
+As [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame), the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) class also benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).
 
 ![ArUco camera frame](../../img/aruco_camera_frame.png)
 
@@ -29,6 +29,12 @@ Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCa
     },
     "image_parameters": {
         "background_weight": 1,
+        "draw_detected_markers": {
+            "color": [0, 255, 0],
+            "draw_axes": {
+                "thickness": 3
+            }
+        },
         "draw_gaze_positions": {
             "color": [0, 255, 255],
             "size": 2
@@ -40,12 +46,6 @@ Here is a simple JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCa
         }, 
         "draw_saccades": {
             "line_color": [255, 0, 255]
-        },
-        "draw_detected_markers": {
-            "color": [0, 255, 0],
-            "draw_axes": {
-                "thickness": 3
-            }
         }
     }
 }
@@ -62,15 +62,15 @@ aruco_camera = ArUcoCamera.ArUcoCamera.from_json('./configuration.json')
 
 Now, let's understand the meaning of each JSON entry.
 
-### Name - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
+### *name - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
 
 The name of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame. Basically useful for visualisation purpose.
 
-### Size - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
+### *size - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
 
 The size of the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame  in pixels. Be aware that gaze positions have to be in the same range of value to be projected in.
 
-### ArUco Detector
+### *aruco_detector*
 
 The first [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) pipeline step is to detect ArUco markers inside input image and estimate their poses.
 
@@ -81,21 +81,21 @@ The [ArUcoDetector](../../argaze.md/#argaze.ArUcoMarkers.ArUcoDetector) is in ch
 !!! warning "Mandatory"
     JSON *aruco_detector* entry is mandatory.
 
-### Gaze Movement Identifier - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
+### *gaze_movement_identifier - inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame)*
 
 The first [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) pipeline step dedicated to identify fixations or saccades from consecutive timestamped gaze positions.
 
 ![Gaze movement identification](../../img/aruco_camera_gaze_movement_identification.png)
 
-### Image parameters - *inherited from [ArFrame](../../argaze.md/#argaze.ArFeatures.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.
+The usual [ArFrame visualisation parameters](../gaze_analysis_pipeline/visualisation.md) plus one additional *draw_detected_markers* field.
 
 ## Pipeline execution
 
-### Detect ArUco markers, estimate scene pose and project AOI
+### Detect ArUco markers, estimate scene pose and project 3D AOI
 
-Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco markers detection, scene pose estimation and AOI projection.
+Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method to execute the whole pipeline dedicated to ArUco markers detection, scene pose estimation and 3D AOI projection.
 
 ```python
 # Assuming that Full HD (1920x1080) video stream or file is opened
@@ -107,19 +107,16 @@ Pass each camera image to [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures
     # Capture image from video stream of file
     image = video_capture.read()
 
-    # Detect ArUco markers, estimate scene pose then, project AOI into camera frame
+    # Detect ArUco markers, estimate scene pose then, project 3D AOI into camera frame
     aruco_camera.watch(image)
 
-    # Display ArUcoCamera frame image to display detected ArUco markers, scene pose, AOI projection and ArFrame visualisation.
+    # Display ArUcoCamera frame image to display detected ArUco markers, scene pose, 2D AOI projection and ArFrame visualisation.
     ... aruco_camera.image()
 ```
 
-!!! warning "Pose estimation error"
-    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 **as less as possible be parallel to camera plan**.
-
 ### Analyse timestamped gaze positions into camera frame
 
-As mentioned above, [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and so, benefits from all the services described in [gaze analysis pipeline section](./user_guide/gaze_analysis_pipeline/introduction.md).
+As mentioned above, [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) inherits from [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and so, benefits from all the services described in [gaze analysis pipeline section](../gaze_analysis_pipeline/introduction.md).
 
 Particularly, timestamped gaze positions can be passed one by one to [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArFrame.look) method to execute the whole pipeline dedicated to gaze analysis.
 
@@ -135,4 +132,4 @@ Particularly, timestamped gaze positions can be passed one by one to [ArUcoCamer
 
     At this point, the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method only detects ArUco markers and the [ArUcoCamera.look](../../argaze.md/#argaze.ArFeatures.ArCamera.look) method only process 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) and [how to project AOI](aoi_projection.md).
\ No newline at end of file
+    Read the next chapters to learn [how to estimate scene pose](pose_estimation.md), [how to describe 3D scene's AOI](aoi_3d_description.md) and [how to project them into camera frame](aoi_3d_projection.md).
\ No newline at end of file
diff --git a/docs/user_guide/aruco_markers_pipeline/introduction.md b/docs/user_guide/aruco_markers_pipeline/introduction.md
index 836569a..37ab055 100644
--- a/docs/user_guide/aruco_markers_pipeline/introduction.md
+++ b/docs/user_guide/aruco_markers_pipeline/introduction.md
@@ -1,29 +1,29 @@
 Overview
 ========
 
-This section explains how to build augmented reality pipelines based on ArUco Markers technology for various use cases.  
+This section explains how to build augmented reality pipelines based on [ArUco Markers technology](https://www.sciencedirect.com/science/article/abs/pii/S0031320314000235) for various use cases.  
 
-The OpenCV library provides a module to detect fiducial markers into a picture and estimate their poses (cf [OpenCV ArUco tutorial page](https://docs.opencv.org/4.x/d5/dae/tutorial_aruco_detection.html)).
+The OpenCV library provides a module to detect fiducial markers into a picture and estimate their poses.
 
-![OpenCV ArUco markers](https://pyimagesearch.com/wp-content/uploads/2020/12/aruco_generate_tags_header.png)
+![OpenCV ArUco markers](../../img/opencv_aruco.png)
 
-The ArGaze [ArUcoMarkers submodule](../../argaze.md/#argaze.ArUcoMarkers) eases markers creation, optic calibration, markers detection and 3D scene pose estimation through a set of high level classes.
+The ArGaze [ArUcoMarkers submodule](../../argaze.md/#argaze.ArUcoMarkers) eases markers creation, markers detection and 3D scene pose estimation through a set of high level classes.
 
-First, let's look at the schema below: it gives an overview of the main notions involved in the following chapters.
+<!-- First, let's look at the schema below: it gives an overview of the main notions involved in the following chapters. -->
 
-![ArUco markers pipeline](../../img/aruco_markers_pipeline.png)
+<!-- ![ArUco markers pipeline](../../img/aruco_markers_pipeline.png) -->
 
 To build your own ArUco markers pipeline, you need to know:
 
 * [How to setup ArUco markers into a scene](aruco_markers_description.md),
-* [How to describe scene's AOI](aoi_description.md),
 * [How to load and execute ArUco markers pipeline](configuration_and_execution.md),
 * [How to estimate scene pose](pose_estimation.md),
-* [How to project AOI into camera frame](aoi_projection.md),
-* [How to visualize ArUcoCamera and ArUcoScenes](visualisation.md)
+* [How to describe scene's AOI](aoi_3d_description.md),
+* [How to project 3D AOI into camera frame](aoi_3d_projection.md),
+* [How to define a 3D AOI as a frame](aoi_3d_frame.md).
 
 More advanced features are also explained like:
 
-* [How to script ArUco markers pipeline](advanced_topics/scripting.md)
-* [How to calibrate optic parameters](optic_parameters_calibration.md)
-* [How to improve ArUco markers detection](advanced_topics/aruco_detector_configuration.md)
+* [How to script ArUco markers pipeline](advanced_topics/scripting.md),
+* [How to calibrate optic parameters](advanced_topics/optic_parameters_calibration.md),
+* [How to improve ArUco markers detection](advanced_topics/aruco_detector_configuration.md).
diff --git a/docs/user_guide/aruco_markers_pipeline/pose_estimation.md b/docs/user_guide/aruco_markers_pipeline/pose_estimation.md
index 6acafee..6b58b24 100644
--- a/docs/user_guide/aruco_markers_pipeline/pose_estimation.md
+++ b/docs/user_guide/aruco_markers_pipeline/pose_estimation.md
@@ -1,13 +1,13 @@
 Estimate scene pose
 ===================
 
-An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) class defines a space with [ArUco markers inside](aruco_markers_description.md) helping to estimate scene pose when they are watched by [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera).
+Once [ArUco markers are placed into a scene](aruco_markers_description.md) and [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) is [configured](configuration_and_execution.md), scene pose can be estimated.
 
 ![Scene pose estimation](../../img/aruco_camera_pose_estimation.png)
 
 ## Add ArUcoScene to ArUcoCamera JSON configuration file
 
-An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) instance can contains multiples [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene).
+An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) class defines a space with [ArUco markers inside](aruco_markers_description.md) helping to estimate scene pose when they are watched by [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera).
 
 Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file with a sample where one scene is added and displayed:
 
@@ -27,17 +27,17 @@ Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMark
                         "rotation": [0, 0, 0]
                     },
                     "1": {
-                        "translation": [0, 25.5, 2],
-                        "rotation": [0, 45, 0]
+                        "translation": [0, 26.5, 2],
+                        "rotation": [0, 70, 0]
                     },
                     "2": {
-                        "translation": [35.5, 0, 3],
-                        "rotation": [-45, 0, 0]
+                        "translation": [46.5, 0, 7],
+                        "rotation": [-90, 0, 0]
                     }
                 }
             } 
         }
-    }
+    },
     ...
     "image_parameters": {
         ...
@@ -51,10 +51,6 @@ Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMark
                     "draw_places": {
                         "color": [0, 0, 0],
                         "border_size": 1
-                    },
-                    "draw_places_axes": {
-                        "thickness": 1,
-                        "length": 2.5
                     }
                 }
             }
@@ -65,11 +61,15 @@ Here is an extract from the JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMark
 
 Now, let's understand the meaning of each JSON entry.
 
-### "MyScene"
+### *scenes*
+
+An [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) instance can contains multiples [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) stored by name.
+
+### MyScene
 
-The name of the [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene). Basically useful for visualisation purpose.
+The name of an [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene). Basically useful for visualisation purpose.
 
-### ArUco markers group
+### *aruco_markers_group*
 
 The 3D places of ArUco markers into the scene as defined at [ArUco markers description chapter](aruco_markers_description.md). Thanks to this description, it is possible to estimate the pose of [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) in [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) frame.
 
@@ -77,6 +77,6 @@ The 3D places of ArUco markers into the scene as defined at [ArUco markers descr
 
     [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) pose estimation is done when calling the [ArUcoCamera.watch](../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method.
 
-### Draw scenes
+### *draw_scenes*
 
 The drawing parameters of each loaded [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) in [ArUcoCamera.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image).