[AutoPR cognitiveservices/data-plane/Face] [FaceAPI] Add detection model argument on Detect and AddFace methods

sdk/cognitiveservices/cognitiveservices-face/package.json

@@ -4,7 +4,7 @@
   "description": "FaceClient Library with typescript type definitions for node.js and browser.",
   "version": "3.0.0",
   "dependencies": {
-    "@azure/ms-rest-js": "^1.6.0",
+    "@azure/ms-rest-js": "^1.8.1",
     "tslib": "^1.9.3"
   },
   "keywords": [
@@ -25,7 +25,7 @@
     "rollup-plugin-sourcemaps": "^0.4.2",
     "uglify-js": "^3.4.9"
   },
-  "homepage": "https://github.com/azure/azure-sdk-for-js/tree/master/sdk/cognitiveservices/cognitiveservices-face",
+  "homepage": "https://github.com/azure/azure-sdk-for-js",
   "repository": {
     "type": "git",
     "url": "https://github.com/azure/azure-sdk-for-js.git"

sdk/cognitiveservices/cognitiveservices-face/src/models/index.ts

@@ -923,6 +923,14 @@ export interface FaceDetectWithUrlOptionalParams extends msRest.RequestOptionsBa
    * value: false.
    */
   returnRecognitionModel?: boolean;
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -978,6 +986,14 @@ export interface FaceDetectWithStreamOptionalParams extends msRest.RequestOption
    * value: false.
    */
   returnRecognitionModel?: boolean;
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1047,6 +1063,14 @@ export interface PersonGroupPersonAddFaceFromUrlOptionalParams extends msRest.Re
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1064,6 +1088,14 @@ export interface PersonGroupPersonAddFaceFromStreamOptionalParams extends msRest
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1197,6 +1229,14 @@ export interface FaceListAddFaceFromUrlOptionalParams extends msRest.RequestOpti
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1214,6 +1254,14 @@ export interface FaceListAddFaceFromStreamOptionalParams extends msRest.RequestO
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1283,6 +1331,14 @@ export interface LargePersonGroupPersonAddFaceFromUrlOptionalParams extends msRe
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1300,6 +1356,14 @@ export interface LargePersonGroupPersonAddFaceFromStreamOptionalParams extends m
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1443,6 +1507,14 @@ export interface LargeFaceListAddFaceFromUrlOptionalParams extends msRest.Reques
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1474,6 +1546,14 @@ export interface LargeFaceListAddFaceFromStreamOptionalParams extends msRest.Req
    * there is only one face detected in the entire image.
    */
   targetFace?: number[];
+  /**
+   * 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'. Default value: 'detection_01'.
+   */
+  detectionModel?: DetectionModel;
 }
 
 /**
@@ -1668,6 +1748,14 @@ export type OperationStatusType = 'notstarted' | 'running' | 'succeeded' | 'fail
  */
 export type FaceAttributeType = 'age' | 'gender' | 'headPose' | 'smile' | 'facialHair' | 'glasses' | 'emotion' | 'hair' | 'makeup' | 'occlusion' | 'accessories' | 'blur' | 'exposure' | 'noise';
 
+/**
+ * Defines values for DetectionModel.
+ * Possible values include: 'detection_01', 'detection_02'
+ * @readonly
+ * @enum {string}
+ */
+export type DetectionModel = 'detection_01' | 'detection_02';
+
 /**
  * Contains response data for the findSimilar operation.
  */

sdk/cognitiveservices/cognitiveservices-face/src/models/parameters.ts

@@ -28,6 +28,20 @@ export const applyScope: msRest.OperationQueryParameter = {
   },
   collectionFormat: msRest.QueryCollectionFormat.Csv
 };
+export const detectionModel: msRest.OperationQueryParameter = {
+  parameterPath: [
+    "options",
+    "detectionModel"
+  ],
+  mapper: {
+    nullable: false,
+    serializedName: "detectionModel",
+    defaultValue: 'detection_01',
+    type: {
+      name: "String"
+    }
+  }
+};
 export const endpoint: msRest.OperationURLParameter = {
   parameterPath: "endpoint",
   mapper: {

sdk/cognitiveservices/cognitiveservices-face/src/operations/face.ts

@@ -211,37 +211,56 @@ export class Face {
   /**
    * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks,
    * and attributes.<br />
-   * * Optional parameters including faceId, landmarks, and attributes. Attributes include age,
-   * gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, occlusion, accessories,
-   * blur, exposure and noise.
-   * * The extracted face feature, instead of the actual image, will be stored on server. The faceId
+   * * 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). 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.
+   * - 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.
-   * * 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
+   * * Up to 100 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. HeadPose's
-   * pitch value is a reserved field and will always return 0.
+   * * 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 url Publicly reachable URL of an image
    * @param [options] The optional parameters
    * @returns Promise<Models.FaceDetectWithUrlResponse>
@@ -304,8 +323,58 @@ export class Face {
   }
 
   /**
-   * Detect human faces in an image and returns face locations, and optionally with faceIds,
-   * landmarks, and attributes.
+   * Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks,
+   * and attributes.<br />
+   * * 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.
    * @param [options] The optional parameters
    * @returns Promise<Models.FaceDetectWithStreamResponse>
@@ -509,7 +578,8 @@ const detectWithUrlOperationSpec: msRest.OperationSpec = {
     Parameters.returnFaceLandmarks,
     Parameters.returnFaceAttributes,
     Parameters.recognitionModel,
-    Parameters.returnRecognitionModel
+    Parameters.returnRecognitionModel,
+    Parameters.detectionModel
   ],
   requestBody: {
     parameterPath: {
@@ -588,7 +658,8 @@ const detectWithStreamOperationSpec: msRest.OperationSpec = {
     Parameters.returnFaceLandmarks,
     Parameters.returnFaceAttributes,
     Parameters.recognitionModel,
-    Parameters.returnRecognitionModel
+    Parameters.returnRecognitionModel,
+    Parameters.detectionModel
   ],
   requestBody: {
     parameterPath: "image",