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 = {}