Adding documentation tips.

6 files changed, 33 insertions, 100 deletions

diff --git a/src/argaze/ArScene.py b/src/argaze/ArScene.py
index 5e38c1e..35fef1c 100644
--- a/src/argaze/ArScene.py
+++ b/src/argaze/ArScene.py
@@ -147,6 +147,22 @@ class ArScene():
 
 		return output
 
+	def whole_pose(self, width: float = 1., height: float = None) -> Tuple[numpy.array, numpy.array, numpy.array, numpy.array]:
+		"""Edit translation vector, rotation vector and camera intrinsic parameters to setup a whole scene projection frame.
+
+		* **Arguments:** 
+			- frame width
+			- frame height: optional, if None the height will be setup according given width and scene dimensions ratio.
+		"""
+
+		scene_size = self.aoi_scene.size
+		frame_size = numpy.array([width, int(scene_size[1]/scene_size[0]*width) if height == None else height])
+		tvec = self.aoi_scene.center*[-1, 1, 0] + [0, 0, scene_size[1]]
+		rvec = numpy.array([[-numpy.pi, 0.0, 0.0]])
+		K = numpy.array([[frame_size[1], 0.0, frame_size[0]/2], [0.0, frame_size[1], frame_size[1]/2], [0.0, 0.0, 1.0]])
+
+		return frame_size, tvec, rvec, K
+
 	def estimate_pose(self, frame) -> Tuple[numpy.array, numpy.array, dict]:
 		"""Estimate scene pose from ArUco markers into frame.
 
@@ -210,14 +226,20 @@ class ArScene():
 
 		return tvec, rmat, consistent_markers
 
-	def project(self, tvec, rmat, visual_hfov=0) -> AOI2DSceneType:
-		"""Project AOI scene into frame according estimated pose."""
+	def project(self, tvec: numpy.array, rvec: numpy.array, visual_hfov=0) -> AOI2DSceneType:
+		"""Project AOI scene into frame according estimated pose and optionals horizontal fieald of view clipping angle.	
+
+		* **Arguments:** 
+			- translation vector
+			- rotation vector
+			- horizontal field of view clipping angle
+		"""
 
 		# Clip AOI out of the visual horizontal field of view (optional)
 		if visual_hfov > 0:
 
 			# Transform scene into camera referential
-			aoi_scene_camera_ref = self.aoi_scene.transform(tvec, rmat)
+			aoi_scene_camera_ref = self.aoi_scene.transform(tvec, rvec)
 
 			# Get aoi inside vision cone field 
 			cone_vision_height_cm = 200 # cm
@@ -232,9 +254,7 @@ class ArScene():
 
 			aoi_scene_copy = self.aoi_scene.copy()
 
-		# DON'T APPLY CAMERA DISTORSION : it projects points which are far from the frame into it
-		# This hack isn't realistic but as the gaze will mainly focus on centered AOI, where the distorsion is low, it is acceptable.
-		aoi_scene_projection = aoi_scene_copy.project(tvec, rmat, self.aruco_camera.K)
+		aoi_scene_projection = aoi_scene_copy.project(tvec, rvec, self.aruco_camera.K)
 
 		# Warn user when the projected scene is empty
 		if len(aoi_scene_projection) == 0:
diff --git a/src/argaze/ArUcoMarkers/utils/aruco_cube.json b/src/argaze/ArUcoMarkers/utils/aruco_cube.json
deleted file mode 100644
index a8df443..0000000
--- a/src/argaze/ArUcoMarkers/utils/aruco_cube.json
+++ /dev/null
@@ -1,24 +0,0 @@
-{
-    "dictionary": "DICT_APRILTAG_16h5",
-    "marker_size": 5.2,
-    "edge_size": 6,
-    "places": {
-        "front": {
-            "translation": [0, 0, 3],
-            "rotation": [0, 0, 0],
-            "marker": 2
-        },
-        "top": {
-            "translation": [0, 3, 0],
-            "rotation": [90, 0, 0],
-            "marker": 1
-        },
-        "left": {
-           "translation": [-3, 0, 0],
-            "rotation": [0, 0, 0],
-            "marker": 3
-        }
-    },
-    "angle_tolerance": 1,
-    "distance_tolerance": 0.5
-}
\ No newline at end of file
diff --git a/src/argaze/ArUcoMarkers/utils/aruco_plan.json b/src/argaze/ArUcoMarkers/utils/aruco_plan.json
deleted file mode 100644
index 1ab05b2..0000000
--- a/src/argaze/ArUcoMarkers/utils/aruco_plan.json
+++ /dev/null
@@ -1,30 +0,0 @@
-{
-    "dictionary": "DICT_APRILTAG_16h5",
-    "marker_size": 5,
-    "width": 29.7,
-    "height": 21,
-    "places": {
-        "lower_left": {
-            "translation": [0, 0, 0],
-            "rotation": [0, 0, 0],
-            "marker": 2
-        },
-        "upper_left": {
-            "translation": [0, 21, 0],
-            "rotation": [0, 0, 0],
-            "marker": 3
-        },
-        "upper_right": {
-            "translation": [29.7, 21, 0],
-            "rotation": [0, 0, 0],
-            "marker": 4
-        },
-        "lower_right": {
-            "translation": [29.7, 0, 0],
-            "rotation": [0, 0, 0],
-            "marker": 5
-        }
-    },
-    "angle_tolerance": 5.0,
-    "distance_tolerance": 1.0
-}
\ No newline at end of file
diff --git a/src/argaze/ArUcoMarkers/utils/tobiiglassespro2_hd.json b/src/argaze/ArUcoMarkers/utils/tobiiglassespro2_hd.json
deleted file mode 100644
index d21295a..0000000
--- a/src/argaze/ArUcoMarkers/utils/tobiiglassespro2_hd.json
+++ /dev/null
@@ -1,33 +0,0 @@
-{
-    "rms": 0.6688921504088245,
-    "dimensions": [
-        1920,
-        1080
-    ],
-    "camera matrix": [
-        [
-            1135.6524381415752,
-            0.0,
-            956.0685325355497
-        ],
-        [
-            0.0,
-            1135.9272506869524,
-            560.059099810324
-        ],
-        [
-            0.0,
-            0.0,
-            1.0
-        ]
-    ],
-    "distortion coefficients": [
-        [
-            0.01655492265003404,
-            0.1985524264972037,
-            0.002129965902489484,
-            -0.0019528582922179365,
-            -0.5792910353639452
-        ]
-    ]
-}
\ No newline at end of file
diff --git a/src/argaze/ArUcoMarkers/utils/tracker_configuration.json b/src/argaze/ArUcoMarkers/utils/tracker_configuration.json
deleted file mode 100644
index b5738a7..0000000
--- a/src/argaze/ArUcoMarkers/utils/tracker_configuration.json
+++ /dev/null
@@ -1,5 +0,0 @@
-{
-    "polygonalApproxAccuracyRate": 0.1,
-    "adaptiveThreshWinSizeMax": 30,
-    "adaptiveThreshWinSizeStep": 5
-}
\ No newline at end of file
diff --git a/src/argaze/AreaOfInterest/AOI3DScene.py b/src/argaze/AreaOfInterest/AOI3DScene.py
index 070789e..142738f 100644
--- a/src/argaze/AreaOfInterest/AOI3DScene.py
+++ b/src/argaze/AreaOfInterest/AOI3DScene.py
@@ -10,7 +10,6 @@ from argaze.AreaOfInterest import AOIFeatures, AOI2DScene
 import numpy
 import cv2 as cv
 
-
 T0 = numpy.array([0., 0., 0.])
 """Define no translation vector."""
 
@@ -188,9 +187,15 @@ class AOI3DScene(AOIFeatures.AOIScene):
 
 		* **Arguments:** 
 			- translation vector
-			- rotation matrix
+			- rotation vector
 			- camera intrinsic parameters matrix
 			- camera distorsion coefficients vector
+
+		.. danger::
+		   Camera distorsion coefficients could projects points which are far from the frame into it.
+
+		.. note::
+		   As gaze is mainly focusing on the frame center, where the distorsion is low, it could be acceptable to not use camera distorsion.
 		"""
 
 		aoi2D_scene = AOI2DScene.AOI2DScene()