Feat task 2901 cleaning modules

.gitignore

@@ -11,3 +11,5 @@ tests/dataset/*.pkl
 tests/*.ipynb
 tests/*.csv
 *.pyc
+**/.coverage
+**/.coverage.*

Makefile

@@ -2,4 +2,7 @@ test:
 	cd tests && python -m pytest . -s --disable-warnings
 
 lint:
-	python -m pylint deepface/ --fail-under=10
+	python -m pylint deepface/ --fail-under=10
+
+coverage:
+	pip install pytest-cov && cd tests && python -m pytest --cov=deepface

deepface/DeepFace.py

@@ -58,6 +58,7 @@ def verify(
     distance_metric: str = "cosine",
     enforce_detection: bool = True,
     align: bool = True,
+    expand_percentage: int = 0,
     normalization: str = "base",
 ) -> Dict[str, Any]:
     """
@@ -83,6 +84,8 @@ def verify(
 
         align (bool): Flag to enable face alignment (default is True).
 
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
         normalization (string): Normalize the input image before feeding it to the model.
             Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace (default is base)
 
@@ -119,6 +122,7 @@ def verify(
         distance_metric=distance_metric,
         enforce_detection=enforce_detection,
         align=align,
+        expand_percentage=expand_percentage,
         normalization=normalization,
     )
 
@@ -129,6 +133,7 @@ def analyze(
     enforce_detection: bool = True,
     detector_backend: str = "opencv",
     align: bool = True,
+    expand_percentage: int = 0,
     silent: bool = False,
 ) -> List[Dict[str, Any]]:
     """
