From 0f0d3be9b94c16d718083e5203af689185498da0 Mon Sep 17 00:00:00 2001 From: Azure SDK for Python bot Date: Thu, 6 Jun 2019 05:30:10 +0000 Subject: [PATCH] Generated from d7666d6019f3a8bedf2596cea2995f4a50585f61 [FaceAPI] Remove all mentions of large groups in persongroup description --- .../cognitiveservices-face/package.json | 4 +- .../src/models/index.ts | 88 +++++++++++++ .../src/models/parameters.ts | 14 ++ .../src/operations/face.ts | 115 +++++++++++++---- .../src/operations/faceListOperations.ts | 113 +++++++++++++--- .../src/operations/largeFaceListOperations.ts | 121 +++++++++++++++--- .../operations/largePersonGroupOperations.ts | 31 +++-- .../src/operations/largePersonGroupPerson.ts | 100 +++++++++++++-- .../src/operations/personGroupOperations.ts | 30 +++-- .../src/operations/personGroupPerson.ts | 120 +++++++++++++++-- 10 files changed, 629 insertions(+), 107 deletions(-) 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",