Hormonizing JSON entry description format. Improving ArUco markers pipeline documentation.

4 files changed, 44 insertions, 32 deletions

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 db9cb73..0a7ec4d 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
@@ -136,11 +136,11 @@ Below, an optic_parameters JSON file example:
 
 [ArUcoCamera.detector.optic_parameters](../../argaze.md/#argaze.ArUcoMarkers.ArUcoOpticCalibrator.OpticParameters) can be enabled thanks to a dedicated JSON entry.
 
-Here is an extract from a JSON [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) configuration file where optic parameters are loaded and displayed:
+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 Full HD Camera",
+    "name": "My FullHD Camera",
     "size": [1920, 1080],
     "aruco_detector": {
         "dictionary": "DICT_APRILTAG_16h5",
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 e96730a..7f98aa2 100644
--- a/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
@@ -1,13 +1,13 @@
-Project AOI into camera frame
-=============================
+Project 3D AOI into camera 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.
 
 ![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:
 
@@ -38,15 +38,19 @@ 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 name of an [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
+
+### *aoi_scene*
 
 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
+## Add ArLayer to ArUcoCamera to project 3D AOI into
 
 Here is the previous extract where one layer is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) and displayed:
 
@@ -91,9 +95,13 @@ 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 [ArFrame](../../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"
 
@@ -103,11 +111,11 @@ The name of the [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 2D AOI analysis
+## Add AOI analysis features to ArUcoCamera
 
-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 [2D AOI analysis pipeline section](../gaze_analysis_pipeline/aoi_analysis.md).
+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).
 
 Here is the previous extract where AOI matcher, AOI scan path and AOI scan path analyzers are added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) layer:
 
@@ -156,4 +164,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/configuration_and_execution.md b/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
index 6bf84a9..2205ed2 100644
--- a/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
+++ b/docs/user_guide/aruco_markers_pipeline/configuration_and_execution.md
@@ -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](../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,10 +107,10 @@ 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()
 ```
 
@@ -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 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) and [how to project 3D AOI](aoi_3d_projection.md).
\ No newline at end of file
diff --git a/docs/user_guide/aruco_markers_pipeline/pose_estimation.md b/docs/user_guide/aruco_markers_pipeline/pose_estimation.md
index d7da336..5dcde6f 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:
 
@@ -65,11 +65,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 +81,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).