This repository has been archived by the owner on Nov 8, 2021. It is now read-only.
/
face.py
190 lines (163 loc) · 7.37 KB
/
face.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
#!/usr/bin/env python
# -*- coding: utf-8 -*-
"""
File: face.py
Description: Face section of the Cognitive Face API.
"""
from . import util
def detect(image, face_id=True, landmarks=False, attributes=''):
"""Detect human faces in an image and returns face locations, and
optionally with `face_id`s, landmarks, and attributes.
Args:
image: A URL or a file path or a file-like object represents an image.
face_id: [Optional] Return faceIds of the detected faces or not. The
default value is true.
landmarks: [Optional] Return face landmarks of the detected faces or
not. The default value is false.
attributes: [Optional] Analyze and return the one or more specified
face attributes in the comma-separated string like
"age,gender". Supported face attributes include age, gender,
headPose, smile, facialHair, glasses, emotion, makeup, accessories,
occlusion, blur, exposure, noise. Note that each face attribute
analysis has additional computational and time cost.
Returns:
An array of face entries ranked by face rectangle size in descending
order. An empty response indicates no faces detected. A face entry may
contain the corresponding values depending on input parameters.
"""
url = 'detect'
headers, data, json = util.parse_image(image)
params = {
'returnFaceId': face_id and 'true' or 'false',
'returnFaceLandmarks': landmarks and 'true' or 'false',
'returnFaceAttributes': attributes,
}
return util.request(
'POST', url, headers=headers, params=params, json=json, data=data)
def find_similars(face_id,
face_list_id=None,
large_face_list_id=None,
face_ids=None,
max_candidates_return=20,
mode='matchPerson'):
"""Given query face's `face_id`, to search the similar-looking faces from a
`face_id` array, a `face_list_id` or a `large_face_list_id`.
Parameter `large_face_list_id`, `face_list_id` and `face_ids` should not be
provided at the same time.
Args:
face_id: `face_id` of the query face. User needs to call `face.detect`
first to get a valid `face_id`. Note that this `face_id` is not
persisted and will expire in 24 hours after the detection call.
face_list_id: An existing user-specified unique candidate face list,
created in `face_list.create`. Face list contains a set of
`persisted_face_ids` which are persisted and will never expire.
large_face_list_id: An existing user-specified unique candidate face
list, created in `large_face_list.create`. Large Face list contains
a set of `persisted_face_ids` which are persisted and will never
expire.
face_ids: An array of candidate `face_id`s. All of them are created by
`face.detect` and the `face_id`s will expire in 24 hours after the
detection call. The number of `face_id`s is limited to 1000.
max_candidates_return: Optional parameter. The number of top similar
faces returned. The valid range is [1, 1000]. It defaults to 20.
mode: Optional parameter. Similar face searching mode. It can be
"matchPerson" or "matchFace". It defaults to "matchPerson".
Returns:
An array of the most similar faces represented in `face_id` if the
input parameter is `face_ids` or `persisted_face_id` if the input
parameter is `face_list_id` or `large_face_list_id`.
"""
url = 'findsimilars'
json = {
'faceId': face_id,
'faceListId': face_list_id,
'largeFaceListId': large_face_list_id,
'faceIds': face_ids,
'maxNumOfCandidatesReturned': max_candidates_return,
'mode': mode,
}
return util.request('POST', url, json=json)
def group(face_ids):
"""Divide candidate faces into groups based on face similarity.
Args:
face_ids: An array of candidate `face_id`s created by `face.detect`.
The maximum is 1000 faces.
Returns:
one or more groups of similar faces (ranked by group size) and a
messyGroup.
"""
url = 'group'
json = {
'faceIds': face_ids,
}
return util.request('POST', url, json=json)
def identify(face_ids,
person_group_id=None,
large_person_group_id=None,
max_candidates_return=1,
threshold=None):
"""Identify unknown faces from a person group or a large person group.
Args:
face_ids: An array of query `face_id`s, created by the `face.detect`.
Each of the faces are identified independently. The valid number of
`face_ids` is between [1, 10].
person_group_id: `person_group_id` of the target person group, created
by `person_group.create`.
large_person_group_id: `large_person_group_id` of the target large
person group, createdJ by `large_person_group.create`.
max_candidates_return: Optional parameter. The range of
`max_candidates_return` is between 1 and 5 (default is 1).
threshold: Optional parameter. Confidence threshold of identification,
used to judge whether one face belongs to one person. The range of
confidence threshold is [0, 1] (default specified by algorithm).
Returns:
The identified candidate person(s) for each query face(s).
"""
url = 'identify'
json = {
'personGroupId': person_group_id,
'largePersonGroupId': large_person_group_id,
'faceIds': face_ids,
'maxNumOfCandidatesReturned': max_candidates_return,
'confidenceThreshold': threshold,
}
return util.request('POST', url, json=json)
def verify(face_id,
another_face_id=None,
person_group_id=None,
large_person_group_id=None,
person_id=None):
"""Verify whether two faces belong to a same person or whether one face
belongs to a person.
For face to face verification, only `face_id` and `another_face_id` is
necessary. For face to person verification, only `face_id`,
`person_group_id` (or `large_person_group_id`) and `person_id` is needed.
Args:
face_id: `face_id` of one face, comes from `face.detect`.
another_face_id: `face_id` of another face, comes from `face.detect`.
person_group_id: Using existing `person_group_id` and `person_id` for
fast loading a specified person. `person_group_id` is created in
`person_group.create`.
large_person_group_id: Using existing `large_person_group_id` and
`person_id` for fast loading a specified person.
`large_person_group_id` is created in `large_person_group.create`.
person_id: Specify a certain person in a person group. `person_id` is
created in `person.create`.
Returns:
The verification result.
"""
url = 'verify'
json = {}
if another_face_id:
json.update({
'faceId1': face_id,
'faceId2': another_face_id,
})
else:
json.update({
'faceId': face_id,
'personGroupId': person_group_id,
'largePersonGroupId': large_person_group_id,
'personId': person_id,
})
return util.request('POST', url, json=json)