From 626aa2e38503ba9c97508f0718de0557cfe65a6c Mon Sep 17 00:00:00 2001
From: Sefik Ilkin Serengil <serengil@gmail.com>
Date: Sat, 10 Feb 2024 18:17:11 +0000
Subject: [PATCH] adding some docstrings

---
 deepface/modules/verification.py | 33 ++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/deepface/modules/verification.py b/deepface/modules/verification.py
index 133dc45..b48d273 100644
--- a/deepface/modules/verification.py
+++ b/deepface/modules/verification.py
@@ -175,6 +175,14 @@ def verify(
 def find_cosine_distance(
     source_representation: Union[np.ndarray, list], test_representation: Union[np.ndarray, list]
 ) -> np.float64:
+    """
+    Find cosine distance between two given vectors
+    Args:
+        source_representation (np.ndarray or list): 1st vector
+        test_representation (np.ndarray or list): 2nd vector
+    Returns
+        distance (np.float64): calculated cosine distance
+    """
     if isinstance(source_representation, list):
         source_representation = np.array(source_representation)
 
@@ -190,6 +198,14 @@ def find_cosine_distance(
 def find_euclidean_distance(
     source_representation: Union[np.ndarray, list], test_representation: Union[np.ndarray, list]
 ) -> np.float64:
+    """
+    Find euclidean distance between two given vectors
+    Args:
+        source_representation (np.ndarray or list): 1st vector
+        test_representation (np.ndarray or list): 2nd vector
+    Returns
+        distance (np.float64): calculated euclidean distance
+    """
     if isinstance(source_representation, list):
         source_representation = np.array(source_representation)
 
@@ -203,12 +219,29 @@ def find_euclidean_distance(
 
 
 def l2_normalize(x: Union[np.ndarray, list]) -> np.ndarray:
+    """
+    Normalize input vector with l2
+    Args:
+        x (np.ndarray or list): given vector
+    Returns:
+        y (np.ndarray): l2 normalized vector
+    """
     if isinstance(x, list):
         x = np.array(x)
     return x / np.sqrt(np.sum(np.multiply(x, x)))
 
 
 def find_threshold(model_name: str, distance_metric: str) -> float:
+    """
+    Retrieve pre-tuned threshold values for a model and distance metric pair
+    Args:
+        model_name (str): facial recognition model name
+        distance_metric (str): distance metric name. Options are cosine, euclidean
+            and euclidean_l2.
+    Returns:
+        threshold (float): threshold value for that model name and distance metric
+            pair. Distances less than this threshold will be classified same person.
+    """
 
     base_threshold = {"cosine": 0.40, "euclidean": 0.55, "euclidean_l2": 0.75}