diff --git a/sdk/cognitiveservices/cognitiveservices-face/package.json b/sdk/cognitiveservices/cognitiveservices-face/package.json
index a37121ff3dfa..1dd05df8d8f6 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/package.json
+++ b/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"
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/models/index.ts b/sdk/cognitiveservices/cognitiveservices-face/src/models/index.ts
index cf81a70fefd4..d8d005c03b11 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/models/index.ts
+++ b/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.
*/
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/models/parameters.ts b/sdk/cognitiveservices/cognitiveservices-face/src/models/parameters.ts
index 61b2aea41366..e2905f7425d2 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/models/parameters.ts
+++ b/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: {
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/face.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/face.ts
index dec44526182f..8f2eef4ba14f 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/face.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/face.ts
@@ -211,30 +211,42 @@ export class Face {
/**
* 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.
- * * 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,
@@ -242,6 +254,13 @@ export class Face {
* 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
@@ -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.
+ * * 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
@@ -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",
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/faceListOperations.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/faceListOperations.ts
index b7e010c9b2b9..eb70ea6bb372 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/faceListOperations.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/faceListOperations.ts
@@ -33,8 +33,9 @@ export class FaceListOperations {
* Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
*
After creation, user should use [FaceList - Add
* Face](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395250) to import the
- * faces. Faces are stored on server until [FaceList -
- * Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f) is called.
+ * faces. No image will be stored. Only the extracted face features are stored on server until
+ * [FaceList - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524f)
+ * is called.
*
Find Similar is used for scenario like finding celebrity-like faces, similar face
* filtering, or as a light way face identification. But if the actual use is to identify person,
* please use
@@ -44,12 +45,18 @@ export class FaceListOperations {
* Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
*
Please consider
* [LargeFaceList](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc)
- * when the face number is large. It can support up to 1,000,000 faces. 'recognitionModel' should
- * be specified to associate with this face list. The default value for 'recognitionModel' is
- * 'recognition_01', if the latest model needed, please explicitly specify the model you need in
- * this parameter. New faces that are added to an existing face list will use the recognition model
- * that's already associated with the collection. Existing face features in a face list can't be
- * updated to features extracted by another version of recognition model.
+ * when the face number is large. It can support up to 1,000,000 faces.
+ *
'recognitionModel' should be specified to associate with this face list. The default value
+ * for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
+ * specify the model you need in this parameter. New faces that are added to an existing face list
+ * will use the recognition model that's already associated with the collection. Existing face
+ * features in a face list can't be updated to features extracted by another version of recognition
+ * model.
+ * * 'recognition_01': The default recognition model for [FaceList-
+ * Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b). All those
+ * face lists 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 faceListId Id referencing a particular face list.
* @param [options] The optional parameters
* @returns Promise
@@ -133,8 +140,7 @@ export class FaceListOperations {
}
/**
- * Delete an existing face list according to faceListId. Persisted face images in the face list
- * will also be deleted.
+ * Delete a specified face list.
* @param faceListId Id referencing a particular face list.
* @param [options] The optional parameters
* @returns Promise
@@ -188,8 +194,9 @@ export class FaceListOperations {
}
/**
- * Delete an existing face from a face list (given by a persistedFaceId and a faceListId).
- * Persisted image related to the face will also be deleted.
+ * Delete a face from a face list by specified faceListId and persistedFaceId.
+ *
Adding/deleting faces to/from a same face list are processed sequentially and to/from
+ * different face lists are in parallel.
* @param faceListId Id referencing a particular face list.
* @param persistedFaceId Id referencing a particular persistedFaceId of an existing face.
* @param [options] The optional parameters
@@ -221,8 +228,42 @@ export class FaceListOperations {
}
/**
- * 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.
+ * 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 faceListId Id referencing a particular face list.
* @param url Publicly reachable URL of an image
* @param [options] The optional parameters
@@ -254,8 +295,42 @@ export class FaceListOperations {
}
/**
- * 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.
+ * 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 faceListId Id referencing a particular face list.
* @param image An image stream.
* @param [options] The optional parameters
@@ -451,7 +526,8 @@ const addFaceFromUrlOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: {
@@ -482,7 +558,8 @@ const addFaceFromStreamOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: "image",
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largeFaceListOperations.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largeFaceListOperations.ts
index e5b8a4d00f38..a5142b420b93 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largeFaceListOperations.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largeFaceListOperations.ts
@@ -35,9 +35,9 @@ export class LargeFaceListOperations {
* Add](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3) to import the
* faces and [LargeFaceList -
* Train](/docs/services/563879b61984550e40cbbe8d/operations/5a158422d2de3616c086f2d1) to make it
- * ready for [Face -
- * FindSimilar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). Faces
- * are stored on server until [LargeFaceList -
+ * ready for [Face - Find
+ * Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). No image
+ * will be stored. Only the extracted face features are stored on server until [LargeFaceList -
* Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) is called.
*
Find Similar is used for scenario like finding celebrity-like faces, similar face
* filtering, or as a light way face identification. But if the actual use is to identify person,
@@ -46,16 +46,21 @@ export class LargeFaceListOperations {
* [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d)
* and [Face -
* Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
- *
- * * Free-tier subscription quota: 64 large face lists.
- * * S0-tier subscription quota: 1,000,000 large face lists.
- *
- * 'recognitionModel' should be specified to associate with this large face list. The default value
- * for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
+ *
'recognitionModel' should be specified to associate with this large face list. The default
+ * value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
* specify the model you need in this parameter. New faces that are added to an existing large face
* list will use the recognition model that's already associated with the collection. Existing face
* features in a large face list can't be updated to features extracted by another version of
* recognition model.
+ * * 'recognition_01': The default recognition model for [LargeFaceList-
+ * Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc). All those
+ * large face lists 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'.
+ *
+ * Large face list quota:
+ * * Free-tier subscription quota: 64 large face lists.
+ * * S0-tier subscription quota: 1,000,000 large face lists.
* @param largeFaceListId Id referencing a particular large face list.
* @param [options] The optional parameters
* @returns Promise
@@ -139,8 +144,7 @@ export class LargeFaceListOperations {
}
/**
- * Delete an existing large face list according to faceListId. Persisted face images in the large
- * face list will also be deleted.
+ * Delete a specified large face list.
* @param largeFaceListId Id referencing a particular large face list.
* @param [options] The optional parameters
* @returns Promise
@@ -263,8 +267,9 @@ export class LargeFaceListOperations {
}
/**
- * Delete an existing face from a large face list (given by a persistedFaceId and a
- * largeFaceListId). Persisted image related to the face will also be deleted.
+ * Delete a face from a large face list by specified largeFaceListId and persistedFaceId.
+ *
Adding/deleting faces to/from a same large face list are processed sequentially and
+ * to/from different large face lists are in parallel.
* @param largeFaceListId Id referencing a particular large face list.
* @param persistedFaceId Id referencing a particular persistedFaceId of an existing face.
* @param [options] The optional parameters
@@ -361,9 +366,45 @@ export class LargeFaceListOperations {
}
/**
- * 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.
+ * 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 largeFaceListId Id referencing a particular large face list.
* @param url Publicly reachable URL of an image
* @param [options] The optional parameters
@@ -424,9 +465,45 @@ export class LargeFaceListOperations {
}
/**
- * 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.
+ * 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 largeFaceListId Id referencing a particular large face list.
* @param image An image stream.
* @param [options] The optional parameters
@@ -704,7 +781,8 @@ const addFaceFromUrlOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: {
@@ -768,7 +846,8 @@ const addFaceFromStreamOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: "image",
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupOperations.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupOperations.ts
index 695c31ac48fb..69e575519178 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupOperations.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupOperations.ts
@@ -29,28 +29,35 @@ export class LargePersonGroupOperations {
/**
* Create a new large person group with user-specified largePersonGroupId, name, an optional
* userData and recognitionModel.
- *
A large person group is the container of the uploaded person data, including face images
- * and face recognition feature, and up to 1,000,000 people.
+ *
A large person group is the container of the uploaded person data, including face
+ * recognition feature, and up to 1,000,000
+ * people.
*
After creation, use [LargePersonGroup Person -
* Create](/docs/services/563879b61984550e40cbbe8d/operations/599adcba3a7b9412a4d53f40) to add
* person into the group, and call [LargePersonGroup -
* Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4) to get this
* group ready for [Face -
* Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
- *
The person face, image, and userData will be stored on server until [LargePersonGroup
- * Person - Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or
+ *
No image will be stored. Only the person's extracted face features and userData will be
+ * stored on server until [LargePersonGroup Person -
+ * Delete](/docs/services/563879b61984550e40cbbe8d/operations/599ade5c6ac60f11b48b5aa2) or
* [LargePersonGroup -
* Delete](/docs/services/563879b61984550e40cbbe8d/operations/599adc216ac60f11b48b5a9f) is called.
- *
- * * Free-tier subscription quota: 1,000 large person groups.
- * * S0-tier subscription quota: 1,000,000 large person groups.
- *
- * 'recognitionModel' should be specified to associate with this large person group. The default
- * value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
- * specify the model you need in this parameter. New faces that are added to an existing large
- * person group will use the recognition model that's already associated with the collection.
+ *
'recognitionModel' should be specified to associate with this large person group. The
+ * default value for 'recognitionModel' is 'recognition_01', if the latest model needed, please
+ * explicitly specify the model you need in this parameter. New faces that are added to an existing
+ * large person group will use the recognition model that's already associated with the collection.
* Existing face features in a large person group can't be updated to features extracted by another
* version of recognition model.
+ * * 'recognition_01': The default recognition model for [LargePersonGroup -
+ * Create](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d). All those
+ * large person groups 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'.
+ *
+ * Large person group quota:
+ * * Free-tier subscription quota: 1,000 large person groups.
+ * * S0-tier subscription quota: 1,000,000 large person groups.
* @param largePersonGroupId Id referencing a particular large person group.
* @param [options] The optional parameters
* @returns Promise
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupPerson.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupPerson.ts
index c64fd464ee37..37131fa8303e 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupPerson.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/largePersonGroupPerson.ts
@@ -84,8 +84,8 @@ export class LargePersonGroupPerson {
}
/**
- * Delete an existing person from a large person group. All stored person data, and face features
- * in the person entry will be deleted.
+ * Delete an existing person from a large person group. The persistedFaceId, userData, person name
+ * and face feature in the person entry will all be deleted.
* @param largePersonGroupId Id referencing a particular large person group.
* @param personId Id referencing a particular person.
* @param [options] The optional parameters
@@ -117,7 +117,8 @@ export class LargePersonGroupPerson {
}
/**
- * Retrieve a person's information, including registered persisted faces, name and userData.
+ * Retrieve a person's name and userData, and the persisted faceIds representing the registered
+ * person face feature.
* @param largePersonGroupId Id referencing a particular large person group.
* @param personId Id referencing a particular person.
* @param [options] The optional parameters
@@ -181,7 +182,10 @@ export class LargePersonGroupPerson {
}
/**
- * Delete a face from a person. Relative feature for the persisted face will also be deleted.
+ * Delete a face from a person in a large person group by specified largePersonGroupId, personId
+ * and persistedFaceId.
+ *
Adding/deleting faces to/from a same person will be processed sequentially.
+ * Adding/deleting faces to/from different persons are processed in parallel.
* @param largePersonGroupId Id referencing a particular large person group.
* @param personId Id referencing a particular person.
* @param persistedFaceId Id referencing a particular persistedFaceId of an existing face.
@@ -290,8 +294,45 @@ export class LargePersonGroupPerson {
}
/**
- * Add a representative face to a person for identification. The input face is specified as an
- * image with a targetFace rectangle.
+ * 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 largePersonGroupId Id referencing a particular large person group.
* @param personId Id referencing a particular person.
* @param url Publicly reachable URL of an image
@@ -327,8 +368,45 @@ export class LargePersonGroupPerson {
}
/**
- * Add a representative face to a person for identification. The input face is specified as an
- * image with a targetFace rectangle.
+ * 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 largePersonGroupId Id referencing a particular large person group.
* @param personId Id referencing a particular person.
* @param image An image stream.
@@ -580,7 +658,8 @@ const addFaceFromUrlOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: {
@@ -612,7 +691,8 @@ const addFaceFromStreamOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: "image",
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupOperations.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupOperations.ts
index 55f3f0ee776e..d5fe4baf292c 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupOperations.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupOperations.ts
@@ -29,30 +29,36 @@ export class PersonGroupOperations {
/**
* Create a new person group with specified personGroupId, name, user-provided userData and
* recognitionModel.
- *
A person group is the container of the uploaded person data, including face images and
- * face recognition features.
+ *
A person group is the container of the uploaded person data, including face recognition
+ * features.
*
After creation, use [PersonGroup Person -
* Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c) to add
* persons into the group, and then call [PersonGroup -
* Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) to get this
* group ready for [Face -
* Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239).
- *
The person's face, image, and userData will be stored on server until [PersonGroup Person
- * - Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or
+ *
No image will be stored. Only the person's extracted face features and userData will be
+ * stored on server until [PersonGroup Person -
+ * Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523d) or
* [PersonGroup -
* Delete](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395245) is called.
- *
- * * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.
- * * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.
- * * to handle larger scale face identification problem, please consider using
- * [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d).
- *
- * 'recognitionModel' should be specified to associate with this person group. The default value
- * for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
+ *
'recognitionModel' should be specified to associate with this person group. The default
+ * value for 'recognitionModel' is 'recognition_01', if the latest model needed, please explicitly
* specify the model you need in this parameter. New faces that are added to an existing person
* group will use the recognition model that's already associated with the collection. Existing
* face features in a person group can't be updated to features extracted by another version of
* recognition model.
+ * * 'recognition_01': The default recognition model for [PersonGroup -
+ * Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244). All those
+ * person groups 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'.
+ *
+ * Person group quota:
+ * * Free-tier subscription quota: 1,000 person groups. Each holds up to 1,000 persons.
+ * * S0-tier subscription quota: 1,000,000 person groups. Each holds up to 10,000 persons.
+ * * to handle larger scale face identification problem, please consider using
+ * [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d).
* @param personGroupId Id referencing a particular person group.
* @param [options] The optional parameters
* @returns Promise
diff --git a/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupPerson.ts b/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupPerson.ts
index c6e94d3e6517..2be7156beef4 100644
--- a/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupPerson.ts
+++ b/sdk/cognitiveservices/cognitiveservices-face/src/operations/personGroupPerson.ts
@@ -84,8 +84,8 @@ export class PersonGroupPerson {
}
/**
- * Delete an existing person from a person group. All stored person data, and face features in the
- * person entry will be deleted.
+ * Delete an existing person from a person group. The persistedFaceId, userData, person name and
+ * face feature in the person entry will all be deleted.
* @param personGroupId Id referencing a particular person group.
* @param personId Id referencing a particular person.
* @param [options] The optional parameters
@@ -181,7 +181,10 @@ export class PersonGroupPerson {
}
/**
- * Delete a face from a person. Relative feature for the persisted face will also be deleted.
+ * Delete a face from a person in a person group by specified personGroupId, personId and
+ * persistedFaceId.
+ *
Adding/deleting faces to/from a same person will be processed sequentially.
+ * Adding/deleting faces to/from different persons are processed in parallel.
* @param personGroupId Id referencing a particular person group.
* @param personId Id referencing a particular person.
* @param persistedFaceId Id referencing a particular persistedFaceId of an existing face.
@@ -254,7 +257,30 @@ export class PersonGroupPerson {
}
/**
- * Update a person persisted face's userData field.
+ * 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.
* @param personGroupId Id referencing a particular person group.
* @param personId Id referencing a particular person.
* @param persistedFaceId Id referencing a particular persistedFaceId of an existing face.
@@ -290,8 +316,44 @@ export class PersonGroupPerson {
}
/**
- * Add a representative face to a person for identification. The input face is specified as an
- * image with a targetFace rectangle.
+ * 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 personGroupId Id referencing a particular person group.
* @param personId Id referencing a particular person.
* @param url Publicly reachable URL of an image
@@ -327,8 +389,44 @@ export class PersonGroupPerson {
}
/**
- * Add a representative face to a person for identification. The input face is specified as an
- * image with a targetFace rectangle.
+ * 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 personGroupId Id referencing a particular person group.
* @param personId Id referencing a particular person.
* @param image An image stream.
@@ -580,7 +678,8 @@ const addFaceFromUrlOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: {
@@ -612,7 +711,8 @@ const addFaceFromStreamOperationSpec: msRest.OperationSpec = {
],
queryParameters: [
Parameters.userData,
- Parameters.targetFace
+ Parameters.targetFace,
+ Parameters.detectionModel
],
requestBody: {
parameterPath: "image",