From c4552e04e1271a9210a934233beae5be1943d034 Mon Sep 17 00:00:00 2001
From: Théo de la Hogue
Date: Wed, 7 Jun 2023 14:34:14 +0200
Subject: Writing User guide and use cases section.

---
 docs/user_guide/areas_of_interest/aoi_frame.md     | 43 ++++++++++++++++
 docs/user_guide/areas_of_interest/aoi_matching.md  | 47 ++++++++++++++++++
 .../user_guide/areas_of_interest/aoi_projection.md | 22 +++++++++
 .../areas_of_interest/aoi_scene_description.md     | 57 ++++++++++++++++++++++
 docs/user_guide/areas_of_interest/introduction.md  |  8 +++
 .../areas_of_interest/vision_cone_filtering.md     | 18 +++++++
 6 files changed, 195 insertions(+)
 create mode 100644 docs/user_guide/areas_of_interest/aoi_frame.md
 create mode 100644 docs/user_guide/areas_of_interest/aoi_matching.md
 create mode 100644 docs/user_guide/areas_of_interest/aoi_projection.md
 create mode 100644 docs/user_guide/areas_of_interest/aoi_scene_description.md
 create mode 100644 docs/user_guide/areas_of_interest/introduction.md
 create mode 100644 docs/user_guide/areas_of_interest/vision_cone_filtering.md

(limited to 'docs/user_guide/areas_of_interest')

