From 609e0300c5c047c164548af8e0c1c9b1e49e9790 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Tue, 11 Jul 2023 15:55:27 +0200
Subject: Documenting ArUco scene creation from detected markers and its
 exportation in OBJ file format.

---
 .../aruco_markers/markers_scene_description.md     | 47 +++++++++++++++++-----
 1 file changed, 38 insertions(+), 9 deletions(-)

(limited to 'docs')

diff --git a/docs/user_guide/aruco_markers/markers_scene_description.md b/docs/user_guide/aruco_markers/markers_scene_description.md
index 3ea962e..0b5b712 100644
--- a/docs/user_guide/aruco_markers/markers_scene_description.md
+++ b/docs/user_guide/aruco_markers/markers_scene_description.md
@@ -11,6 +11,10 @@ The ArGaze toolkit provides [ArUcoScene](../../../argaze/#argaze.ArUcoMarkers.Ar
 * check the consistency of detected markers according the place where each marker is expected to be,
 * estimate the pose of the scene from the pose of detected markers.
 
+## Scene creation
+
+### from OBJ
+
 ArUco scene description uses common OBJ file format that can be exported from most 3D editors. Notice that plane normals (vn) needs to be exported.
 
 ``` obj
@@ -33,6 +37,24 @@ f 5//2 6//2 8//2 7//2
 ...
 ```
 
+Here is a sample of code to show the loading of an [ArUcoScene](../../../argaze/#argaze.ArUcoMarkers.ArUcoScene) OBJ file description:
+
+``` python
+from argaze.ArUcoMarkers import ArUcoScene
+
+# Create an ArUco scene from a OBJ file description
+aruco_scene = ArUcoScene.ArUcoScene.from_obj('./markers.obj')
+
+# Print loaded marker places
+for place_id, place in aruco_scene.places.items():
+
+       print(f'place {place_id} for marker: ', place.marker.identifier)
+       print(f'place {place_id} translation: ', place.translation)
+       print(f'place {place_id} rotation: ', place.rotation)
+```
+
+### from JSON
+
 [ArUcoScene](../../../argaze/#argaze.ArUcoMarkers.ArUcoScene) description can also be written in a JSON file format.
 
 ``` json
@@ -56,20 +78,18 @@ f 5//2 6//2 8//2 7//2
 }
 ```
 
-Here is a sample of code to show the loading of an [ArUcoScene](../../../argaze/#argaze.ArUcoMarkers.ArUcoScene) OBJ file description:
+### from detected markers
+
+Here is a more advanced usage where ArUco scene is built from markers detected into an image:
 
 ``` python
 from argaze.ArUcoMarkers import ArUcoScene
 
-# Create an ArUco scene from a OBJ file description
-aruco_scene = ArUcoScene.ArUcoScene.from_obj('./markers.obj')
-
-# Print loaded marker places
-for place_id, place in aruco_scene.places.items():
+# Assuming markers have been detected and their pose estimated thanks to ArUcoDetector
+# ...
 
-       print(f'place {place_id} for marker: ', place.marker.identifier)
-       print(f'place {place_id} translation: ', place.translation)
-       print(f'place {place_id} rotation: ', place.rotation)
+# Build ArUco scene from detected markers
+aruco_scene = ArUcoScene.ArUcoScene(aruco_detector.marker_size, aruco_detector.dictionary, aruco_detector.detected_markers)
 ```
 
 ## Markers filtering
@@ -115,3 +135,12 @@ The third approach is only available when ArUco markers are placed in such a con
 ``` python
 tvec, rmat = self.aruco_scene.estimate_pose_from_axis_markers(origin_marker, horizontal_axis_marker, vertical_axis_marker)
 ```
+
+## Scene exportation
+
+As ArUco scene can be exported to OBJ file description to import it into most 3D editors.
+
+``` python
+# Export an ArUco scene as OBJ file description
+aruco_scene.to_obj('markers.obj')
+```
-- 
cgit v1.1