From 6af30f98e4d8c89e4602c4048622ce5e66dbe774 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Tue, 26 Sep 2023 17:39:10 +0200
Subject: Adding new aruco markers pipeline scripting chapter.

---
 .../advanced_topics/scripting.md                   | 132 +++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md

(limited to 'docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md')

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..c1db6d5
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/advanced_topics/scripting.md
@@ -0,0 +1,132 @@
+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 many data about pipeline execution.
+
+```python
+# Assuming that images are available
+...:
+
+    # Watch image with ArUco camera
+    detection_time, exception = aruco_camera.watch(image)
+
+    # Do something with pipeline detection 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.
+
+### *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
-- 
cgit v1.1