diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/__init__.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/__init__.py
index 39c2758f7e00..eb488346f616 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/__init__.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/__init__.py
@@ -114,6 +114,7 @@
SnapshotObjectType,
OperationStatusType,
FaceAttributeType,
+ DetectionModel,
)
__all__ = [
@@ -175,4 +176,5 @@
'SnapshotObjectType',
'OperationStatusType',
'FaceAttributeType',
+ 'DetectionModel',
]
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/face_client_enums.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/face_client_enums.py
index 6eb661a0b2c3..b3fed2fd6d7f 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/face_client_enums.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/models/face_client_enums.py
@@ -123,3 +123,9 @@ class FaceAttributeType(str, Enum):
blur = "blur"
exposure = "exposure"
noise = "noise"
+
+
+class DetectionModel(str, Enum):
+
+ detection_01 = "detection_01"
+ detection_02 = "detection_02"
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_list_operations.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_list_operations.py
index 5e8c39a10751..9a7420dea8ff 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_list_operations.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_list_operations.py
@@ -397,7 +397,7 @@ def delete_face(
delete_face.metadata = {'url': '/facelists/{faceListId}/persistedfaces/{persistedFaceId}'}
def add_face_from_url(
- self, face_list_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config):
+ self, face_list_id, url, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, **operation_config):
"""Add a face to a specified face list, up to 1,000 faces.
To deal with an image contains multiple faces, input face can be
specified as an image with a targetFace rectangle. It returns a
@@ -425,6 +425,21 @@ def add_face_from_url(
head-pose, or large occlusions will cause failures.
* Adding/deleting faces to/from a same face list are processed
sequentially and to/from different face lists are in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [FaceList - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param face_list_id: Id referencing a particular face list.
:type face_list_id: str
@@ -439,6 +454,14 @@ def add_face_from_url(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -466,6 +489,8 @@ def add_face_from_url(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
@@ -497,10 +522,49 @@ def add_face_from_url(
add_face_from_url.metadata = {'url': '/facelists/{faceListId}/persistedfaces'}
def add_face_from_stream(
- self, face_list_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config):
- """Add a face to a face list. The input face is specified as an image with
- a targetFace rectangle. It returns a persistedFaceId representing the
- added face, and persistedFaceId will not expire.
+ self, face_list_id, image, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, callback=None, **operation_config):
+ """Add a face to a specified face list, up to 1,000 faces.
+
To deal with an image contains multiple faces, input face can be
+ specified as an image with a targetFace rectangle. It returns a
+ persistedFaceId representing the added face. No image will be stored.
+ Only the extracted face feature will be stored on server until
+ [FaceList - Delete
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395251)
+ or [FaceList -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f)
+ is called.
+
Note persistedFaceId is different from faceId generated by [Face
+ -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ * Higher face image quality means better detection and recognition
+ precision. Please consider high-quality faces: frontal, clear, and face
+ size is 200x200 pixels (100 pixels between eyes) or bigger.
+ * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
+ allowed image file size is from 1KB to 6MB.
+ * "targetFace" rectangle should contain one face. Zero or multiple
+ faces will be regarded as an error. If the provided "targetFace"
+ rectangle is not returned from [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236),
+ there’s no guarantee to detect and add the face successfully.
+ * Out of detectable face size (36x36 - 4096x4096 pixels), large
+ head-pose, or large occlusions will cause failures.
+ * Adding/deleting faces to/from a same face list are processed
+ sequentially and to/from different face lists are in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [FaceList - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param face_list_id: Id referencing a particular face list.
:type face_list_id: str
@@ -515,6 +579,14 @@ def add_face_from_stream(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -545,6 +617,8 @@ def add_face_from_stream(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_operations.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_operations.py
index 85f8696dbe58..6339928243a6 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_operations.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/face_operations.py
@@ -397,13 +397,9 @@ def verify_face_to_face(
verify_face_to_face.metadata = {'url': '/verify'}
def detect_with_url(
- self, url, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, recognition_model="recognition_01", return_recognition_model=False, custom_headers=None, raw=False, **operation_config):
+ self, url, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, recognition_model="recognition_01", return_recognition_model=False, detection_model="detection_01", custom_headers=None, raw=False, **operation_config):
"""Detect human faces in an image, return face rectangles, and optionally
with faceIds, landmarks, and attributes.
- * Optional parameters including faceId, landmarks, and attributes.
- Attributes include age, gender, headPose, smile, facialHair, glasses,
- emotion, hair, makeup, occlusion, accessories, blur, exposure and
- noise.
* No image will be stored. Only the extracted face feature will be
stored on server. The faceId is an identifier of the face feature and
will be used in [Face -
@@ -412,23 +408,40 @@ def detect_with_url(
Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
and [Face - Find
Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
- It will expire 24 hours after the detection call.
- * Higher face image quality means better detection and recognition
- precision. Please consider high-quality faces: frontal, clear, and face
- size is 200x200 pixels (100 pixels between eyes) or bigger.
+ The stored face feature(s) will expire and be deleted 24 hours after
+ the original detection call.
+ * Optional parameters include faceId, landmarks, and attributes.
+ Attributes include age, gender, headPose, smile, facialHair, glasses,
+ emotion, hair, makeup, occlusion, accessories, blur, exposure and
+ noise. Some of the results returned for specific attributes may not be
+ highly accurate.
* JPEG, PNG, GIF (the first frame), and BMP format are supported. The
allowed image file size is from 1KB to 6MB.
- * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If
- need to detect very small but clear faces, please try to enlarge the
- input image.
- * Up to 64 faces can be returned for an image. Faces are ranked by face
- rectangle size from large to small.
- * Face detector prefer frontal and near-frontal faces. There are cases
- that faces may not be detected, e.g. exceptionally large face angles
- (head-pose) or being occluded, or wrong image orientation.
- * Attributes (age, gender, headPose, smile, facialHair, glasses,
- emotion, hair, makeup, occlusion, accessories, blur, exposure and
- noise) may not be perfectly accurate.
+ * Up to 100 faces can be returned for an image. Faces are ranked by
+ face rectangle size from large to small.
+ * For optimal results when querying [Face -
+ Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239),
+ [Face -
+ Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
+ and [Face - Find
+ Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237)
+ ('returnFaceId' is true), please use faces that are: frontal, clear,
+ and with a minimum size of 200x200 pixels (100 pixels between eyes).
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |
* Different 'recognitionModel' values are provided. If follow-up
operations like Verify, Identify, Find Similar are needed, please
specify the recognition model with 'recognitionModel' parameter. The
@@ -437,7 +450,16 @@ def detect_with_url(
parameter. Once specified, the detected faceIds will be associated with
the specified recognition model. More details, please refer to [How to
specify a recognition
- model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model).
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'recognition_01': | The default recognition model for [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ All those faceIds created before 2019 March are bonded with this
+ recognition model. |
+ | 'recognition_02': | Recognition model released in 2019 March.
+ 'recognition_02' is recommended since its overall accuracy is improved
+ compared with 'recognition_01'. |.
:param url: Publicly reachable URL of an image
:type url: str
@@ -468,6 +490,14 @@ def detect_with_url(
:param return_recognition_model: A value indicating whether the
operation should return 'recognitionModel' in response.
:type return_recognition_model: bool
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -500,6 +530,8 @@ def detect_with_url(
query_parameters['recognitionModel'] = self._serialize.query("recognition_model", recognition_model, 'str')
if return_recognition_model is not None:
query_parameters['returnRecognitionModel'] = self._serialize.query("return_recognition_model", return_recognition_model, 'bool')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
@@ -604,9 +636,69 @@ def verify_face_to_person(
verify_face_to_person.metadata = {'url': '/verify'}
def detect_with_stream(
- self, image, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, recognition_model="recognition_01", return_recognition_model=False, custom_headers=None, raw=False, callback=None, **operation_config):
- """Detect human faces in an image and returns face locations, and
- optionally with faceIds, landmarks, and attributes.
+ self, image, return_face_id=True, return_face_landmarks=False, return_face_attributes=None, recognition_model="recognition_01", return_recognition_model=False, detection_model="detection_01", custom_headers=None, raw=False, callback=None, **operation_config):
+ """Detect human faces in an image, return face rectangles, and optionally
+ with faceIds, landmarks, and attributes.
+ * No image will be stored. Only the extracted face feature will be
+ stored on server. The faceId is an identifier of the face feature and
+ will be used in [Face -
+ Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239),
+ [Face -
+ Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
+ and [Face - Find
+ Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
+ The stored face feature(s) will expire and be deleted 24 hours after
+ the original detection call.
+ * Optional parameters include faceId, landmarks, and attributes.
+ Attributes include age, gender, headPose, smile, facialHair, glasses,
+ emotion, hair, makeup, occlusion, accessories, blur, exposure and
+ noise. Some of the results returned for specific attributes may not be
+ highly accurate.
+ * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
+ allowed image file size is from 1KB to 6MB.
+ * Up to 100 faces can be returned for an image. Faces are ranked by
+ face rectangle size from large to small.
+ * For optimal results when querying [Face -
+ Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239),
+ [Face -
+ Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
+ and [Face - Find
+ Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237)
+ ('returnFaceId' is true), please use faces that are: frontal, clear,
+ and with a minimum size of 200x200 pixels (100 pixels between eyes).
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |
+ * Different 'recognitionModel' values are provided. If follow-up
+ operations like Verify, Identify, Find Similar are needed, please
+ specify the recognition model with 'recognitionModel' parameter. The
+ default value for 'recognitionModel' is 'recognition_01', if latest
+ model needed, please explicitly specify the model you need in this
+ parameter. Once specified, the detected faceIds will be associated with
+ the specified recognition model. More details, please refer to [How to
+ specify a recognition
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'recognition_01': | The default recognition model for [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ All those faceIds created before 2019 March are bonded with this
+ recognition model. |
+ | 'recognition_02': | Recognition model released in 2019 March.
+ 'recognition_02' is recommended since its overall accuracy is improved
+ compared with 'recognition_01'. |.
:param image: An image stream.
:type image: Generator
@@ -637,6 +729,14 @@ def detect_with_stream(
:param return_recognition_model: A value indicating whether the
operation should return 'recognitionModel' in response.
:type return_recognition_model: bool
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -672,6 +772,8 @@ def detect_with_stream(
query_parameters['recognitionModel'] = self._serialize.query("recognition_model", recognition_model, 'str')
if return_recognition_model is not None:
query_parameters['returnRecognitionModel'] = self._serialize.query("return_recognition_model", return_recognition_model, 'bool')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_face_list_operations.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_face_list_operations.py
index 33a5970a3d9e..ba70e8c6b02f 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_face_list_operations.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_face_list_operations.py
@@ -639,7 +639,7 @@ def update_face(
update_face.metadata = {'url': '/largefacelists/{largeFaceListId}/persistedfaces/{persistedFaceId}'}
def add_face_from_url(
- self, large_face_list_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config):
+ self, large_face_list_id, url, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, **operation_config):
"""Add a face to a specified large face list, up to 1,000,000 faces.
To deal with an image contains multiple faces, input face can be
specified as an image with a targetFace rectangle. It returns a
@@ -667,6 +667,22 @@ def add_face_from_url(
head-pose, or large occlusions will cause failures.
* Adding/deleting faces to/from a same face list are processed
sequentially and to/from different face lists are in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [LargeFaceList -
+ Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |
Quota:
* Free-tier subscription quota: 1,000 faces per large face list.
* S0-tier subscription quota: 1,000,000 faces per large face list.
@@ -685,6 +701,14 @@ def add_face_from_url(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -712,6 +736,8 @@ def add_face_from_url(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
@@ -810,10 +836,53 @@ def list_faces(
list_faces.metadata = {'url': '/largefacelists/{largeFaceListId}/persistedfaces'}
def add_face_from_stream(
- self, large_face_list_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config):
- """Add a face to a large face list. The input face is specified as an
- image with a targetFace rectangle. It returns a persistedFaceId
- representing the added face, and persistedFaceId will not expire.
+ self, large_face_list_id, image, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, callback=None, **operation_config):
+ """Add a face to a specified large face list, up to 1,000,000 faces.
+
To deal with an image contains multiple faces, input face can be
+ specified as an image with a targetFace rectangle. It returns a
+ persistedFaceId representing the added face. No image will be stored.
+ Only the extracted face feature will be stored on server until
+ [LargeFaceList Face -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4)
+ or [LargeFaceList -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd)
+ is called.
+
Note persistedFaceId is different from faceId generated by [Face
+ -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ * Higher face image quality means better recognition precision. Please
+ consider high-quality faces: frontal, clear, and face size is 200x200
+ pixels (100 pixels between eyes) or bigger.
+ * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
+ allowed image file size is from 1KB to 6MB.
+ * "targetFace" rectangle should contain one face. Zero or multiple
+ faces will be regarded as an error. If the provided "targetFace"
+ rectangle is not returned from [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236),
+ there’s no guarantee to detect and add the face successfully.
+ * Out of detectable face size (36x36 - 4096x4096 pixels), large
+ head-pose, or large occlusions will cause failures.
+ * Adding/deleting faces to/from a same face list are processed
+ sequentially and to/from different face lists are in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [LargeFaceList -
+ Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |
+ Quota:
+ * Free-tier subscription quota: 1,000 faces per large face list.
+ * S0-tier subscription quota: 1,000,000 faces per large face list.
:param large_face_list_id: Id referencing a particular large face
list.
@@ -829,6 +898,14 @@ def add_face_from_stream(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -859,6 +936,8 @@ def add_face_from_stream(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_person_group_person_operations.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_person_group_person_operations.py
index 28f5aacf3b41..a61caa0bdd7b 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_person_group_person_operations.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/large_person_group_person_operations.py
@@ -509,7 +509,7 @@ def update_face(
update_face.metadata = {'url': '/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'}
def add_face_from_url(
- self, large_person_group_id, person_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config):
+ self, large_person_group_id, person_id, url, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, **operation_config):
"""Add a face to a person into a large person group for face
identification or verification. To deal with an image contains multiple
faces, input face can be specified as an image with a targetFace
@@ -541,6 +541,22 @@ def add_face_from_url(
* Adding/deleting faces to/from a same person will be processed
sequentially. Adding/deleting faces to/from different persons are
processed in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [LargePersonGroup
+ Person - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param large_person_group_id: Id referencing a particular large person
group.
@@ -558,6 +574,14 @@ def add_face_from_url(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -586,6 +610,8 @@ def add_face_from_url(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
@@ -617,9 +643,54 @@ def add_face_from_url(
add_face_from_url.metadata = {'url': '/largepersongroups/{largePersonGroupId}/persons/{personId}/persistedfaces'}
def add_face_from_stream(
- self, large_person_group_id, person_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config):
- """Add a representative face to a person for identification. The input
- face is specified as an image with a targetFace rectangle.
+ self, large_person_group_id, person_id, image, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, callback=None, **operation_config):
+ """Add a face to a person into a large person group for face
+ identification or verification. To deal with an image contains multiple
+ faces, input face can be specified as an image with a targetFace
+ rectangle. It returns a persistedFaceId representing the added face. No
+ image will be stored. Only the extracted face feature will be stored on
+ server until [LargePersonGroup PersonFace -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3),
+ [LargePersonGroup Person -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2)
+ or [LargePersonGroup -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f)
+ is called.
+
Note persistedFaceId is different from faceId generated by [Face
+ -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ * Higher face image quality means better recognition precision. Please
+ consider high-quality faces: frontal, clear, and face size is 200x200
+ pixels (100 pixels between eyes) or bigger.
+ * Each person entry can hold up to 248 faces.
+ * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
+ allowed image file size is from 1KB to 6MB.
+ * "targetFace" rectangle should contain one face. Zero or multiple
+ faces will be regarded as an error. If the provided "targetFace"
+ rectangle is not returned from [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236),
+ there’s no guarantee to detect and add the face successfully.
+ * Out of detectable face size (36x36 - 4096x4096 pixels), large
+ head-pose, or large occlusions will cause failures.
+ * Adding/deleting faces to/from a same person will be processed
+ sequentially. Adding/deleting faces to/from different persons are
+ processed in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [LargePersonGroup
+ Person - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/599adf2a3a7b9412a4d53f42).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param large_person_group_id: Id referencing a particular large person
group.
@@ -637,6 +708,14 @@ def add_face_from_stream(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -668,6 +747,8 @@ def add_face_from_stream(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
diff --git a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/person_group_person_operations.py b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/person_group_person_operations.py
index 401dcdc8dc65..8dc83c2c5860 100644
--- a/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/person_group_person_operations.py
+++ b/sdk/cognitiveservices/azure-cognitiveservices-vision-face/azure/cognitiveservices/vision/face/operations/person_group_person_operations.py
@@ -531,18 +531,18 @@ def update_face(
update_face.metadata = {'url': '/persongroups/{personGroupId}/persons/{personId}/persistedfaces/{persistedFaceId}'}
def add_face_from_url(
- self, person_group_id, person_id, url, user_data=None, target_face=None, custom_headers=None, raw=False, **operation_config):
- """Add a face to a person into a large person group for face
- identification or verification. To deal with an image contains multiple
- faces, input face can be specified as an image with a targetFace
- rectangle. It returns a persistedFaceId representing the added face. No
- image will be stored. Only the extracted face feature will be stored on
- server until [LargePersonGroup PersonFace -
- Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ae2966ac60f11b48b5aa3),
- [LargePersonGroup Person -
- Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2)
- or [LargePersonGroup -
- Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f)
+ self, person_group_id, person_id, url, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, **operation_config):
+ """Add a face to a person into a person group for face identification or
+ verification. To deal with an image contains multiple faces, input face
+ can be specified as an image with a targetFace rectangle. It returns a
+ persistedFaceId representing the added face. No image will be stored.
+ Only the extracted face feature will be stored on server until
+ [PersonGroup PersonFace -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e),
+ [PersonGroup Person -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d)
+ or [PersonGroup -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245)
is called.
Note persistedFaceId is different from faceId generated by [Face
-
@@ -563,6 +563,22 @@ def add_face_from_url(
* Adding/deleting faces to/from a same person will be processed
sequentially. Adding/deleting faces to/from different persons are
processed in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [PersonGroup Person
+ - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param person_group_id: Id referencing a particular person group.
:type person_group_id: str
@@ -579,6 +595,14 @@ def add_face_from_url(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -607,6 +631,8 @@ def add_face_from_url(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}
@@ -638,9 +664,54 @@ def add_face_from_url(
add_face_from_url.metadata = {'url': '/persongroups/{personGroupId}/persons/{personId}/persistedfaces'}
def add_face_from_stream(
- self, person_group_id, person_id, image, user_data=None, target_face=None, custom_headers=None, raw=False, callback=None, **operation_config):
- """Add a representative face to a person for identification. The input
- face is specified as an image with a targetFace rectangle.
+ self, person_group_id, person_id, image, user_data=None, target_face=None, detection_model="detection_01", custom_headers=None, raw=False, callback=None, **operation_config):
+ """Add a face to a person into a person group for face identification or
+ verification. To deal with an image contains multiple faces, input face
+ can be specified as an image with a targetFace rectangle. It returns a
+ persistedFaceId representing the added face. No image will be stored.
+ Only the extracted face feature will be stored on server until
+ [PersonGroup PersonFace -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523e),
+ [PersonGroup Person -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d)
+ or [PersonGroup -
+ Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245)
+ is called.
+
Note persistedFaceId is different from faceId generated by [Face
+ -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
+ * Higher face image quality means better recognition precision.
+ Please consider high-quality faces: frontal, clear, and face size is
+ 200x200 pixels (100 pixels between eyes) or bigger.
+ * Each person entry can hold up to 248 faces.
+ * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
+ allowed image file size is from 1KB to 6MB.
+ * "targetFace" rectangle should contain one face. Zero or multiple
+ faces will be regarded as an error. If the provided "targetFace"
+ rectangle is not returned from [Face -
+ Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236),
+ there’s no guarantee to detect and add the face successfully.
+ * Out of detectable face size (36x36 - 4096x4096 pixels), large
+ head-pose, or large occlusions will cause failures.
+ * Adding/deleting faces to/from a same person will be processed
+ sequentially. Adding/deleting faces to/from different persons are
+ processed in parallel.
+ * The minimum detectable face size is 36x36 pixels in an image no
+ larger than 1920x1080 pixels. Images with dimensions higher than
+ 1920x1080 pixels will need a proportionally larger minimum face size.
+ * Different 'detectionModel' values can be provided. To use and compare
+ different detection models, please refer to [How to specify a detection
+ model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
+ | Model | Recommended use-case(s) |
+ | ---------- | -------- |
+ | 'detection_01': | The default detection model for [PersonGroup Person
+ - Add
+ Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b).
+ Recommend for near frontal face detection. For scenarios with
+ exceptionally large angle (head-pose) faces, occluded faces or wrong
+ image orientation, the faces in such cases may not be detected. |
+ | 'detection_02': | Detection model released in 2019 May with improved
+ accuracy especially on small, side and blurry faces. |.
:param person_group_id: Id referencing a particular person group.
:type person_group_id: str
@@ -657,6 +728,14 @@ def add_face_from_stream(
image, targetFace is required to specify which face to add. No
targetFace means there is only one face detected in the entire image.
:type target_face: list[int]
+ :param detection_model: Name of detection model. Detection model is
+ used to detect faces in the submitted image. A detection model name
+ can be provided when performing Face - Detect or (Large)FaceList - Add
+ Face or (Large)PersonGroup - Add Face. The default value is
+ 'detection_01', if another model is needed, please explicitly specify
+ it. Possible values include: 'detection_01', 'detection_02'
+ :type detection_model: str or
+ ~azure.cognitiveservices.vision.face.models.DetectionModel
:param dict custom_headers: headers that will be added to the request
:param bool raw: returns the direct response alongside the
deserialized response
@@ -688,6 +767,8 @@ def add_face_from_stream(
query_parameters['userData'] = self._serialize.query("user_data", user_data, 'str', max_length=1024)
if target_face is not None:
query_parameters['targetFace'] = self._serialize.query("target_face", target_face, '[int]', div=',')
+ if detection_model is not None:
+ query_parameters['detectionModel'] = self._serialize.query("detection_model", detection_model, 'str')
# Construct headers
header_parameters = {}