Improving AOI description documentation.

1 files changed, 159 insertions, 0 deletions

diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
new file mode 100644
index 0000000..bdebd6c
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_projection.md
@@ -0,0 +1,159 @@
+Project AOI into camera frame
+=============================
+
+Once [ArUcoScene pose is estimated](pose_estimation.md) and [3D AOIs are described](aoi_3d_description.md), AOIs 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
+
+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).
+
+Here is the previous extract where one layer is added to the [ArUcoScene](../../argaze.md/#argaze.ArUcoMarkers.ArUcoScene) configuration:
+
+```json
+{
+    "name": "My FullHD camera",
+    "size": [1920, 1080],
+    ...
+    "scenes": {
+        "MyScene" : {
+            "aruco_markers_group": {
+                ...
+            },
+            "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]]
+                    }
+                }
+            } 
+        }
+    }
+    ...
+}
+```
+
+Now, let's understand the meaning of each JSON entry.
+
+### "MyLayer"
+
+The name of the [ArLayer](../../argaze.md/#argaze.ArFeatures.ArLayer). Basically useful for visualisation purpose.
+
+### AOI Scene
+
+The [AOIScene](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AOIScene) defines a set of 3D [AreaOfInterest](../../argaze.md/#argaze.AreaOfInterest.AOIFeatures.AreaOfInterest) registered by name.
+
+## Add ArLayer to ArUcoCamera to project 3D AOIs
+
+Here is the previous extract where one layer is added to the [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) and displayed:
+
+```json
+{
+    "name": "My FullHD camera",
+    "size": [1920, 1080],
+    ...
+    "scenes": {
+        "MyScene" : {
+            "aruco_markers_group": {
+                ...
+            },
+            "layers": {
+                 "MyLayer": {
+                    "aoi_scene": {
+                        ...
+                    }
+                } 
+            } 
+        }
+    },
+    "layers": {
+        "MyLayer": {}
+    }
+    ...
+    "image_parameters": {
+        ...
+        "draw_layers": {
+            "MyLayer": {
+                "draw_aoi_scene": {
+                    "draw_aoi": {
+                        "color": [255, 255, 255],
+                        "border_size": 1
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+Now, let's understand the meaning of each JSON entry.
+
+### "MyLayer"
+
+The name of the [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**.
+
+!!! 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 2D AOIs analysis
+
+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.
+
+Therefore, it means that [ArUcoCamera](../../argaze.md/#argaze.ArUcoMarkers.ArUcoCamera) benefits from all the services described in [2D AOIs analysis pipeline section](../gaze_analysis_pipeline/aoi_2d_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:
+
+```json
+{
+    "name": "My FullHD camera",
+    "size": [1920, 1080],
+    ...
+    "scenes": {
+        "MyScene" : {
+            "aruco_markers_group": {
+                ...
+            },
+            "layers": {
+                 "MyLayer": {
+                    "aoi_scene": {
+                        ...
+                    }
+                } 
+            } 
+        }
+    },
+    "layers": {
+        "MyLayer": {
+            "aoi_matcher": {
+                "DeviationCircleCoverage": {
+                    "coverage_threshold": 0.5
+                }
+            },
+            "aoi_scan_path": {
+                "duration_max": 30000
+            },
+            "aoi_scan_path_analyzers": {
+                "Basic": {},
+                "TransitionMatrix": {},
+                "NGram": {
+                    "n_min": 3,
+                    "n_max": 5
+                }
+            }
+        }
+    }
+    ...
+}
+```
+
+!!! 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.