docstring updated

deepface/DeepFace.py

@@ -476,7 +476,9 @@ def extract_faces(
 
         - "facial_area" (Dict[str, Any]): The detected face's regions as a dictionary containing:
             - keys 'x', 'y', 'w', 'h' with int values
-            - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values
+            - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values. left and right eyes
+                are eyes on the left and right respectively with respect to the person itself
+                instead of observer.
 
         - "confidence" (float): The confidence score associated with the detected face.
     """

deepface/detectors/DetectorWrapper.py

@@ -76,7 +76,9 @@ def detect_faces(
 
         - img (np.ndarray): The detected face as a NumPy array.
 
-        - facial_area (FacialAreaRegion): The facial area region represented as x, y, w, h
+        - facial_area (FacialAreaRegion): The facial area region represented as x, y, w, h,
+            left_eye and right eye. left eye and right eye are eyes on the left and right
+            with respect to the person instead of observer.
 
         - confidence (float): The confidence score associated with the detected face.
     """
@@ -123,13 +125,11 @@ def detect_faces(
                 img=img, left_eye=left_eye, right_eye=right_eye
             )
             rotated_x1, rotated_y1, rotated_x2, rotated_y2 = rotate_facial_area(
-                facial_area=(x, y, x + w, y + h),
-                angle=angle,
-                size=(img.shape[0], img.shape[1])
+                facial_area=(x, y, x + w, y + h), angle=angle, size=(img.shape[0], img.shape[1])
             )
             detected_face = aligned_img[
-                int(rotated_y1) : int(rotated_y2),
-                int(rotated_x1) : int(rotated_x2)]
+                int(rotated_y1) : int(rotated_y2), int(rotated_x1) : int(rotated_x2)
+            ]
 
         result = DetectedFace(
             img=detected_face,
@@ -143,9 +143,7 @@ def detect_faces(
 
 
 def rotate_facial_area(
-    facial_area: Tuple[int, int, int, int],
-    angle: float,
-    size: Tuple[int, int]
+    facial_area: Tuple[int, int, int, int], angle: float, size: Tuple[int, int]
 ) -> Tuple[int, int, int, int]:
     """
     Rotate the facial area around its center.

deepface/models/Detector.py

@@ -20,7 +20,9 @@ class Detector(ABC):
                 where each object contains:
 
             - facial_area (FacialAreaRegion): The facial area region represented
-                as x, y, w, h, left_eye and right_eye
+                as x, y, w, h, left_eye and right_eye. left eye and right eye are
+                eyes on the left and right respectively with respect to the person
+                instead of observer.
         """
         pass
 
@@ -44,6 +46,21 @@ class FacialAreaRegion:
         right_eye: Optional[Tuple[int, int]] = None,
         confidence: Optional[float] = None,
     ):
+        """
+        Initialize a Face object.
+
+        Args:
+            x (int): The x-coordinate of the top-left corner of the bounding box.
+            y (int): The y-coordinate of the top-left corner of the bounding box.
+            w (int): The width of the bounding box.
+            h (int): The height of the bounding box.
+            left_eye (tuple): The coordinates (x, y) of the left eye with respect to
+                the person instead of observer. Default is None.
+            right_eye (tuple): The coordinates (x, y) of the right eye with respect to
+                the person instead of observer. Default is None.
+            confidence (float, optional): Confidence score associated with the face detection.
+                Default is None.
+        """
         self.x = x
         self.y = y
         self.w = w
@@ -59,6 +76,14 @@ class DetectedFace:
     confidence: float
 
     def __init__(self, img: np.ndarray, facial_area: FacialAreaRegion, confidence: float):
+        """
+        Initialize detected face object.
+
+        Args:
+            img (np.ndarray): detected face image as numpy array
+            facial_area (FacialAreaRegion): detected face's metadata (e.g. bounding box)
+            confidence (float): confidence score for face detection
+        """
         self.img = img
         self.facial_area = facial_area
         self.confidence = confidence

deepface/modules/detection.py

@@ -68,7 +68,9 @@ def extract_faces(
 
         - "facial_area" (Dict[str, Any]): The detected face's regions as a dictionary containing:
             - keys 'x', 'y', 'w', 'h' with int values
-            - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values
+            - keys 'left_eye', 'right_eye' with a tuple of 2 ints as values.
+                left eye and right eye are eyes on the left and right respectively with respect
+                to the person itself instead of observer.
 
         - "confidence" (float): The confidence score associated with the detected face.
     """