From 9958a965725764aee7150a67d9f63e241b4c345e Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 17 Apr 2024 14:16:40 +0200
Subject: Improving aruco marker pipeline documentation.

---
 .../aruco_marker_description.md                    | 120 +++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md

(limited to 'docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md')

diff --git a/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md b/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md
new file mode 100644
index 0000000..1d703d4
--- /dev/null
+++ b/docs/user_guide/aruco_marker_pipeline/aruco_marker_description.md
@@ -0,0 +1,120 @@
+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 two screens, a control panel and a window.
+
+![Scene](../../img/scene.png)
+
+## Print ArUco markers from an ArUco dictionary
+
+ArUco markers always belong to a set of markers called the ArUco marker dictionary.
+
+![ArUco dictionaries](../../img/aruco_dictionaries.png)
+
+Many ArUco marker dictionaries exist with properties concerning the format, the number of markers, or the difference between each marker to avoid errors in tracking.
+
+Here is the documention [about ArUco markers dictionaries](https://docs.opencv.org/3.4/d9/d6a/group__aruco.html#gac84398a9ed9dd01306592dd616c2c975).
+
+The creation of [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures from a dictionary is illustrated in the code below:
+ 
+```python
+from argaze.ArUcoMarker import ArUcoMarkerDictionary
+
+# Create a dictionary of specific April tags
+aruco_dictionary = ArUcoMarkerDictionary.ArUcoMarkerDictionary('DICT_APRILTAG_16h5')
+
+# Export marker n°5 as 3.5 cm picture with 300 dpi resolution
+aruco_dictionary.create_marker(5, 3.5).save('./markers/', 300)
+
+# Export all dictionary markers as 3.5 cm pictures with 300 dpi resolution
+aruco_dictionary.save('./markers/', 3.5, 300)
+```
+
+!!! note
+      There is an **A4_DICT_APRILTAG_16h5_5cm_0-7.pdf** file located in *./src/argaze/ArUcoMarker/utils/* folder ready to be printed on an A4 paper sheet.
+
+Let's print some of them before going further.
+
+!!! warning
+	Print markers with a blank zone around them to help in their detection.
+
+## Describe ArUco markers place
+
+Once [ArUcoMarker](../../argaze.md/#argaze.ArUcoMarker.ArUcoMarker) pictures are placed into a scene, it is possible to describe their 3D places into a file.
+
+![ArUco markers description](../../img/aruco_markers_description.png)
+
+Wherever the origin point is, all markers places need to be described on a [right-handed 3D axis](https://robotacademy.net.au/lesson/right-handed-3d-coordinate-frame/) where:
+
+* +X is pointing to the right,
+* +Y is pointing to the top,
+* +Z is pointing to the backward.
+
+!!! warning
+	All ArUco markers spatial values must be given in **centimeters**.
+
+### Edit OBJ file description
+
+OBJ file format could be exported from most 3D editors.
+
+``` obj
+o DICT_APRILTAG_16h5#0_Marker
+v 15.000000 0.378741 0.330527
+v 20.000000 0.378741 0.330527
+v 15.000000 5.120359 -1.255996
+v 20.000000 5.120359 -1.255996
+f 1 2 4 3
+o DICT_APRILTAG_16h5#1_Marker
+v 43.500000 31.428055 18.333317
+v 48.500000 31.428055 18.333317
+v 43.500000 36.428055 18.333317
+v 48.500000 36.428055 18.333317
+f 5 6 8 7
+o DICT_APRILTAG_16h5#2_Marker
+v 38.500000 2.678055 5.498381
+v 43.500000 2.678055 5.498381
+v 38.500000 5.178055 1.168253
+v 43.500000 5.178055 1.168253
+f 9 10 12 11
+```
+
+Here are some common OBJ file features needed to describe ArUco markers places:  
+
+* Object line (starting with *o* key) indicate marker dictionary and id by following this format: **DICTIONARY**#**ID**\_Marker.
+* Vertice line (starting with *v* key) indicate marker corners. The marker size will be automatically deducted from the geometry.
+* Face line (starting with *f* key) link vertice and normal indexes together.
+
+!!! warning
+	Markers have to belong to the same dictionary.
+
+!!! note
+    Markers can have different sizes.
+
+### Edit JSON file description
+
+JSON file format allows to describe markers places using translation and euler angle rotation vectors.
+
+``` json
+{
+    "dictionary": "DICT_APRILTAG_16h5",
+    "places": {
+        "0": {
+            "translation": [17.5, 2.75, -0.5],
+            "rotation": [-18.5, 0, 0],
+            "size": 5
+        },
+        "1": {
+            "translation": [46, 34, 18.333],
+            "rotation": [0, 70, 0],
+            "size": 5
+        },
+        "2": {
+            "translation": [41, 4, 3.333],
+            "rotation": [-60, 0, 0],
+            "size": 5
+        }
+    }
+}
+```
-- 
cgit v1.1