diff --git a/docs/user_guide/areas_of_interest/aoi_frame.md b/docs/user_guide/areas_of_interest/aoi_frame.md
new file mode 100644
index 0000000..855e302
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/aoi_frame.md
@@ -0,0 +1,43 @@
+---
+title: AOI frame
+---
+
+AOI Frame
+=========
+
+[AOIFeatures](/argaze/#argaze/AreaOfInterest.AOIFeatures) provides [AOIFrame](/argaze/#argaze/AreaOfInterest.AOIFeatures.AOIFrame) class to draw into an 2D AOI.
+
+## Point spread
+
+The **point_spread** method draw a gaussian point spread into the frame at a given pointer position.
+
+![Point spread](../../img/point_spread.png)
+
+## Heatmap
+
+Heatmap visualisation allows to show where a pointer is most of the time.
+
+![Heatmap](../../img/heatmap.png)
+
+```python
+from argaze.AreaOfInterest import AOIFeatures
+
+# Create an AOI
+aoi = AOIFeatures.AreaOfInterest([[0, 0], [1, 0], [1, 1], [0, 1]])
+
+# Create AOIFrame related to this AOI with 800px * 600px resolution
+aoi_frame = AOIFeatures.AOIFrame(aoi, (800, 600))
+
+# Initialize heatmap
+aoi_frame.heatmap_init()
+
+# Assuming a pointer position (x, y) is moving inside frame
+...:
+
+	# Update heatmap at pointer position
+	aoi_frame.heatmap_update((x, y), sigma=0.05)
+
+	# Do something with heatmap picture
+	... aoi_frame.heatmap
+
+```
\ No newline at end of file
diff --git a/docs/user_guide/areas_of_interest/aoi_matching.md b/docs/user_guide/areas_of_interest/aoi_matching.md
new file mode 100644
index 0000000..3bffeb9
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/aoi_matching.md
@@ -0,0 +1,47 @@
+---
+title: AOI matching
+---
+
+AOI matching
+============
+
+Once AOI3D scene is projected into a frame as AOI2D scene, it could be needed to know which AOI2D is looked. 
+The AOI class in [AOIFeatures](/argaze/#argaze.AreaOfInterest.AOIFeatures) provides two ways to accomplish such task.
+
+## Pointer-based matching
+
+Test if 2D pointer is inside or not AOI using contains_point() method as illustrated below.
+
+![Contains point](../../img/contains_point.png)
+
+``` python
+pointer = (x, y)
+
+for name, aoi in aoi2D_scene.items():
+                    
+       if aoi.contains_point(pointer):
+
+              # Do something with looked aoi
+              ...
+
+```
+
+It is also possible to get where a pointer is looking inside an AOI provided that AOI is a rectangular plane:
+
+``` python
+
+inner_x, inner_y = aoi.inner_axis(pointer)
+
+```
+
+## Circle-based matching
+
+As positions have limited accuracy, it is possible to define a radius around a pointer to test circle intersection with AOI.
+
+![Circle intersection](../../img/circle_intersection.png)
+
+``` python
+
+intersection_shape, intersection_aoi_ratio, intersection_circle_ratio = aoi.circle_intersection(pointer, radius)
+
+```
diff --git a/docs/user_guide/areas_of_interest/aoi_projection.md b/docs/user_guide/areas_of_interest/aoi_projection.md
new file mode 100644
index 0000000..7ffc42d
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/aoi_projection.md
@@ -0,0 +1,22 @@
+---
+title: AOI projection
+---
+
+AOI projection
+==============
+
+An AOI3D scene can be rotated and translated according to a pose estimation before to project it onto camera frame as an AOI2D scene.
+
+![AOI projection](../../img/aoi_projection.png)
+
+``` python
+...
+
+# Assuming pose estimation is done (tvec and rmat)
+
+# Project AOI 3D scene according pose estimation and camera intrinsic parameters
+aoi2D_scene = aoi3D_scene.project(tvec, rmat, aruco_camera.K)
+
+# Draw AOI 2D scene
+aoi2D_scene.draw(frame)
+```
diff --git a/docs/user_guide/areas_of_interest/aoi_scene_description.md b/docs/user_guide/areas_of_interest/aoi_scene_description.md
new file mode 100644
index 0000000..dcda74b
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/aoi_scene_description.md
@@ -0,0 +1,57 @@
+---
+title: AOI scene description
+---
+
+AOI scene description
+=====================
+
+An AOI3D scene is built from a 3D model with all AOI as 3D planes and loaded through OBJ file format. 
+Notice that plane normals are not needed and planes are not necessary 4 vertices shapes.
+
+``` obj
+o PIC_ND
+v 6.513238 -27.113548 -25.163900
+v 22.994461 -27.310783 -24.552130
+v 6.718690 -6.467261 -26.482569
+v 23.252594 -6.592890 -25.873484
+f 1 2 4 3
+o PIC_ND_Aircraft
+v 6.994747 -21.286463 -24.727146
+v 22.740919 -21.406120 -24.147078
+v 7.086208 -12.096219 -25.314123
+v 22.832380 -12.215876 -24.734055
+f 5 6 8 7
+o PIC_ND_Wind
+v 7.086199 -11.769333 -25.335127
+v 12.081032 -11.807289 -25.151123
+v 7.115211 -8.854101 -25.521320
+v 12.110044 -8.892057 -25.337317
+f 9 10 12 11
+o PIC_ND_Waypoint
+v 17.774197 -11.819057 -24.943428
+v 22.769030 -11.857013 -24.759424
+v 17.803209 -8.903825 -25.129622
+v 22.798042 -8.941781 -24.945618
+f 13 14 16 15
+...
+o Thrust_Lever
+v 19.046124 15.523837 4.774072
+v 18.997263 -0.967944 5.701000
+v 18.988382 15.923470 -13.243046
+v 18.921808 -0.417994 -17.869610
+v 19.032232 19.241346 -3.040264
+v 19.020988 6.392717 5.872663
+v 18.945322 6.876906 -17.699480
+s off
+f 185 190 186 188 191 187 189
+...
+```
+
+Here is a sample of code to show the loading of an AOI3D scene from an OBJ file description:
+
+``` python
+from argaze.AreaOfInterest import AOI3DScene
+
+# Load an AOI3D scene from OBJ file
+aoi3D_scene = AOI3DScene.AOI3DScene.from_obj('./aoi_scene.obj')
+```
diff --git a/docs/user_guide/areas_of_interest/introduction.md b/docs/user_guide/areas_of_interest/introduction.md
new file mode 100644
index 0000000..7d44785
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/introduction.md
@@ -0,0 +1,8 @@
+About Areas Of Interest (AOI)
+=============================
+
+The [AreaOfInterest submodule](/argaze/#argaze.AreaOfInterest) allows to deal with AOI in a AR environment through high level classes:
+
+* [AOIFeatures](/argaze/#argaze.AreaOfInterest.AOIFeatures)
+* [AOI3DScene](/argaze/#argaze.AreaOfInterest.AOI3DScene)
+* [AOI2DScene](/argaze/#argaze.AreaOfInterest.AOI2DScene)
\ No newline at end of file
diff --git a/docs/user_guide/areas_of_interest/vision_cone_filtering.md b/docs/user_guide/areas_of_interest/vision_cone_filtering.md
new file mode 100644
index 0000000..e2b31ea
--- /dev/null
+++ b/docs/user_guide/areas_of_interest/vision_cone_filtering.md
@@ -0,0 +1,18 @@
+Vision cone filtering
+=====================
+
+The AOI3D scene provides cone clipping support in order to select only AOI which are inside vision cone field. 
+
+![Vision cone](../../img/vision_cone.png)
+
+``` python
+# Transform scene into camera referential
+aoi3D_camera = aoi3D_scene.transform(tvec, rmat)
+
+# Get aoi inside vision cone field 
+# The vision cone tip is positionned behind the head
+aoi3D_inside, aoi3D_outside = aoi3D_camera.vision_cone(cone_radius=300, cone_height=150, cone_tip=[0., 0., -20.])
+
+# Keep only aoi inside vision cone field
+aoi3D_scene = aoi3D_scene.copy(exclude=aoi3D_outside.keys())
+``` 
-- 
cgit v1.1