Skip to content

Commit d429d71

Browse files
serengilserengil
committed
examples explained in docstrings
1 parent ddf008d commit d429d71

File tree

3 files changed

+155
-111
lines changed

3 files changed

+155
-111
lines changed

‎deepface/DeepFace.py

+77-55
Original file line numberDiff line numberDiff line change
@@ -75,37 +75,45 @@ def verify(
7575
as a string, numpy array (BGR), or base64 encoded images.
7676
7777
model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
78-
OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
78+
OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace (default is VGG-Face).
7979
8080
detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
81-
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
81+
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv)
8282
8383
distance_metric (string): Metric for measuring similarity. Options: 'cosine',
84-
'euclidean', 'euclidean_l2'.
84+
'euclidean', 'euclidean_l2' (default is cosine).
8585
8686
enforce_detection (boolean): If no face is detected in an image, raise an exception.
87-
Default is True. Set to False to avoid the exception for low-resolution images.
87+
Set to False to avoid the exception for low-resolution images (default is True).
8888
8989
align (bool): Flag to enable face alignment (default is True).
9090
9191
normalization (string): Normalize the input image before feeding it to the model.
92-
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
92+
Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace (default is base)
9393
9494
Returns:
9595
result (dict): A dictionary containing verification results.
9696
97-
{
98-
"verified": True
99-
, "distance": 0.2563
100-
, "max_threshold_to_verify": 0.40
101-
, "model": "VGG-Face"
102-
, "similarity_metric": "cosine"
103-
, 'facial_areas': {
104-
'img1': {'x': 345, 'y': 211, 'w': 769, 'h': 769},
105-
'img2': {'x': 318, 'y': 534, 'w': 779, 'h': 779}
106-
}
107-
, "time": 2
108-
}
97+
- 'verified' (bool): Indicates whether the images represent the same person (True)
98+
or different persons (False).
99+
100+
- 'distance' (float): The distance measure between the face vectors.
101+
A lower distance indicates higher similarity.
102+
103+
- 'max_threshold_to_verify' (float): The maximum threshold used for verification.
104+
If the distance is below this threshold, the images are considered a match.
105+
106+
- 'model' (str): The chosen face recognition model.
107+
108+
- 'similarity_metric' (str): The chosen similarity metric for measuring distances.
109+
110+
- 'facial_areas' (dict): Rectangular regions of interest for faces in both images.
111+
- 'img1': {'x': int, 'y': int, 'w': int, 'h': int}
112+
Region of interest for the first image.
113+
- 'img2': {'x': int, 'y': int, 'w': int, 'h': int}
114+
Region of interest for the second image.
115+
116+
- 'time' (float): Time taken for the verification process in seconds.
109117
"""
110118

111119
return verification.verify(
@@ -140,53 +148,67 @@ def analyze(
140148
You can exclude some of these attributes from the analysis if needed.
141149
142150
enforce_detection (boolean): If no face is detected in an image, raise an exception.
143-
Default is True. Set to False to avoid the exception for low-resolution images.
151+
Set to False to avoid the exception for low-resolution images (default is True).
144152
145153
detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
146-
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
154+
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv).
147155
148156
distance_metric (string): Metric for measuring similarity. Options: 'cosine',
149-
'euclidean', 'euclidean_l2'.
157+
'euclidean', 'euclidean_l2' (default is cosine).
150158
151-
align (boolean): Perform alignment based on the eye positions.
159+
align (boolean): Perform alignment based on the eye positions (default is True).
152160
153-
silent (boolean): Suppress or allow some log messages for a quieter analysis process.
161+
silent (boolean): Suppress or allow some log messages for a quieter analysis process
162+
(default is False).
154163
155164
Returns:
156165
results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary represents
157-
the analysis results for a detected face. Example:
158-
159-
[
160-
{
161-
"region": {'x': 230, 'y': 120, 'w': 36, 'h': 45},
162-
"age": 28.66,
163-
'face_confidence': 0.9993908405303955,
164-
"dominant_gender": "Woman",
165-
"gender": {
166-
'Woman': 99.99407529830933,
167-
'Man': 0.005928758764639497,
168-
}
169-
"dominant_emotion": "neutral",
170-
"emotion": {
171-
'sad': 37.65260875225067,
172-
'angry': 0.15512987738475204,
173-
'surprise': 0.0022171278033056296,
174-
'fear': 1.2489334680140018,
175-
'happy': 4.609785228967667,
176-
'disgust': 9.698561953541684e-07,
177-
'neutral': 56.33133053779602
178-
}
179-
"dominant_race": "white",
180-
"race": {
181-
'indian': 0.5480832420289516,
182-
'asian': 0.7830780930817127,
183-
'latino hispanic': 2.0677512511610985,
184-
'black': 0.06337375962175429,
185-
'middle eastern': 3.088453598320484,
186-
'white': 93.44925880432129
187-
}
188-
}
189-
]
166+
the analysis results for a detected face.
167+
168+
Each dictionary in the list contains the following keys:
169+
170+
- 'region' (dict): Represents the rectangular region of the detected face in the image.
171+
- 'x': x-coordinate of the top-left corner of the face.
172+
- 'y': y-coordinate of the top-left corner of the face.
173+
- 'w': Width of the detected face region.
174+
- 'h': Height of the detected face region.
175+
176+
- 'age' (float): Estimated age of the detected face.
177+
178+
- 'face_confidence' (float): Confidence score for the detected face.
179+
Indicates the reliability of the face detection.
180+
181+
- 'dominant_gender' (str): The dominant gender in the detected face.
182+
Either "Man" or "Woman."
183+
184+
- 'gender' (dict): Confidence scores for each gender category.
185+
- 'Man': Confidence score for the male gender.
186+
- 'Woman': Confidence score for the female gender.
187+
188+
- 'dominant_emotion' (str): The dominant emotion in the detected face.
189+
Possible values include "sad," "angry," "surprise," "fear," "happy,"
190+
"disgust," and "neutral."
191+
192+
- 'emotion' (dict): Confidence scores for each emotion category.
193+
- 'sad': Confidence score for sadness.
194+
- 'angry': Confidence score for anger.
195+
- 'surprise': Confidence score for surprise.
196+
- 'fear': Confidence score for fear.
197+
- 'happy': Confidence score for happiness.
198+
- 'disgust': Confidence score for disgust.
199+
- 'neutral': Confidence score for neutrality.
200+
201+
- 'dominant_race' (str): The dominant race in the detected face.
202+
Possible values include "indian," "asian," "latino hispanic,"
203+
"black," "middle eastern," and "white."
204+
205+
- 'race' (dict): Confidence scores for each race category.
206+
- 'indian': Confidence score for Indian ethnicity.
207+
- 'asian': Confidence score for Asian ethnicity.
208+
- 'latino hispanic': Confidence score for Latino/Hispanic ethnicity.
209+
- 'black': Confidence score for Black ethnicity.
210+
- 'middle eastern': Confidence score for Middle Eastern ethnicity.
211+
- 'white': Confidence score for White ethnicity.
190212
"""
191213
return demography.analyze(
192214
img_path=img_path,

‎deepface/modules/demography.py

+53-39
Original file line numberDiff line numberDiff line change
@@ -31,55 +31,69 @@ def analyze(
3131
You can exclude some of these attributes from the analysis if needed.
3232
3333
enforce_detection (boolean): If no face is detected in an image, raise an exception.
34-
Default is True. Set to False to avoid the exception for low-resolution images.
34+
Set to False to avoid the exception for low-resolution images (default is True).
3535
3636
detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
37-
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
37+
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv).
3838
3939
distance_metric (string): Metric for measuring similarity. Options: 'cosine',
40-
'euclidean', 'euclidean_l2'.
40+
'euclidean', 'euclidean_l2' (default is cosine).
4141
42-
align (boolean): Perform alignment based on the eye positions.
42+
align (boolean): Perform alignment based on the eye positions (default is True).
4343
44-
silent (boolean): Suppress or allow some log messages for a quieter analysis process.
44+
silent (boolean): Suppress or allow some log messages for a quieter analysis process
45+
(default is False).
4546
4647
Returns:
4748
results (List[Dict[str, Any]]): A list of dictionaries, where each dictionary represents
48-
the analysis results for a detected face. Example:
49-
50-
[
51-
{
52-
"region": {'x': 230, 'y': 120, 'w': 36, 'h': 45},
53-
"age": 28.66,
54-
'face_confidence': 0.9993908405303955,
55-
"dominant_gender": "Woman",
56-
"gender": {
57-
'Woman': 99.99407529830933,
58-
'Man': 0.005928758764639497,
59-
}
60-
"dominant_emotion": "neutral",
61-
"emotion": {
62-
'sad': 37.65260875225067,
63-
'angry': 0.15512987738475204,
64-
'surprise': 0.0022171278033056296,
65-
'fear': 1.2489334680140018,
66-
'happy': 4.609785228967667,
67-
'disgust': 9.698561953541684e-07,
68-
'neutral': 56.33133053779602
69-
}
70-
"dominant_race": "white",
71-
"race": {
72-
'indian': 0.5480832420289516,
73-
'asian': 0.7830780930817127,
74-
'latino hispanic': 2.0677512511610985,
75-
'black': 0.06337375962175429,
76-
'middle eastern': 3.088453598320484,
77-
'white': 93.44925880432129
78-
}
79-
}
80-
]
49+
the analysis results for a detected face.
50+
51+
Each dictionary in the list contains the following keys:
52+
53+
- 'region' (dict): Represents the rectangular region of the detected face in the image.
54+
- 'x': x-coordinate of the top-left corner of the face.
55+
- 'y': y-coordinate of the top-left corner of the face.
56+
- 'w': Width of the detected face region.
57+
- 'h': Height of the detected face region.
58+
59+
- 'age' (float): Estimated age of the detected face.
60+
61+
- 'face_confidence' (float): Confidence score for the detected face.
62+
Indicates the reliability of the face detection.
63+
64+
- 'dominant_gender' (str): The dominant gender in the detected face.
65+
Either "Man" or "Woman."
66+
67+
- 'gender' (dict): Confidence scores for each gender category.
68+
- 'Man': Confidence score for the male gender.
69+
- 'Woman': Confidence score for the female gender.
70+
71+
- 'dominant_emotion' (str): The dominant emotion in the detected face.
72+
Possible values include "sad," "angry," "surprise," "fear," "happy,"
73+
"disgust," and "neutral."
74+
75+
- 'emotion' (dict): Confidence scores for each emotion category.
76+
- 'sad': Confidence score for sadness.
77+
- 'angry': Confidence score for anger.
78+
- 'surprise': Confidence score for surprise.
79+
- 'fear': Confidence score for fear.
80+
- 'happy': Confidence score for happiness.
81+
- 'disgust': Confidence score for disgust.
82+
- 'neutral': Confidence score for neutrality.
83+
84+
- 'dominant_race' (str): The dominant race in the detected face.
85+
Possible values include "indian," "asian," "latino hispanic,"
86+
"black," "middle eastern," and "white."
87+
88+
- 'race' (dict): Confidence scores for each race category.
89+
- 'indian': Confidence score for Indian ethnicity.
90+
- 'asian': Confidence score for Asian ethnicity.
91+
- 'latino hispanic': Confidence score for Latino/Hispanic ethnicity.
92+
- 'black': Confidence score for Black ethnicity.
93+
- 'middle eastern': Confidence score for Middle Eastern ethnicity.
94+
- 'white': Confidence score for White ethnicity.
8195
"""
82-
# ---------------------------------
96+
8397
# validate actions
8498
if isinstance(actions, str):
8599
actions = (actions,)

‎deepface/modules/verification.py

+25-17
Original file line numberDiff line numberDiff line change
@@ -35,37 +35,45 @@ def verify(
3535
as a string, numpy array (BGR), or base64 encoded images.
3636
3737
model_name (str): Model for face recognition. Options: VGG-Face, Facenet, Facenet512,
38-
OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace
38+
OpenFace, DeepFace, DeepID, Dlib, ArcFace and SFace (default is VGG-Face).
3939
4040
detector_backend (string): face detector backend. Options: 'opencv', 'retinaface',
41-
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8'.
41+
'mtcnn', 'ssd', 'dlib', 'mediapipe', 'yolov8' (default is opencv)
4242
4343
distance_metric (string): Metric for measuring similarity. Options: 'cosine',
44-
'euclidean', 'euclidean_l2'.
44+
'euclidean', 'euclidean_l2' (default is cosine).
4545
4646
enforce_detection (boolean): If no face is detected in an image, raise an exception.
47-
Default is True. Set to False to avoid the exception for low-resolution images.
47+
Set to False to avoid the exception for low-resolution images (default is True).
4848
4949
align (bool): Flag to enable face alignment (default is True).
5050
5151
normalization (string): Normalize the input image before feeding it to the model.
52-
Default is base. Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace
52+
Options: base, raw, Facenet, Facenet2018, VGGFace, VGGFace2, ArcFace (default is base)
5353
5454
Returns:
5555
result (dict): A dictionary containing verification results.
5656
57-
{
58-
"verified": True
59-
, "distance": 0.2563
60-
, "max_threshold_to_verify": 0.40
61-
, "model": "VGG-Face"
62-
, "similarity_metric": "cosine"
63-
, 'facial_areas': {
64-
'img1': {'x': 345, 'y': 211, 'w': 769, 'h': 769},
65-
'img2': {'x': 318, 'y': 534, 'w': 779, 'h': 779}
66-
}
67-
, "time": 2
68-
}
57+
- 'verified' (bool): Indicates whether the images represent the same person (True)
58+
or different persons (False).
59+
60+
- 'distance' (float): The distance measure between the face vectors.
61+
A lower distance indicates higher similarity.
62+
63+
- 'max_threshold_to_verify' (float): The maximum threshold used for verification.
64+
If the distance is below this threshold, the images are considered a match.
65+
66+
- 'model' (str): The chosen face recognition model.
67+
68+
- 'similarity_metric' (str): The chosen similarity metric for measuring distances.
69+
70+
- 'facial_areas' (dict): Rectangular regions of interest for faces in both images.
71+
- 'img1': {'x': int, 'y': int, 'w': int, 'h': int}
72+
Region of interest for the first image.
73+
- 'img2': {'x': int, 'y': int, 'w': int, 'h': int}
74+
Region of interest for the second image.
75+
76+
- 'time' (float): Time taken for the verification process in seconds.
6977
"""
7078

7179
tic = time.time()

0 commit comments

Comments
 (0)