From c12e429190b4f63064c81edfa08fb00b8ed8a28c Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Thu, 28 Sep 2023 23:31:33 +0200
Subject: Improving documentation details.

---
 docs/img/aruco_camera_aoi_frame.png                | Bin 41104 -> 49405 bytes
 docs/img/aruco_camera_aoi_projection.png           | Bin 34892 -> 37858 bytes
 docs/img/scene.png                                 | Bin 32079 -> 41117 bytes
 .../advanced_topics/scripting.md                   |   4 +--
 .../aruco_markers_pipeline/aoi_3d_description.md   |   4 +--
 .../aruco_markers_pipeline/aoi_3d_frame.md         |   2 +-
 .../aruco_markers_pipeline/aoi_3d_projection.md    |   4 +--
 .../aruco_markers_description.md                   |   5 +--
 .../configuration_and_execution.md                 |  14 ++++-----
 .../aruco_markers_pipeline/introduction.md         |   4 +--
 .../gaze_analysis_pipeline/aoi_2d_description.md   |   2 +-
 .../gaze_analysis_pipeline/aoi_analysis.md         |   4 +--
 .../gaze_analysis_pipeline/background.md           |   4 +--
 docs/user_guide/gaze_analysis_pipeline/heatmap.md  |   8 ++---
 .../gaze_analysis_pipeline/introduction.md         |   2 +-
 docs/user_guide/gaze_analysis_pipeline/logging.md  |   4 +--
 .../gaze_analysis_pipeline/visualisation.md        |  34 ++++++++++-----------
 docs/user_guide/utils/ready-made_scripts.md        |   2 +-
 mkdocs.yml                                         |   2 +-
 19 files changed, 47 insertions(+), 52 deletions(-)

diff --git a/docs/img/aruco_camera_aoi_frame.png b/docs/img/aruco_camera_aoi_frame.png
index 944f9ff..f21cc8d 100644
Binary files a/docs/img/aruco_camera_aoi_frame.png and b/docs/img/aruco_camera_aoi_frame.png differ
diff --git a/docs/img/aruco_camera_aoi_projection.png b/docs/img/aruco_camera_aoi_projection.png
index ec708db..df1ec4c 100644
Binary files a/docs/img/aruco_camera_aoi_projection.png and b/docs/img/aruco_camera_aoi_projection.png differ
diff --git a/docs/img/scene.png b/docs/img/scene.png
index 251c7bf..e7edd88 100644
Binary files a/docs/img/scene.png and b/docs/img/scene.png differ
diff --git a/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md b/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
index 0b2ef52..529bff8 100644
--- a/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
+++ b/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
@@ -72,7 +72,7 @@ for name, aruco_scene in aruco_camera.scenes.items():
 
 ## Pipeline execution outputs
 