@@ -152,6 +157,8 @@ def analyze(
 
         align (boolean): Perform alignment based on the eye positions (default is True).
 
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
         silent (boolean): Suppress or allow some log messages for a quieter analysis process
             (default is False).
 
@@ -209,6 +216,7 @@ def analyze(
         enforce_detection=enforce_detection,
         detector_backend=detector_backend,
         align=align,
+        expand_percentage=expand_percentage,
         silent=silent,
     )
 
@@ -221,6 +229,7 @@ def find(
     enforce_detection: bool = True,
     detector_backend: str = "opencv",
     align: bool = True,
+    expand_percentage: int = 0,
     threshold: Optional[float] = None,
     normalization: str = "base",
     silent: bool = False,
@@ -249,6 +258,8 @@ def find(
 
         align (boolean): Perform alignment based on the eye positions (default is True).
 
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
         threshold (float): Specify a threshold to determine whether a pair represents the same
             person or different individuals. This threshold is used for comparing distances.
             If left unset, default pre-tuned threshold values will be applied based on the specified
@@ -286,6 +297,7 @@ def find(
         enforce_detection=enforce_detection,
         detector_backend=detector_backend,
         align=align,
+        expand_percentage=expand_percentage,
         threshold=threshold,
         normalization=normalization,
         silent=silent,
@@ -298,6 +310,7 @@ def represent(
     enforce_detection: bool = True,
     detector_backend: str = "opencv",
     align: bool = True,
+    expand_percentage: int = 0,
     normalization: str = "base",
 ) -> List[Dict[str, Any]]:
     """
@@ -320,6 +333,8 @@ def represent(
 
         align (boolean): Perform alignment based on the eye positions (default is True).
 
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
         normalization (string): Normalize the input image before feeding it to the model.
             Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
             (default is base).
@@ -346,6 +361,7 @@ def represent(
         enforce_detection=enforce_detection,
         detector_backend=detector_backend,
         align=align,
+        expand_percentage=expand_percentage,
         normalization=normalization,
     )
 
@@ -409,6 +425,7 @@ def extract_faces(
     detector_backend: str = "opencv",
     enforce_detection: bool = True,
     align: bool = True,
+    expand_percentage: int = 0,
     grayscale: bool = False,
 ) -> List[Dict[str, Any]]:
     """
@@ -429,6 +446,8 @@ def extract_faces(
 
         align (bool): Flag to enable face alignment (default is True).
 
+        expand_percentage (int): expand detected facial area with a percentage (default is 0).
+
         grayscale (boolean): Flag to convert the image to grayscale before
             processing (default is False).
 
@@ -448,7 +467,9 @@ def extract_faces(
         detector_backend=detector_backend,
         enforce_detection=enforce_detection,
         align=align,
+        expand_percentage=expand_percentage,
         grayscale=grayscale,
+        human_readable=True,
     )
 
 
@@ -459,3 +480,49 @@ def cli() -> None:
     import fire
 
     fire.Fire()
+
+
+# deprecated function(s)
+
+
+def detectFace(
+    img_path: Union[str, np.ndarray],
+    target_size: tuple = (224, 224),
+    detector_backend: str = "opencv",
+    enforce_detection: bool = True,
+    align: bool = True,
+) -> Union[np.ndarray, None]:
+    """
+    Deprecated face detection function. Use extract_faces for same functionality.
+
+    Args:
+        img_path (str or np.ndarray): Path to the first image. Accepts exact image path
+            as a string, numpy array (BGR), or base64 encoded images.
+
+        target_size (tuple): final shape of facial image. black pixels will be
+            added to resize the image (default is (224, 224)).
+
+        detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
+            'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv).
+
+        enforce_detection (boolean): If no face is detected in an image, raise an exception.
+            Set to False to avoid the exception for low-resolution images (default is True).
+
+        align (bool): Flag to enable face alignment (default is True).
+
+    Returns:
+            img (np.ndarray): detected (and aligned) facial area image as numpy array
+    """
+    logger.warn("Function detectFace is deprecated. Use extract_faces instead.")
+    face_objs = extract_faces(
+        img_path=img_path,
+        target_size=target_size,
+        detector_backend=detector_backend,
+        enforce_detection=enforce_detection,
+        align=align,
+        grayscale=False,
+    )
+    extracted_face = None
+    if len(face_objs) > 0:
+        extracted_face = face_objs[0]["face"]
+    return extracted_face

deepface/basemodels/ArcFace.py

@@ -53,6 +53,8 @@ class ArcFaceClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "ArcFace"
+        self.input_shape = (112, 112)
+        self.output_shape = 512
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/DeepID.py

@@ -49,6 +49,8 @@ class DeepIdClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "DeepId"
+        self.input_shape = (47, 55)
+        self.output_shape = 160
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/Dlib.py

@@ -20,6 +20,8 @@ class DlibClient(FacialRecognition):
     def __init__(self):
         self.model = DlibResNet()
         self.model_name = "Dlib"
+        self.input_shape = (150, 150)
+        self.output_shape = 128
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/Facenet.py

@@ -53,6 +53,8 @@ class FaceNet128dClient(FacialRecognition):
     def __init__(self):
         self.model = load_facenet128d_model()
         self.model_name = "FaceNet-128d"
+        self.input_shape = (160, 160)
+        self.output_shape = 128
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """
@@ -75,6 +77,8 @@ class FaceNet512dClient(FacialRecognition):
     def __init__(self):
         self.model = load_facenet512d_model()
         self.model_name = "FaceNet-512d"
+        self.input_shape = (160, 160)
+        self.output_shape = 512
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/FbDeepFace.py

@@ -46,6 +46,8 @@ class DeepFaceClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "DeepFace"
+        self.input_shape = (152, 152)
+        self.output_shape = 4096
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/OpenFace.py

@@ -36,6 +36,8 @@ class OpenFaceClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "OpenFace"
+        self.input_shape = (96, 96)
+        self.output_shape = 128
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/SFace.py

@@ -22,6 +22,8 @@ class SFaceClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "SFace"
+        self.input_shape = (112, 112)
+        self.output_shape = 128
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/basemodels/VGGFace.py

@@ -43,6 +43,8 @@ class VggFaceClient(FacialRecognition):
     def __init__(self):
         self.model = load_model()
         self.model_name = "VGG-Face"
+        self.input_shape = (224, 224)
+        self.output_shape = 4096
 
     def find_embeddings(self, img: np.ndarray) -> List[float]:
         """

deepface/commons/distance.py

@@ -2,7 +2,7 @@
 import numpy as np
 
 
-def findCosineDistance(
+def find_cosine_distance(
     source_representation: Union[np.ndarray, list], test_representation: Union[np.ndarray, list]
 ) -> np.float64:
     if isinstance(source_representation, list):
@@ -17,7 +17,7 @@ def findCosineDistance(
     return 1 - (a / (np.sqrt(b) * np.sqrt(c)))
 
 
-def findEuclideanDistance(
+def find_euclidean_distance(
     source_representation: Union[np.ndarray, list], test_representation: Union[np.ndarray, list]
 ) -> np.float64:
     if isinstance(source_representation, list):
@@ -38,7 +38,7 @@ def l2_normalize(x: Union[np.ndarray, list]) -> np.ndarray:
     return x / np.sqrt(np.sum(np.multiply(x, x)))
 
 
-def findThreshold(model_name: str, distance_metric: str) -> float:
+def find_threshold(model_name: str, distance_metric: str) -> float:
 
     base_threshold = {"cosine": 0.40, "euclidean": 0.55, "euclidean_l2": 0.75}