github/deepface
1
1
Fork 0
mirror of https://github.com/serengil/deepface.git synced 2025-06-07 12:05:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #965 from serengil/feat-task-2101-deepface-interface-docstrings

Browse Source 
cosmetic changes in docstrings of interface functions
This commit is contained in:
Sefik Ilkin Serengil 2024-01-21 23:01:14 +00:00 committed by GitHub
commit ddf008d396
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 301 additions and 287 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

311
deepface/DeepFace.py
View File

@ -61,34 +61,38 @@ def verify(
normalization: str = "base", normalization: str = "base",
) -> Dict[str, Any]: ) -> Dict[str, Any]:
""" """
This function verifies an image pair is same person or different persons. In the background, Verify if an image pair represents the same person or different persons.
verification function represents facial images as vectors and then calculates the similarity
between those vectors. Vectors of same person images should have more similarity (or less
distance) than vectors of different persons.
Parameters: The verification function converts facial images to vectors and calculates the similarity
img1_path, img2_path: exact image path as string. numpy array (BGR) or based64 encoded between those vectors. Vectors of images of the same person should exhibit higher similarity
images are also welcome. If one of pair has more than one face, then we will compare the (or lower distance) than vectors of images of different persons.
face pair with max similarity.
model_name (str): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib Args:
, ArcFace and SFace img1_path (str or np.ndarray): Path to the first image. Accepts exact image path
as a string, numpy array (BGR), or base64 encoded images.
distance_metric (string): cosine, euclidean, euclidean_l2 img2_path (str or np.ndarray): Path to the second image. Accepts exact image path
as a string, numpy array (BGR), or base64 encoded images.
enforce_detection (boolean): If no face could not be detected in an image, then this model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
function will return exception by default. Set this to False not to have this exception. OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
This might be convenient for low resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
normalization (string): normalize the input image before feeding to model enforce_detection (boolean): If no face is detected in an image, raise an exception.
Default is True. Set to False to avoid the exception for low-resolution images.
align (bool): Flag to enable face alignment (default is True).
normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
Returns: Returns:
Verify function returns a dictionary. result (dict): A dictionary containing verification results.
{ {
"verified": True "verified": True
@ -102,7 +106,6 @@ def verify(
} }
, "time": 2 , "time": 2
} }
""" """
return verification.verify( return verification.verify(
@ -126,63 +129,64 @@ def analyze(
silent: bool = False, silent: bool = False,
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function analyzes facial attributes including age, gender, emotion and race. Analyze facial attributes such as age, gender, emotion, and race in the provided image.
In the background, analysis function builds convolutional neural network models to
classify age, gender, emotion and race of the input image.
Parameters: Args:
img_path: exact image path, numpy array (BGR) or base64 encoded image could be passed. img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
If source image has more than one face, then result will be size of number of faces or a base64 encoded image. If the source image contains multiple faces, the result will
appearing in the image. include information for each detected face.
actions (tuple): The default is ('age', 'gender', 'emotion', 'race'). You can drop actions (tuple): Attributes to analyze. The default is ('age', 'gender', 'emotion', 'race').
some of those attributes. You can exclude some of these attributes from the analysis if needed.
enforce_detection (bool): The function throws exception if no face detected by default. enforce_detection (boolean): If no face is detected in an image, raise an exception.
Set this to False if you don't want to get exception. This might be convenient for low Default is True. Set to False to avoid the exception for low-resolution images.
resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
silent (boolean): disable (some) log messages align (boolean): Perform alignment based on the eye positions.
silent (boolean): Suppress or allow some log messages for a quieter analysis process.
Returns: Returns:
The function returns a list of dictionaries for each face appearing in the image. results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary represents
the analysis results for a detected face. Example:
[ [
{ {
"region": {'x': 230, 'y': 120, 'w': 36, 'h': 45}, "region": {'x': 230, 'y': 120, 'w': 36, 'h': 45},
"age": 28.66, "age": 28.66,
'face_confidence': 0.9993908405303955, 'face_confidence': 0.9993908405303955,
"dominant_gender": "Woman", "dominant_gender": "Woman",
"gender": { "gender": {
'Woman': 99.99407529830933, 'Woman': 99.99407529830933,
'Man': 0.005928758764639497, 'Man': 0.005928758764639497,
} }
"dominant_emotion": "neutral", "dominant_emotion": "neutral",
"emotion": { "emotion": {
'sad': 37.65260875225067, 'sad': 37.65260875225067,
'angry': 0.15512987738475204, 'angry': 0.15512987738475204,
'surprise': 0.0022171278033056296, 'surprise': 0.0022171278033056296,
'fear': 1.2489334680140018, 'fear': 1.2489334680140018,
'happy': 4.609785228967667, 'happy': 4.609785228967667,
'disgust': 9.698561953541684e-07, 'disgust': 9.698561953541684e-07,
'neutral': 56.33133053779602 'neutral': 56.33133053779602
} }
"dominant_race": "white", "dominant_race": "white",
"race": { "race": {
'indian': 0.5480832420289516, 'indian': 0.5480832420289516,
'asian': 0.7830780930817127, 'asian': 0.7830780930817127,
'latino hispanic': 2.0677512511610985, 'latino hispanic': 2.0677512511610985,
'black': 0.06337375962175429, 'black': 0.06337375962175429,
'middle eastern': 3.088453598320484, 'middle eastern': 3.088453598320484,
'white': 93.44925880432129 'white': 93.44925880432129
} }
} }
] ]
""" """
return demography.analyze( return demography.analyze(
img_path=img_path, img_path=img_path,
@ -206,38 +210,47 @@ def find(
silent: bool = False, silent: bool = False,
) -> List[pd.DataFrame]: ) -> List[pd.DataFrame]:
""" """
This function applies verification several times and find the identities in a database Identify individuals in a database
Parameters: Args:
img_path: exact image path, numpy array (BGR) or based64 encoded image. img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
Source image can have many faces. Then, result will be the size of number of or a base64 encoded image. If the source image contains multiple faces, the result will
faces in the source image. include information for each detected face.
db_path (string): You should store some image files in a folder and pass the db_path (string): Path to the folder containing image files. All detected faces
exact folder path to this. A database image can also have many faces. in the database will be considered in the decision-making process.
Then, all detected faces in db side will be considered in the decision.
model_name (string): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
Dlib, ArcFace, SFace or Ensemble OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
distance_metric (string): cosine, euclidean, euclidean_l2 distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
enforce_detection (bool): The function throws exception if a face could not be detected. enforce_detection (boolean): If no face is detected in an image, raise an exception.
Set this to False if you don't want to get exception. This might be convenient for low Default is True. Set to False to avoid the exception for low-resolution images.
resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. align (boolean): Perform alignment based on the eye positions.
normalization (string): normalize the input image before feeding to model normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
silent (boolean): disable some logging and progress bars silent (boolean): Suppress or allow some log messages for a quieter analysis process.
Returns: Returns:
This function returns list of pandas data frame. Each item of the list corresponding to results (List[pd.DataFrame]): A list of pandas dataframes. Each dataframe corresponds
an identity in the img_path. to the identity information for an individual detected in the source image.
The DataFrame columns include:
- 'identity': Identity label of the detected individual.
- 'target_x', 'target_y', 'target_w', 'target_h': Bounding box coordinates of the
target face in the database.
- 'source_x', 'source_y', 'source_w', 'source_h': Bounding box coordinates of the
detected face in the source image.
- '{model_name}_{distance_metric}': Similarity score between the faces based on the
specified model and distance metric
""" """
return recognition.find( return recognition.find(
img_path=img_path, img_path=img_path,
@ -261,47 +274,40 @@ def represent(
normalization: str = "base", normalization: str = "base",
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function represents facial images as vectors. The function uses convolutional neural Represent facial images as multi-dimensional vector embeddings.
networks models to generate vector embeddings.
Parameters: Args:
img_path (string): exact image path. Alternatively, numpy array (BGR) or based64 img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
encoded images could be passed. Source image can have many faces. Then, result will or a base64 encoded image. If the source image contains multiple faces, the result will
be the size of number of faces appearing in the source image. include information for each detected face.
model_name (string): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib, model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
ArcFace, SFace OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
enforce_detection (boolean): If no face could not be detected in an image, then this enforce_detection (boolean): If no face is detected in an image, raise an exception.
function will return exception by default. Set this to False not to have this exception. Default is True. Set to False to avoid the exception for low-resolution images.
This might be convenient for low resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. A special value `skip` could be used to skip face-detection 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
and only encode the given image.
align (boolean): alignment according to the eye positions. align (boolean): Perform alignment based on the eye positions.
normalization (string): normalize the input image before feeding to model normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
Returns: Returns:
Represent function returns a list of object, each object has fields as follows: results (List[Dict[str, Any]]): A list of dictionaries, each containing the
{ following fields:
// Multidimensional vector
// The number of dimensions is changing based on the reference model.
// E.g. FaceNet returns 128 dimensional vector;
// VGG-Face returns 2622 dimensional vector.
"embedding": np.array,
// Detected Facial-Area by Face detection in dict format. - embedding (np.array): Multidimensional vector representing facial features.
// (x, y) is left-corner point, and (w, h) is the width and height The number of dimensions varies based on the reference model
// If `detector_backend` == `skip`, it is the full image area and nonsense. (e.g., FaceNet returns 128 dimensions, VGG-Face returns 4096 dimensions).
"facial_area": dict{"x": int, "y": int, "w": int, "h": int}, - facial_area (dict): Detected facial area by face detection in dictionary format.
Contains 'x' and 'y' as the left-corner point, and 'w' and 'h'
// Face detection confidence. as the width and height. If `detector_backend` is set to 'skip', it represents
// If `detector_backend` == `skip`, will be 0 and nonsense. the full image area and is nonsensical.
"face_confidence": float - face_confidence (float): Confidence score of face detection. If `detector_backend` is set
} to 'skip', the confidence will be 0 and is nonsensical.
""" """
return representation.represent( return representation.represent(
img_path=img_path, img_path=img_path,
@ -324,26 +330,31 @@ def stream(
frame_threshold: int = 5, frame_threshold: int = 5,
) -> None: ) -> None:
""" """
This function applies real time face recognition and facial attribute analysis Run real time face recognition and facial attribute analysis
Parameters: Args:
db_path (string): facial database path. You should store some .jpg files in this folder. db_path (string): Path to the folder containing image files. All detected faces
in the database will be considered in the decision-making process.
model_name (string): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib, model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
ArcFace, SFace OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
detector_backend (string): opencv, retinaface, mtcnn, ssd, dlib, mediapipe or yolov8. detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
distance_metric (string): cosine, euclidean, euclidean_l2 distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
enable_facial_analysis (boolean): Set this to False to just run face recognition enable_face_analysis (bool): Flag to enable face analysis (default is True).
source: Set this to 0 for access web cam. Otherwise, pass exact video path. source (Any): The source for the video stream (default is 0, which represents the
default camera).
time_threshold (int): how many second analyzed image will be displayed time_threshold (int): The time threshold (in seconds) for face recognition (default is 5).
frame_threshold (int): how many frames required to focus on face
frame_threshold (int): The frame threshold for face recognition (default is 5).
Returns:
None
""" """
time_threshold = max(time_threshold, 1) time_threshold = max(time_threshold, 1)
@ -370,32 +381,32 @@ def extract_faces(
grayscale: bool = False, grayscale: bool = False,
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function applies pre-processing stages of a face recognition pipeline Extract faces from a given image
including detection and alignment
Parameters: Args:
img_path: exact image path, numpy array (BGR) or base64 encoded image. img_path (str or np.ndarray): Path to the first image. Accepts exact image path
Source image can have many face. Then, result will be the size of number as a string, numpy array (BGR), or base64 encoded images.
of faces appearing in that source image.
target_size (tuple): final shape of facial image. black pixels will be target_size (tuple): final shape of facial image. black pixels will be
added to resize the image. added to resize the image.
detector_backend (string): face detection backends are retinaface, mtcnn, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
opencv, ssd or dlib 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv)
enforce_detection (boolean): function throws exception if face cannot be enforce_detection (boolean): If no face is detected in an image, raise an exception.
detected in the fed image. Set this to False if you do not want to get Default is True. Set to False to avoid the exception for low-resolution images.
an exception and run the function anyway.
align (boolean): alignment according to the eye positions. align (bool): Flag to enable face alignment (default is True).
grayscale (boolean): Flag to convert the image to grayscale before
processing (default is False).
grayscale (boolean): extracting faces in rgb or gray scale
Returns: Returns:
list of dictionaries. Each dictionary will have facial image itself, results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary contains:
extracted area from the original image and confidence score. - "face" (np.ndarray): The detected face as a NumPy array.
- "facial_area" (List[float]): The detected face's regions represented as a list of floats.
- "confidence" (float): The confidence score associated with the detected face.
""" """
return detection.extract_faces( return detection.extract_faces(

97
deepface/modules/demography.py
View File

@ -20,63 +20,64 @@ def analyze(
silent: bool = False, silent: bool = False,
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function analyzes facial attributes including age, gender, emotion and race. Analyze facial attributes such as age, gender, emotion, and race in the provided image.
In the background, analysis function builds convolutional neural network models to
classify age, gender, emotion and race of the input image.
Parameters: Args:
img_path: exact image path, numpy array (BGR) or base64 encoded image could be passed. img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
If source image has more than one face, then result will be size of number of faces or a base64 encoded image. If the source image contains multiple faces, the result will
appearing in the image. include information for each detected face.
actions (tuple): The default is ('age', 'gender', 'emotion', 'race'). You can drop actions (tuple): Attributes to analyze. The default is ('age', 'gender', 'emotion', 'race').
some of those attributes. You can exclude some of these attributes from the analysis if needed.
enforce_detection (bool): The function throws exception if no face detected by default. enforce_detection (boolean): If no face is detected in an image, raise an exception.
Set this to False if you don't want to get exception. This might be convenient for low Default is True. Set to False to avoid the exception for low-resolution images.
resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
silent (boolean): disable (some) log messages align (boolean): Perform alignment based on the eye positions.
silent (boolean): Suppress or allow some log messages for a quieter analysis process.
Returns: Returns:
The function returns a list of dictionaries for each face appearing in the image. results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary represents
the analysis results for a detected face. Example:
[ [
{ {
"region": {'x': 230, 'y': 120, 'w': 36, 'h': 45}, "region": {'x': 230, 'y': 120, 'w': 36, 'h': 45},
"age": 28.66, "age": 28.66,
'face_confidence': 0.9993908405303955, 'face_confidence': 0.9993908405303955,
"dominant_gender": "Woman", "dominant_gender": "Woman",
"gender": { "gender": {
'Woman': 99.99407529830933, 'Woman': 99.99407529830933,
'Man': 0.005928758764639497, 'Man': 0.005928758764639497,
} }
"dominant_emotion": "neutral", "dominant_emotion": "neutral",
"emotion": { "emotion": {
'sad': 37.65260875225067, 'sad': 37.65260875225067,
'angry': 0.15512987738475204, 'angry': 0.15512987738475204,
'surprise': 0.0022171278033056296, 'surprise': 0.0022171278033056296,
'fear': 1.2489334680140018, 'fear': 1.2489334680140018,
'happy': 4.609785228967667, 'happy': 4.609785228967667,
'disgust': 9.698561953541684e-07, 'disgust': 9.698561953541684e-07,
'neutral': 56.33133053779602 'neutral': 56.33133053779602
} }
"dominant_race": "white", "dominant_race": "white",
"race": { "race": {
'indian': 0.5480832420289516, 'indian': 0.5480832420289516,
'asian': 0.7830780930817127, 'asian': 0.7830780930817127,
'latino hispanic': 2.0677512511610985, 'latino hispanic': 2.0677512511610985,
'black': 0.06337375962175429, 'black': 0.06337375962175429,
'middle eastern': 3.088453598320484, 'middle eastern': 3.088453598320484,
'white': 93.44925880432129 'white': 93.44925880432129
} }
} }
] ]
""" """
# --------------------------------- # ---------------------------------
# validate actions # validate actions

29
deepface/modules/detection.py
View File

@ -18,35 +18,32 @@ def extract_faces(
grayscale: bool = False, grayscale: bool = False,
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function applies pre-processing stages of a face recognition pipeline Extract faces from a given image
including detection and alignment
Parameters: Args:
img_path: exact image path, numpy array (BGR) or base64 encoded image. img_path (str or np.ndarray): Path to the first image. Accepts exact image path
Source image can have many face. Then, result will be the size of number as a string, numpy array (BGR), or base64 encoded images.
of faces appearing in that source image.
target_size (tuple): final shape of facial image. black pixels will be target_size (tuple): final shape of facial image. black pixels will be
added to resize the image. added to resize the image.
detector_backend (string): face detection backends are retinaface, mtcnn, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
opencv, ssd or dlib 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv)
enforce_detection (boolean): function throws exception if face cannot be enforce_detection (boolean): If no face is detected in an image, raise an exception.
detected in the fed image. Set this to False if you do not want to get Default is True. Set to False to avoid the exception for low-resolution images.
an exception and run the function anyway.
align (boolean): alignment according to the eye positions. align (bool): Flag to enable face alignment (default is True).
grayscale (boolean): Flag to convert the image to grayscale before
processing (default is False).
grayscale (boolean): extracting faces in rgb or gray scale
Returns: Returns:
results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary contains: results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary contains:
- "face" (np.ndarray): The detected face as a NumPy array. - "face" (np.ndarray): The detected face as a NumPy array.
- "facial_area" (List[float]): The detected face's regions represented as a list of floats. - "facial_area" (List[float]): The detected face's regions represented as a list of floats.
- "confidence" (float): The confidence score associated with the detected face. - "confidence" (float): The confidence score associated with the detected face.
""" """
resp_objs = [] resp_objs = []

51
deepface/modules/recognition.py
View File

@ -29,38 +29,47 @@ def find(
silent: bool = False, silent: bool = False,
) -> List[pd.DataFrame]: ) -> List[pd.DataFrame]:
""" """
This function applies verification several times and find the identities in a database Identify individuals in a database
Parameters: Args:
img_path: exact image path, numpy array (BGR) or based64 encoded image. img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
Source image can have many faces. Then, result will be the size of number of or a base64 encoded image. If the source image contains multiple faces, the result will
faces in the source image. include information for each detected face.
db_path (string): You should store some image files in a folder and pass the db_path (string): Path to the folder containing image files. All detected faces
exact folder path to this. A database image can also have many faces. in the database will be considered in the decision-making process.
Then, all detected faces in db side will be considered in the decision.
model_name (string): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
Dlib, ArcFace, SFace or Ensemble OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
distance_metric (string): cosine, euclidean, euclidean_l2 distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
enforce_detection (bool): The function throws exception if a face could not be detected. enforce_detection (boolean): If no face is detected in an image, raise an exception.
Set this to False if you don't want to get exception. This might be convenient for low Default is True. Set to False to avoid the exception for low-resolution images.
resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. align (boolean): Perform alignment based on the eye positions.
normalization (string): normalize the input image before feeding to model normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
silent (boolean): disable some logging and progress bars silent (boolean): Suppress or allow some log messages for a quieter analysis process.
Returns: Returns:
This function returns list of pandas data frame. Each item of the list corresponding to results (List[pd.DataFrame]): A list of pandas dataframes. Each dataframe corresponds
an identity in the img_path. to the identity information for an individual detected in the source image.
The DataFrame columns include:
- 'identity': Identity label of the detected individual.
- 'target_x', 'target_y', 'target_w', 'target_h': Bounding box coordinates of the
target face in the database.
- 'source_x', 'source_y', 'source_w', 'source_h': Bounding box coordinates of the
detected face in the source image.
- '{model_name}_{distance_metric}': Similarity score between the faces based on the
specified model and distance metric
""" """
tic = time.time() tic = time.time()

57
deepface/modules/representation.py
View File

@ -20,47 +20,40 @@ def represent(
normalization: str = "base", normalization: str = "base",
) -> List[Dict[str, Any]]: ) -> List[Dict[str, Any]]:
""" """
This function represents facial images as vectors. The function uses convolutional neural Represent facial images as multi-dimensional vector embeddings.
networks models to generate vector embeddings.
Parameters: Args:
img_path (string): exact image path. Alternatively, numpy array (BGR) or based64 img_path (str or np.ndarray): The exact path to the image, a numpy array in BGR format,
encoded images could be passed. Source image can have many faces. Then, result will or a base64 encoded image. If the source image contains multiple faces, the result will
be the size of number of faces appearing in the source image. include information for each detected face.
model_name (string): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib, model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
ArcFace, SFace OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
enforce_detection (boolean): If no face could not be detected in an image, then this enforce_detection (boolean): If no face is detected in an image, raise an exception.
function will return exception by default. Set this to False not to have this exception. Default is True. Set to False to avoid the exception for low-resolution images.
This might be convenient for low resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. A special value `skip` could be used to skip face-detection 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
and only encode the given image.
align (boolean): alignment according to the eye positions. align (boolean): Perform alignment based on the eye positions.
normalization (string): normalize the input image before feeding to model normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
Returns: Returns:
Represent function returns a list of object, each object has fields as follows: results (List[Dict[str, Any]]): A list of dictionaries, each containing the
{ following fields:
// Multidimensional vector
// The number of dimensions is changing based on the reference model.
// E.g. FaceNet returns 128 dimensional vector;
// VGG-Face returns 2622 dimensional vector.
"embedding": np.array,
// Detected Facial-Area by Face detection in dict format. - embedding (np.array): Multidimensional vector representing facial features.
// (x, y) is left-corner point, and (w, h) is the width and height The number of dimensions varies based on the reference model
// If `detector_backend` == `skip`, it is the full image area and nonsense. (e.g., FaceNet returns 128 dimensions, VGG-Face returns 4096 dimensions).
"facial_area": dict{"x": int, "y": int, "w": int, "h": int}, - facial_area (dict): Detected facial area by face detection in dictionary format.
Contains 'x' and 'y' as the left-corner point, and 'w' and 'h'
// Face detection confidence. as the width and height. If `detector_backend` is set to 'skip', it represents
// If `detector_backend` == `skip`, will be 0 and nonsense. the full image area and is nonsensical.
"face_confidence": float - face_confidence (float): Confidence score of face detection. If `detector_backend` is set
} to 'skip', the confidence will be 0 and is nonsensical.
""" """
resp_objs = [] resp_objs = []

43
deepface/modules/verification.py
View File

@ -21,34 +21,38 @@ def verify(
normalization: str = "base", normalization: str = "base",
) -> Dict[str, Any]: ) -> Dict[str, Any]:
""" """
This function verifies an image pair is same person or different persons. In the background, Verify if an image pair represents the same person or different persons.
verification function represents facial images as vectors and then calculates the similarity
between those vectors. Vectors of same person images should have more similarity (or less
distance) than vectors of different persons.
Parameters: The verification function converts facial images to vectors and calculates the similarity
img1_path, img2_path: exact image path as string. numpy array (BGR) or based64 encoded between those vectors. Vectors of images of the same person should exhibit higher similarity
images are also welcome. If one of pair has more than one face, then we will compare the (or lower distance) than vectors of images of different persons.
face pair with max similarity.
model_name (str): VGG-Face, Facenet, Facenet512, OpenFace, DeepFace, DeepID, Dlib Args:
, ArcFace and SFace img1_path (str or np.ndarray): Path to the first image. Accepts exact image path
as a string, numpy array (BGR), or base64 encoded images.
distance_metric (string): cosine, euclidean, euclidean_l2 img2_path (str or np.ndarray): Path to the second image. Accepts exact image path
as a string, numpy array (BGR), or base64 encoded images.
enforce_detection (boolean): If no face could not be detected in an image, then this model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
function will return exception by default. Set this to False not to have this exception. OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
This might be convenient for low resolution images.
detector_backend (string): set face detector backend to opencv, retinaface, mtcnn, ssd, detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
dlib, mediapipe or yolov8. 'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
align (boolean): alignment according to the eye positions. distance_metric (string): Metric for measuring similarity. Options: 'cosine',
'euclidean', 'euclidean_l2'.
normalization (string): normalize the input image before feeding to model enforce_detection (boolean): If no face is detected in an image, raise an exception.
Default is True. Set to False to avoid the exception for low-resolution images.
align (bool): Flag to enable face alignment (default is True).
normalization (string): Normalize the input image before feeding it to the model.
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
Returns: Returns:
Verify function returns a dictionary. result (dict): A dictionary containing verification results.
{ {
"verified": True "verified": True
@ -62,7 +66,6 @@ def verify(
} }
, "time": 2 , "time": 2
} }
""" """
tic = time.time() tic = time.time()