[AutoPR cognitiveservices/data-plane/Face] [FaceAPI] Add detection mo…

…del argument on Detect and AddFace methods (#5667)

* Generated from 1d8183de7f54b28cda9df52c1d35e6484d49acac

[FaceAPI] Add detection model argument on Detect and AddFace methods

* Generated from 4ef1c813ae58c6edbad72d07f42a57db72db5508

Update detect and detection model-related descriptions

* Generated from 3445d5ce23ebb7d0321ba0a7991075d735fa3678

[FaceAPI] Amend DetectionModel parameter description

* Generated from 7c460c476831442f5ada9fc57e8892f61bff939e

[FaceAPI] Make Add Faces description consistent accross multiple calls

* Generated from 11957f52387ddc031a08403fcbb35bf09195ca95

[FaceAPI] Correct description of PersonGroup Person - Add Face

* Generated from d7666d6019f3a8bedf2596cea2995f4a50585f61

[FaceAPI] Remove all mentions of large groups in persongroup description

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',
 ]

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"

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.
         <br /> 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.
+        <br /> 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.
+        <br /> 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 = {}