-[ArUcoCamera.watch](../../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method returns many data about pipeline execution.
+[ArUcoCamera.watch](../../../argaze.md/#argaze.ArFeatures.ArCamera.watch) method returns data about pipeline execution.
 
 ```python
 # Assuming that images are available
@@ -81,7 +81,7 @@ for name, aruco_scene in aruco_camera.scenes.items():
     # Watch image with ArUco camera
     detection_time, exception = aruco_camera.watch(image)
 
-    # Do something with pipeline detection times
+    # Do something with pipeline detection time
     ...
 
     # Do something with pipeline exception
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
index 502f905..b02bc9e 100644
--- a/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
@@ -1,7 +1,7 @@
 Describe 3D AOI
 ===============
 
-Once [ArUco markers are placed into a scene](aruco_markers_description.md), [areas of interest (AOI)](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) need to be described into the same 3D referential.
+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.
 
@@ -26,14 +26,12 @@ 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
-s off
 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
-s off
 f 5 6 8 7
 ```
 
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md
index 8affe91..f1ae1f6 100644
--- a/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_frame.md
@@ -69,7 +69,7 @@ An [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) instance can co
 
 ### Screen
 
-The name of a 3D AOI **and** of an [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically useful for visualisation purpose.
+The name of a 3D AOI **and** an [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame). Basically useful for visualisation purpose.
 
 !!! warning "AOI / Frame names policy"
 
diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
index 0d58d9a..8c7310b 100644
--- a/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
@@ -96,7 +96,7 @@ Now, let's understand the meaning of each JSON entry.
 
 ### *layers*
 
-An [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.
+An [ArUcoCamera](../../argaze.md/#argaze.ArFeatures.ArFrame) instance can contains multiples [ArLayers](../../argaze.md/#argaze.ArFeatures.ArLayer) stored by name.
 
 ### MyLayer
 
@@ -110,7 +110,7 @@ The name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically
 
     [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 features to ArUcoCamera
+## Add AOI analysis features to ArUcoCamera layer
 
 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.
 
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 3addcab..8104345 100644
--- a/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md
+++ b/docs/user_guide/aruco_markers_pipeline/aruco_markers_description.md
@@ -3,7 +3,7 @@ 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 workspace with a screen and a sheet on the table.
+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)
 
@@ -66,7 +66,6 @@ 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 -0.855050 24.000002 4.349232
@@ -74,7 +73,6 @@ v 0.855050 24.000002 -0.349231
 v -0.855050 29.000002 4.349232
 v 0.855050 29.000002 -0.349231
 vn 0.9397 0.0000 0.3420
-s off
 f 5//2 6//2 8//2 7//2
 o DICT_APRILTAG_16h5#2_Marker
 v 44.000000 0.000000 9.500000
@@ -82,7 +80,6 @@ v 49.000000 0.000000 9.500000
 v 44.000000 -0.000000 4.500000
 v 49.000000 -0.000000 4.500000
 vn 0.0000 1.0000 -0.0000
-s off
 f 9//3 10//3 12//3 11//3
 ```
 
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 2205ed2..3bded3a 100644
--- a/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
+++ b/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
@@ -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
-            }
         }
     }
 }
@@ -135,4 +135,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 3D AOI](aoi_3d_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 26294f7..a83da9a 100644
--- a/docs/user_guide/aruco_markers_pipeline/introduction.md
+++ b/docs/user_guide/aruco_markers_pipeline/introduction.md
@@ -9,16 +9,16 @@ The OpenCV library provides a module to detect fiducial markers into a picture a
 
 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) -->
 
 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_3d_description.md),
 * [How to load and execute ArUco markers pipeline](configuration_and_execution.md),
 * [How to estimate scene pose](pose_estimation.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)
 
diff --git a/docs/user_guide/gaze_analysis_pipeline/aoi_2d_description.md b/docs/user_guide/gaze_analysis_pipeline/aoi_2d_description.md
index ad8ee74..4b7ed69 100644
--- a/docs/user_guide/gaze_analysis_pipeline/aoi_2d_description.md
+++ b/docs/user_guide/gaze_analysis_pipeline/aoi_2d_description.md
@@ -29,7 +29,7 @@ Here are common SVG file features needed to describe AOI:
 
 * *id* attribute indicates AOI name.
 * *path* element describes any polygon using only [M, L and Z path intructions](https://www.w3.org/TR/SVG2/paths.html#PathData)
-* *rect* and *circle* allow respectively to describe rectangular and circle AOI.
+* *rect*, *circle* and *ellipse* allow respectively to describe rectangular, circular and elliptic AOI.
 
 ### Edit JSON file description
 
diff --git a/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md b/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md
index b282f80..3fd15db 100644
--- a/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md
+++ b/docs/user_guide/gaze_analysis_pipeline/aoi_analysis.md
@@ -1,13 +1,13 @@
 Enable AOI analysis
 ===================
 
-Once [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) is [configured](configuration_and_execution.md) and [2D AOI are described](aoi_2d_description.md), gaze movement can be matched with AOI to build an AOI scan path before analyze it. 
+Once [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) is [configured](configuration_and_execution.md) and [2D AOI are described](aoi_2d_description.md), fixation can be matched with AOI to build an AOI scan path before analyze it. 
 
 ![Layer](../../img/ar_layer.png)
 
 ## Add ArLayer to ArFrame JSON configuration file
 
-The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class defines a space where to make matching of gaze movements with AOI and inside which those matchings need to be analyzed.
+The [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) class defines a space where to make matching of fixations with AOI and inside which those matchings need to be analyzed.
 
 Here is an extract from the JSON [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) configuration file with a sample where one layer is added:
 
diff --git a/docs/user_guide/gaze_analysis_pipeline/background.md b/docs/user_guide/gaze_analysis_pipeline/background.md
index ee27495..a61abdc 100644
--- a/docs/user_guide/gaze_analysis_pipeline/background.md
+++ b/docs/user_guide/gaze_analysis_pipeline/background.md
@@ -30,10 +30,10 @@ Here is an extract from the JSON ArFrame configuration file where a background p
 
 Now, let's understand the meaning of each JSON entry.
 
-### Background
+### *background*
 
 The path to an image file on disk.
 
-### Background weight
+### *background_weight*
 
 The weight of background overlay in [ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) between 0 and 1.
diff --git a/docs/user_guide/gaze_analysis_pipeline/heatmap.md b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
index 5310d64..6d9ad18 100644
--- a/docs/user_guide/gaze_analysis_pipeline/heatmap.md
+++ b/docs/user_guide/gaze_analysis_pipeline/heatmap.md
@@ -33,21 +33,21 @@ Here is an extract from the JSON ArFrame configuration file where heatmap is ena
 
 Now, let's understand the meaning of each JSON entry.
 
-### Size
+### *size*
 
 The heatmap image size in pixel. Higher size implies higher CPU load.
 
-### Sigma
+### *sigma*
 
 The gaussian point spreading to draw at each gaze position.
 
 ![Point spread](../../img/point_spread.png)
 
-### Buffer 
+### *buffer* 
 
 The size of point spread images buffer (0 means no buffering) to visualize only last N gaze positions.
 
-### Heatmap weight
+### *heatmap_weight*
 
 The weight of heatmap overlay in [ArFrame.image](../../argaze.md/#argaze.ArFeatures.ArFrame.image) between 0 and 1.
 
diff --git a/docs/user_guide/gaze_analysis_pipeline/introduction.md b/docs/user_guide/gaze_analysis_pipeline/introduction.md
index 76a146c..339dd90 100644
--- a/docs/user_guide/gaze_analysis_pipeline/introduction.md
+++ b/docs/user_guide/gaze_analysis_pipeline/introduction.md
@@ -13,7 +13,7 @@ To build your own gaze analysis pipeline, you need to know:
 * [How to load and execute gaze analysis pipeline](configuration_and_execution.md),
 * [How to describe frame's AOI](aoi_2d_description.md),
 * [How to enable AOI analysis](aoi_analysis.md),
-* [How to visualize ArFrame and ArLayers](visualisation.md),
+* [How to visualize pipeline steps outputs](visualisation.md),
 * [How to log resulted gaze analysis](logging.md),
 * [How to make heatmap image](heatmap.md).
 * [How to add a background image](background.md).
diff --git a/docs/user_guide/gaze_analysis_pipeline/logging.md b/docs/user_guide/gaze_analysis_pipeline/logging.md
index 1dea712..055a535 100644
--- a/docs/user_guide/gaze_analysis_pipeline/logging.md
+++ b/docs/user_guide/gaze_analysis_pipeline/logging.md
@@ -7,7 +7,7 @@ Log gaze analysis
 
 [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer) have a log attribute to enable analysis logging.
 
-Here is an extract from the JSON ArFrame configuration file where logging is enabled for the ArFrame and for one ArLayer:
+Here is an extract from the JSON ArFrame configuration file where logging is enabled for the [ArFrame](../../argaze.md/#argaze.ArFeatures.ArFrame) and for one [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer):
 
 ```json
 {
@@ -91,7 +91,7 @@ Assuming that [ArGaze.GazeAnalysis.NGram](../../argaze.md/#argaze.GazeAnalysis.N
 |timestamped|ngrams_count|
 |:----------|:-----------|
 |5687       |"{3: {}, 4: {}, 5: {}}"|
-|6208       |"{3: {('upper_left_corner', 'lower_left_corner', 'lower_right_corner'): 1}, 4: {}, 5: {}}"|
+|6208       |"{3: {('LeftPanel', 'GeoSector', 'CircularWidget'): 1}, 4: {}, 5: {}}"|
 |...        |...         |
 
 
diff --git a/docs/user_guide/gaze_analysis_pipeline/visualisation.md b/docs/user_guide/gaze_analysis_pipeline/visualisation.md
index cf6fa41..5f06fac 100644
--- a/docs/user_guide/gaze_analysis_pipeline/visualisation.md
+++ b/docs/user_guide/gaze_analysis_pipeline/visualisation.md
@@ -17,6 +17,22 @@ Here is an extract from the JSON ArFrame configuration file with a sample where
     "size": [1920, 1080],
     ...
     "image_parameters": {
+        "draw_gaze_positions": {
+            "color": [0, 255, 255],
+            "size": 2
+        },
+        "draw_fixations": {
+            "deviation_circle_color": [255, 255, 255],
+            "duration_border_color": [127, 0, 127],
+            "duration_factor": 1e-2,
+            "draw_positions": {
+                "position_color": [0, 255, 255],
+                "line_color": [0, 0, 0]
+            }
+        }, 
+        "draw_saccades": {
+            "line_color": [255, 0, 255]
+        },
         "draw_scan_path": {
             "draw_fixations": {
                 "deviation_circle_color": [255, 0, 255],
@@ -55,22 +71,6 @@ Here is an extract from the JSON ArFrame configuration file with a sample where
                     "looked_aoi_name_offset": [0, -10]
                 }
             }
-        },
-        "draw_fixations": {
-            "deviation_circle_color": [255, 255, 255],
-            "duration_border_color": [127, 0, 127],
-            "duration_factor": 1e-2,
-            "draw_positions": {
-                "position_color": [0, 255, 255],
-                "line_color": [0, 0, 0]
-            }
-        }, 
-        "draw_saccades": {
-            "line_color": [255, 0, 255]
-        },
-        "draw_gaze_positions": {
-            "color": [0, 255, 255],
-            "size": 2
         }
     }
 }
@@ -92,7 +92,7 @@ import cv2
 # Assuming that timestamped gaze positions have been processed by ArFrame.look method
 ...
 
-# Export heatmap image
+# Export ArFrame image
 cv2.imwrite('./ar_frame.png', ar_frame.image())
 ```
 
diff --git a/docs/user_guide/utils/ready-made_scripts.md b/docs/user_guide/utils/ready-made_scripts.md
index bc8b277..c82a332 100644
--- a/docs/user_guide/utils/ready-made_scripts.md
+++ b/docs/user_guide/utils/ready-made_scripts.md
@@ -11,7 +11,7 @@ Collection of command-line scripts to provide useful features.
 
 ## ArUco scene exporter
 
-Load a MOVIE with ArUco markers inside and select image into it, detect ArUco markers belonging to DICT_APRILTAG_16h5 dictionary with 5cm size into the selected image thanks to given OPTIC_PARAMETERS and DETECTOR_PARAMETERS then, export detected ArUco markers scene as .obj file into an *./src/argaze/utils/_export/scenes* folder.
+Load a MOVIE with ArUco markers inside and select image into it, detect ArUco markers belonging to DICT_APRILTAG_16h5 dictionary with 5cm size into the selected image thanks to given OPTIC_PARAMETERS and DETECTOR_PARAMETERS files then, export detected ArUco markers scene as .obj file into an *./src/argaze/utils/_export/scenes* folder.
 
 ```shell
 python ./src/argaze/utils/aruco_markers_scene_export.py MOVIE DICT_APRILTAG_16h5 5 OPTIC_PARAMETERS DETECTOR_PARAMETERS -o ./src/argaze/utils/_export/scenes
diff --git a/mkdocs.yml b/mkdocs.yml
index d00d6e7..f988ed0 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -25,9 +25,9 @@ nav:
   - ArUco markers pipeline:
     - user_guide/aruco_markers_pipeline/introduction.md
     - user_guide/aruco_markers_pipeline/aruco_markers_description.md
-    - user_guide/aruco_markers_pipeline/aoi_3d_description.md
     - user_guide/aruco_markers_pipeline/configuration_and_execution.md
     - user_guide/aruco_markers_pipeline/pose_estimation.md
+    - user_guide/aruco_markers_pipeline/aoi_3d_description.md
     - user_guide/aruco_markers_pipeline/aoi_3d_projection.md
     - user_guide/aruco_markers_pipeline/aoi_3d_frame.md
     - Advanced Topics:
-- 
cgit v1.1