Improving AOI description documentation.

1 files changed, 62 insertions, 0 deletions

diff --git a/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
new file mode 100644
index 0000000..13f9c86
--- /dev/null
+++ b/docs/user_guide/aruco_markers_pipeline/aoi_3d_description.md
@@ -0,0 +1,62 @@
+Describe 3D AOI
+===============
+
+Once [ArUco markers are placed into a scene](aruco_markers_description.md), areas of interest need to be described into the same 3D referential.
+
+In the example scene, each screen is considered as an area of interest more the blue triangle area inside the top screen.
+
+![3D AOI description](../../img/aoi_3d_description.png)
+
+All AOIs need to be described from same origin than markers in 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 AOIs spatial values must be given in **centimeters**.
+
+### Edit OBJ file description
+
+OBJ file format could be exported from most 3D editors.
+
+``` obj
+o YellowSquare
+v 6.200003 -7.275252 25.246159
+v 31.200003 -7.275252 25.246159
+v 6.200003 1.275252 1.753843
+v 31.200003 1.275252 1.753843
+s off
+f 1 2 4 3
+o GrayRectangle
+v 2.500000 2.500000 -0.500000
+v 37.500000 2.500000 -0.500000
+v 2.500000 27.500000 -0.500000
+v 37.500000 27.500000 -0.500000
+s off
+f 5 6 8 7
+o BlueTriangle
+v 12.500002 7.500000 -0.500000
+v 27.500002 7.500000 -0.500000
+v 20.000002 22.500000 -0.500000
+s off
+f 9 10 11
+```
+
+Here are common OBJ file features needed to describe AOIs:  
+
+* Object lines (starting with *o* key) indicate AOI name.
+* Vertice lines (starting with *v* key) indicate AOI vertices.
+* Face (starting with *f* key) link vertices together.
+
+### Edit JSON file description
+
+JSON file format allows to describe AOIs vertices.
+
+``` json
+{
+    "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]]
+}
+```