Writing User guide and use cases section.

3 files changed, 119 insertions, 0 deletions

diff --git a/docs/user_guide/ar_environment/environment_exploitation.md b/docs/user_guide/ar_environment/environment_exploitation.md
new file mode 100644
index 0000000..db40385
--- /dev/null
+++ b/docs/user_guide/ar_environment/environment_exploitation.md
@@ -0,0 +1,36 @@
+Environment exploitation
+========================
+
+Once loaded, AR environment assets can be exploited as illustrated below:
+
+```python
+# Access to AR environment ArUco detector passing it a frame where to detect ArUco markers
+ar_environment.aruco_detector.detect_markers(frame)
+
+# Access to an AR environment scene
+my_first_scene = ar_environment.scenes['my first AR scene']
+
+try:
+
+     # Try to estimate AR scene pose from detected markers
+     tvec, rmat, consistent_markers = my_first_scene.estimate_pose(ar_environment.aruco_detector.detected_markers)
+
+     # Project AR scene into camera frame according estimated pose
+     # Optional visual_hfov argument is set to 160° to clip AOI scene according a cone vision
+     aoi2D_scene = my_first_scene.project(tvec, rmat, visual_hfov=160)
+
+     # Draw estimated AR scene axis
+     my_first_scene.draw_axis(frame)
+
+     # Draw AOI2D scene projection
+     aoi2D_scene.draw(frame)
+
+     # Do something with AOI2D scene projection
+     ...
+
+# Catch exceptions raised by estimate_pose and project methods
+except (ArFeatures.PoseEstimationFailed, ArFeatures.SceneProjectionFailed) as e:
+
+    print(e)
+
+```
diff --git a/docs/user_guide/ar_environment/environment_setup.md b/docs/user_guide/ar_environment/environment_setup.md
new file mode 100644
index 0000000..b63f64a
--- /dev/null
+++ b/docs/user_guide/ar_environment/environment_setup.md
@@ -0,0 +1,77 @@
+Environment Setup
+=================
+
+AR environment setup is loaded from JSON file format.
+
+Each AR environment defines a unique ArUco detector dedicated to detection of markers from a specific ArUco dictionary and with a given size. However, it is possible to load multiple AR scenes into a same AR environment.
+
+Here is JSON environment file example where it is assumed that mentioned .obj files are located relatively to the environment file on disk.
+
+```
+{
+    "name": "my AR environment",
+    "aruco_detector": {
+    	"dictionary": {
+            "name": "DICT_APRILTAG_16h5"
+    	}
+    	"marker_size": 5,
+    	"camera": {
+            "rms": 0.6,
+            "dimensions": [
+                1920,
+                1080
+            ],
+            "K": [
+                [
+                    1135,
+                    0.0,
+                    956
+                ],
+                [
+                    0.0,
+                    1135,
+                    560
+                ],
+                [
+                    0.0,
+                    0.0,
+                    1.0
+                ]
+            ],
+            "D": [
+                0.01655492265003404,
+                0.1985524264972037,
+                0.002129965902489484,
+                -0.0019528582922179365,
+                -0.5792910353639452
+            ]
+        },
+        "parameters": {
+            "cornerRefinementMethod": 3,
+            "aprilTagQuadSigma": 2,
+            "aprilTagDeglitch": 1
+        }
+    },
+    "scenes": {
+        "my first AR scene" : {
+            "aruco_scene": "./first_scene/markers.obj",
+            "aoi_scene": "./first_scene/aoi.obj",
+            "angle_tolerance": 15.0,
+            "distance_tolerance": 2.54
+        },
+        "my second AR scene" : {
+            "aruco_scene": "./second_scene/markers.obj",
+            "aoi_scene": "./second_scene/aoi.obj",
+            "angle_tolerance": 15.0,
+            "distance_tolerance": 2.54
+        }
+    }
+}
+```
+
+```python
+from argaze import ArFeatures
+
+# Load AR environment
+ar_environment = ArFeatures.ArEnvironment.from_json('./environment.json')
+```
diff --git a/docs/user_guide/ar_environment/introduction.md b/docs/user_guide/ar_environment/introduction.md
new file mode 100644
index 0000000..608cdb4
--- /dev/null
+++ b/docs/user_guide/ar_environment/introduction.md
@@ -0,0 +1,6 @@
+AR environment setup
+====================
+
+ArGaze toolkit eases ArUco and AOI management in a single AR environment setup.
+
+This section refers to [ArFeatures](/aragaze/#argaze.ArFeatures).