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

3 files changed, 238 insertions, 4 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