diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceClient.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceClient.cs index 95fe7f33e869..2bc145cada1d 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceClient.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceClient.cs @@ -90,6 +90,19 @@ public partial class FaceClient : ServiceClient, IFaceClient /// public virtual ISnapshotOperations Snapshot { get; private set; } + /// + /// Initializes a new instance of the FaceClient class. + /// + /// + /// HttpClient to be used + /// + /// + /// True: will dispose the provided httpClient on calling FaceClient.Dispose(). False: will not dispose provided httpClient + protected FaceClient(HttpClient httpClient, bool disposeHttpClient) : base(httpClient, disposeHttpClient) + { + Initialize(); + } + /// /// Initializes a new instance of the FaceClient class. /// @@ -140,6 +153,33 @@ public FaceClient(ServiceClientCredentials credentials, params DelegatingHandler } } + /// + /// Initializes a new instance of the FaceClient class. + /// + /// + /// Required. Subscription credentials which uniquely identify client subscription. + /// + /// + /// HttpClient to be used + /// + /// + /// True: will dispose the provided httpClient on calling FaceClient.Dispose(). False: will not dispose provided httpClient + /// + /// Thrown when a required parameter is null + /// + public FaceClient(ServiceClientCredentials credentials, HttpClient httpClient, bool disposeHttpClient) : this(httpClient, disposeHttpClient) + { + if (credentials == null) + { + throw new System.ArgumentNullException("credentials"); + } + Credentials = credentials; + if (Credentials != null) + { + Credentials.InitializeServiceClient(this); + } + } + /// /// Initializes a new instance of the FaceClient class. /// diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperations.cs index a39b0a3657c2..72b4248b8f88 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperations.cs @@ -51,8 +51,36 @@ public FaceListOperations(FaceClient client) public FaceClient Client { get; private set; } /// - /// Create an empty face list. Up to 64 face lists are allowed to exist in one + /// Create an empty face list with user-specified faceListId, name, an optional + /// userData and recognitionModel. Up to 64 face lists are allowed in one /// subscription. + /// <br /> Face list is a list of faces, up to 1,000 faces, and used by + /// [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> 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. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> 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. + /// /// /// /// Id referencing a particular face list. @@ -63,6 +91,9 @@ public FaceListOperations(FaceClient client) /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// Headers that will be added to request. /// @@ -81,7 +112,7 @@ public FaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task CreateWithHttpMessagesAsync(string faceListId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task CreateWithHttpMessagesAsync(string faceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -116,11 +147,12 @@ public FaceListOperations(FaceClient client) throw new ValidationException(ValidationRules.MaxLength, "userData", 16384); } } - NameAndUserDataContract body = new NameAndUserDataContract(); - if (name != null || userData != null) + MetaDataContract body = new MetaDataContract(); + if (name != null || userData != null || recognitionModel != null) { body.Name = name; body.UserData = userData; + body.RecognitionModel = recognitionModel; } // Tracing bool _shouldTrace = ServiceClientTracing.IsEnabled; @@ -228,11 +260,17 @@ public FaceListOperations(FaceClient client) } /// - /// Retrieve a face list's information. + /// Retrieve a face list’s faceListId, name, userData, recognitionModel and + /// faces in the face list. + /// /// /// /// Id referencing a particular face list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -254,7 +292,7 @@ public FaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task> GetWithHttpMessagesAsync(string faceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task> GetWithHttpMessagesAsync(string faceListId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -283,6 +321,7 @@ public FaceListOperations(FaceClient client) _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("faceListId", faceListId); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "Get", tracingParameters); } @@ -291,6 +330,15 @@ public FaceListOperations(FaceClient client) var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "facelists/{faceListId}"; _url = _url.Replace("{Endpoint}", Client.Endpoint); _url = _url.Replace("{faceListId}", System.Uri.EscapeDataString(faceListId)); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; @@ -712,9 +760,16 @@ public FaceListOperations(FaceClient client) } /// - /// Retrieve information about all existing face lists. Only faceListId, name - /// and userData will be returned. + /// List face lists’ faceListId, name, userData and recognitionModel. <br + /// /> + /// To get face information inside faceList use [FaceList - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c) + /// /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -736,7 +791,7 @@ public FaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> ListWithHttpMessagesAsync(Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> ListWithHttpMessagesAsync(bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -749,6 +804,7 @@ public FaceListOperations(FaceClient client) { _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "List", tracingParameters); } @@ -756,6 +812,15 @@ public FaceListOperations(FaceClient client) var _baseUrl = Client.BaseUri; var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "facelists"; _url = _url.Replace("{Endpoint}", Client.Endpoint); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperationsExtensions.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperationsExtensions.cs index 6b29ae8ced98..5ad6adcdd472 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperationsExtensions.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceListOperationsExtensions.cs @@ -23,8 +23,36 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public static partial class FaceListOperationsExtensions { /// - /// Create an empty face list. Up to 64 face lists are allowed to exist in one + /// Create an empty face list with user-specified faceListId, name, an optional + /// userData and recognitionModel. Up to 64 face lists are allowed in one /// subscription. + /// <br /> Face list is a list of faces, up to 1,000 faces, and used by + /// [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> 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. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> 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. + /// /// /// /// The operations group for this extension method. @@ -38,16 +66,21 @@ public static partial class FaceListOperationsExtensions /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The cancellation token. /// - public static async Task CreateAsync(this IFaceListOperations operations, string faceListId, string name = default(string), string userData = default(string), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task CreateAsync(this IFaceListOperations operations, string faceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), CancellationToken cancellationToken = default(CancellationToken)) { - (await operations.CreateWithHttpMessagesAsync(faceListId, name, userData, null, cancellationToken).ConfigureAwait(false)).Dispose(); + (await operations.CreateWithHttpMessagesAsync(faceListId, name, userData, recognitionModel, null, cancellationToken).ConfigureAwait(false)).Dispose(); } /// - /// Retrieve a face list's information. + /// Retrieve a face list’s faceListId, name, userData, recognitionModel and + /// faces in the face list. + /// /// /// /// The operations group for this extension method. @@ -55,12 +88,16 @@ public static partial class FaceListOperationsExtensions /// /// Id referencing a particular face list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task GetAsync(this IFaceListOperations operations, string faceListId, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task GetAsync(this IFaceListOperations operations, string faceListId, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.GetWithHttpMessagesAsync(faceListId, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.GetWithHttpMessagesAsync(faceListId, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } @@ -108,18 +145,25 @@ public static partial class FaceListOperationsExtensions } /// - /// Retrieve information about all existing face lists. Only faceListId, name - /// and userData will be returned. + /// List face lists’ faceListId, name, userData and recognitionModel. <br + /// /> + /// To get face information inside faceList use [FaceList - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c) + /// /// /// /// The operations group for this extension method. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> ListAsync(this IFaceListOperations operations, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> ListAsync(this IFaceListOperations operations, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.ListWithHttpMessagesAsync(null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.ListWithHttpMessagesAsync(returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperations.cs index b7f27dd6c6be..259a3a56ee99 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperations.cs @@ -51,8 +51,31 @@ public FaceOperations(FaceClient client) public FaceClient Client { get; private set; } /// - /// Given query face's faceId, find the similar-looking faces from a faceId - /// array, a face list or a large face list. + /// Given query face's faceId, to search the similar-looking faces from a + /// faceId array, a face list or a large face list. faceId array contains the + /// faces created by [Face - + /// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), + /// which will expire 24 hours after creation. A "faceListId" is created by + /// [FaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) + /// containing persistedFaceIds that will not expire. And a "largeFaceListId" + /// is created by [LargeFaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) + /// containing persistedFaceIds that will also not expire. Depending on the + /// input the returned similar faces list contains faceIds or persistedFaceIds + /// ranked by similarity. + /// <br/>Find similar has two working modes, "matchPerson" and + /// "matchFace". "matchPerson" is the default mode that it tries to find faces + /// of the same person as possible by using internal same-person thresholds. It + /// is useful to find a known person's other photos. Note that an empty list + /// will be returned if no faces pass the internal thresholds. "matchFace" mode + /// ignores same-person thresholds and returns ranked similar faces anyway, + /// even the similarity is low. It can be used in the cases like searching + /// celebrity-looking faces. + /// <br/>The 'recognitionModel' associated with the query face's faceId + /// should be the same as the 'recognitionModel' used by the target faceId + /// array, face list or large face list. + /// /// /// /// FaceId of the query face. User needs to call Face - Detect first to get a @@ -280,7 +303,22 @@ public FaceOperations(FaceClient client) } /// - /// Divide candidate faces into groups based on face similarity. + /// Divide candidate faces into groups based on face similarity.<br /> + /// * The output is one or more disjointed face groups and a messyGroup. A face + /// group contains faces that have similar looking, often of the same person. + /// Face groups are ranked by group size, i.e. number of faces. Notice that + /// faces belonging to a same person might be split into several groups in the + /// result. + /// * MessyGroup is a special face group containing faces that cannot find any + /// similar counterpart face from original faces. The messyGroup will not + /// appear in the result if all faces found their counterparts. + /// * Group API needs at least 2 candidate faces and 1000 at most. We suggest + /// to try [Face - + /// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) + /// when you only have 2 candidate faces. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same. + /// /// /// /// Array of candidate faceId created by Face - Detect. The maximum is 1000 @@ -453,6 +491,36 @@ public FaceOperations(FaceClient client) /// /// 1-to-many identification to find the closest matches of the specific query /// person face from a person group or large person group. + /// <br/> For each face in the faceIds array, Face Identify will compute + /// similarities between the query face and all the faces in the person group + /// (given by personGroupId) or large person group (given by + /// largePersonGroupId), and return candidate person(s) for that face ranked by + /// similarity confidence. The person group/large person group should be + /// trained to make it ready for identification. See more in [PersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) + /// and [LargePersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + /// <br/> + /// + /// Remarks:<br /> + /// * The algorithm allows more than one face to be identified independently at + /// the same request, but no more than 10 faces. + /// * Each person in the person group/large person group could have more than + /// one face, but no more than 248 faces. + /// * Higher face image quality means better identification precision. Please + /// consider high-quality faces: frontal, clear, and face size is 200x200 + /// pixels (100 pixels between eyes) or bigger. + /// * Number of candidates returned is restricted by maxNumOfCandidatesReturned + /// and confidenceThreshold. If no person is identified, the returned + /// candidates will be an empty array. + /// * Try [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) + /// when you need to find similar faces from a face list/large face list + /// instead of a person group/large person group. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same as the 'recognitionModel' used by the target person group or large + /// person group. + /// /// /// /// Array of query faces faceIds, created by the Face - Detect. Each of the @@ -678,6 +746,17 @@ public FaceOperations(FaceClient client) /// /// Verify whether two faces belong to a same person or whether one face /// belongs to a person. + /// <br/> + /// Remarks:<br /> + /// * Higher face image quality means better identification precision. Please + /// consider high-quality faces: frontal, clear, and face size is 200x200 + /// pixels (100 pixels between eyes) or bigger. + /// * For the scenarios that are sensitive to accuracy please make your own + /// judgment. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same as the 'recognitionModel' used by the target face, person group or + /// large person group. + /// /// /// /// FaceId of the first face, comes from Face - Detect @@ -837,8 +916,46 @@ public FaceOperations(FaceClient client) } /// - /// Detect human faces in an image and returns face locations, and optionally - /// with faceIds, landmarks, and attributes. + /// Detect human faces in an image, return face rectangles, and optionally with + /// faceIds, landmarks, and attributes.<br /> + /// * 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 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. + /// * JPEG, PNG, GIF (the first frame), and BMP format are supported. The + /// allowed image file size is from 1KB to 6MB. + /// * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need + /// to detect very small but clear faces, please try to enlarge the input + /// image. + /// * Up to 64 faces can be returned for an image. Faces are ranked by face + /// rectangle size from large to small. + /// * Face detector prefer frontal and near-frontal faces. There are cases that + /// faces may not be detected, e.g. exceptionally large face angles (head-pose) + /// or being occluded, or wrong image orientation. + /// * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, + /// hair, makeup, occlusion, accessories, blur, exposure and noise) may not be + /// perfectly accurate. HeadPose's pitch value is a reserved field and will + /// always return 0. + /// * 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) + /// /// /// /// Publicly reachable URL of an image @@ -858,6 +975,19 @@ public FaceOperations(FaceClient client) /// and emotion. Note that each face attribute analysis has additional /// computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face features + /// are extracted and associated with detected faceIds, (Large)FaceList or + /// (Large)PersonGroup. A recognition model name can be provided when + /// performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup + /// - Create. The default value is 'recognition_01', if latest model needed, + /// please explicitly specify the model you need. Possible values include: + /// 'recognition_01', 'recognition_02' + /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -879,7 +1009,7 @@ public FaceOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> DetectWithUrlWithHttpMessagesAsync(string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> DetectWithUrlWithHttpMessagesAsync(string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -904,6 +1034,8 @@ public FaceOperations(FaceClient client) tracingParameters.Add("returnFaceId", returnFaceId); tracingParameters.Add("returnFaceLandmarks", returnFaceLandmarks); tracingParameters.Add("returnFaceAttributes", returnFaceAttributes); + tracingParameters.Add("recognitionModel", recognitionModel); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("imageUrl", imageUrl); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "DetectWithUrl", tracingParameters); @@ -925,6 +1057,14 @@ public FaceOperations(FaceClient client) { _queryParameters.Add(string.Format("returnFaceAttributes={0}", System.Uri.EscapeDataString(string.Join(",", returnFaceAttributes)))); } + if (recognitionModel != null) + { + _queryParameters.Add(string.Format("recognitionModel={0}", System.Uri.EscapeDataString(recognitionModel))); + } + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } if (_queryParameters.Count > 0) { _url += "?" + string.Join("&", _queryParameters); @@ -1259,6 +1399,19 @@ public FaceOperations(FaceClient client) /// and emotion. Note that each face attribute analysis has additional /// computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face features + /// are extracted and associated with detected faceIds, (Large)FaceList or + /// (Large)PersonGroup. A recognition model name can be provided when + /// performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup + /// - Create. The default value is 'recognition_01', if latest model needed, + /// please explicitly specify the model you need. Possible values include: + /// 'recognition_01', 'recognition_02' + /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -1280,7 +1433,7 @@ public FaceOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> DetectWithStreamWithHttpMessagesAsync(Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> DetectWithStreamWithHttpMessagesAsync(Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -1301,6 +1454,8 @@ public FaceOperations(FaceClient client) tracingParameters.Add("returnFaceLandmarks", returnFaceLandmarks); tracingParameters.Add("returnFaceAttributes", returnFaceAttributes); tracingParameters.Add("image", image); + tracingParameters.Add("recognitionModel", recognitionModel); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "DetectWithStream", tracingParameters); } @@ -1321,6 +1476,14 @@ public FaceOperations(FaceClient client) { _queryParameters.Add(string.Format("returnFaceAttributes={0}", System.Uri.EscapeDataString(string.Join(",", returnFaceAttributes)))); } + if (recognitionModel != null) + { + _queryParameters.Add(string.Format("recognitionModel={0}", System.Uri.EscapeDataString(recognitionModel))); + } + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } if (_queryParameters.Count > 0) { _url += "?" + string.Join("&", _queryParameters); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperationsExtensions.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperationsExtensions.cs index 7e205915d035..fc7d8ecaebfe 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperationsExtensions.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/FaceOperationsExtensions.cs @@ -23,8 +23,31 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public static partial class FaceOperationsExtensions { /// - /// Given query face's faceId, find the similar-looking faces from a faceId - /// array, a face list or a large face list. + /// Given query face's faceId, to search the similar-looking faces from a + /// faceId array, a face list or a large face list. faceId array contains the + /// faces created by [Face - + /// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), + /// which will expire 24 hours after creation. A "faceListId" is created by + /// [FaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) + /// containing persistedFaceIds that will not expire. And a "largeFaceListId" + /// is created by [LargeFaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) + /// containing persistedFaceIds that will also not expire. Depending on the + /// input the returned similar faces list contains faceIds or persistedFaceIds + /// ranked by similarity. + /// <br/>Find similar has two working modes, "matchPerson" and + /// "matchFace". "matchPerson" is the default mode that it tries to find faces + /// of the same person as possible by using internal same-person thresholds. It + /// is useful to find a known person's other photos. Note that an empty list + /// will be returned if no faces pass the internal thresholds. "matchFace" mode + /// ignores same-person thresholds and returns ranked similar faces anyway, + /// even the similarity is low. It can be used in the cases like searching + /// celebrity-looking faces. + /// <br/>The 'recognitionModel' associated with the query face's faceId + /// should be the same as the 'recognitionModel' used by the target faceId + /// array, face list or large face list. + /// /// /// /// The operations group for this extension method. @@ -71,7 +94,22 @@ public static partial class FaceOperationsExtensions } /// - /// Divide candidate faces into groups based on face similarity. + /// Divide candidate faces into groups based on face similarity.<br /> + /// * The output is one or more disjointed face groups and a messyGroup. A face + /// group contains faces that have similar looking, often of the same person. + /// Face groups are ranked by group size, i.e. number of faces. Notice that + /// faces belonging to a same person might be split into several groups in the + /// result. + /// * MessyGroup is a special face group containing faces that cannot find any + /// similar counterpart face from original faces. The messyGroup will not + /// appear in the result if all faces found their counterparts. + /// * Group API needs at least 2 candidate faces and 1000 at most. We suggest + /// to try [Face - + /// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) + /// when you only have 2 candidate faces. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same. + /// /// /// /// The operations group for this extension method. @@ -94,6 +132,36 @@ public static partial class FaceOperationsExtensions /// /// 1-to-many identification to find the closest matches of the specific query /// person face from a person group or large person group. + /// <br/> For each face in the faceIds array, Face Identify will compute + /// similarities between the query face and all the faces in the person group + /// (given by personGroupId) or large person group (given by + /// largePersonGroupId), and return candidate person(s) for that face ranked by + /// similarity confidence. The person group/large person group should be + /// trained to make it ready for identification. See more in [PersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) + /// and [LargePersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + /// <br/> + /// + /// Remarks:<br /> + /// * The algorithm allows more than one face to be identified independently at + /// the same request, but no more than 10 faces. + /// * Each person in the person group/large person group could have more than + /// one face, but no more than 248 faces. + /// * Higher face image quality means better identification precision. Please + /// consider high-quality faces: frontal, clear, and face size is 200x200 + /// pixels (100 pixels between eyes) or bigger. + /// * Number of candidates returned is restricted by maxNumOfCandidatesReturned + /// and confidenceThreshold. If no person is identified, the returned + /// candidates will be an empty array. + /// * Try [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) + /// when you need to find similar faces from a face list/large face list + /// instead of a person group/large person group. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same as the 'recognitionModel' used by the target person group or large + /// person group. + /// /// /// /// The operations group for this extension method. @@ -135,6 +203,17 @@ public static partial class FaceOperationsExtensions /// /// Verify whether two faces belong to a same person or whether one face /// belongs to a person. + /// <br/> + /// Remarks:<br /> + /// * Higher face image quality means better identification precision. Please + /// consider high-quality faces: frontal, clear, and face size is 200x200 + /// pixels (100 pixels between eyes) or bigger. + /// * For the scenarios that are sensitive to accuracy please make your own + /// judgment. + /// * The 'recognitionModel' associated with the query faces' faceIds should be + /// the same as the 'recognitionModel' used by the target face, person group or + /// large person group. + /// /// /// /// The operations group for this extension method. @@ -157,8 +236,46 @@ public static partial class FaceOperationsExtensions } /// - /// Detect human faces in an image and returns face locations, and optionally - /// with faceIds, landmarks, and attributes. + /// Detect human faces in an image, return face rectangles, and optionally with + /// faceIds, landmarks, and attributes.<br /> + /// * 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 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. + /// * JPEG, PNG, GIF (the first frame), and BMP format are supported. The + /// allowed image file size is from 1KB to 6MB. + /// * Faces are detectable when its size is 36x36 to 4096x4096 pixels. If need + /// to detect very small but clear faces, please try to enlarge the input + /// image. + /// * Up to 64 faces can be returned for an image. Faces are ranked by face + /// rectangle size from large to small. + /// * Face detector prefer frontal and near-frontal faces. There are cases that + /// faces may not be detected, e.g. exceptionally large face angles (head-pose) + /// or being occluded, or wrong image orientation. + /// * Attributes (age, gender, headPose, smile, facialHair, glasses, emotion, + /// hair, makeup, occlusion, accessories, blur, exposure and noise) may not be + /// perfectly accurate. HeadPose's pitch value is a reserved field and will + /// always return 0. + /// * 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) + /// /// /// /// The operations group for this extension method. @@ -181,12 +298,25 @@ public static partial class FaceOperationsExtensions /// and emotion. Note that each face attribute analysis has additional /// computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face features + /// are extracted and associated with detected faceIds, (Large)FaceList or + /// (Large)PersonGroup. A recognition model name can be provided when + /// performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup + /// - Create. The default value is 'recognition_01', if latest model needed, + /// please explicitly specify the model you need. Possible values include: + /// 'recognition_01', 'recognition_02' + /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> DetectWithUrlAsync(this IFaceOperations operations, string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> DetectWithUrlAsync(this IFaceOperations operations, string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.DetectWithUrlWithHttpMessagesAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.DetectWithUrlWithHttpMessagesAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } @@ -255,12 +385,25 @@ public static partial class FaceOperationsExtensions /// and emotion. Note that each face attribute analysis has additional /// computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face features + /// are extracted and associated with detected faceIds, (Large)FaceList or + /// (Large)PersonGroup. A recognition model name can be provided when + /// performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup + /// - Create. The default value is 'recognition_01', if latest model needed, + /// please explicitly specify the model you need. Possible values include: + /// 'recognition_01', 'recognition_02' + /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> DetectWithStreamAsync(this IFaceOperations operations, Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> DetectWithStreamAsync(this IFaceOperations operations, Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.DetectWithStreamWithHttpMessagesAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.DetectWithStreamWithHttpMessagesAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceListOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceListOperations.cs index 2519d4dbccf3..4f29ac4284e3 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceListOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceListOperations.cs @@ -24,8 +24,38 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public partial interface IFaceListOperations { /// - /// Create an empty face list. Up to 64 face lists are allowed to exist - /// in one subscription. + /// Create an empty face list with user-specified faceListId, name, an + /// optional userData and recognitionModel. Up to 64 face lists are + /// allowed in one subscription. + /// <br /> Face list is a list of faces, up to 1,000 faces, and + /// used by [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> 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. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> 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. + /// /// /// /// Id referencing a particular face list. @@ -36,6 +66,9 @@ public partial interface IFaceListOperations /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The headers that will be added to request. /// @@ -48,13 +81,19 @@ public partial interface IFaceListOperations /// /// Thrown when a required parameter is null /// - Task CreateWithHttpMessagesAsync(string faceListId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task CreateWithHttpMessagesAsync(string faceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Retrieve a face list's information. + /// Retrieve a face list’s faceListId, name, userData, recognitionModel + /// and faces in the face list. + /// /// /// /// Id referencing a particular face list. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -70,7 +109,7 @@ public partial interface IFaceListOperations /// /// Thrown when a required parameter is null /// - Task> GetWithHttpMessagesAsync(string faceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task> GetWithHttpMessagesAsync(string faceListId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Update information of a face list. /// @@ -117,9 +156,16 @@ public partial interface IFaceListOperations /// Task DeleteWithHttpMessagesAsync(string faceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Retrieve information about all existing face lists. Only - /// faceListId, name and userData will be returned. + /// List face lists’ faceListId, name, userData and recognitionModel. + /// <br /> + /// To get face information inside faceList use [FaceList - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524c) + /// /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -135,7 +181,7 @@ public partial interface IFaceListOperations /// /// Thrown when a required parameter is null /// - Task>> ListWithHttpMessagesAsync(Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> ListWithHttpMessagesAsync(bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Delete an existing face from a face list (given by a /// persistedFaceId and a faceListId). Persisted image related to the diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceOperations.cs index 5a22b62ab1d2..42e9c9986f2c 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IFaceOperations.cs @@ -24,8 +24,32 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public partial interface IFaceOperations { /// - /// Given query face's faceId, find the similar-looking faces from a - /// faceId array, a face list or a large face list. + /// Given query face's faceId, to search the similar-looking faces from + /// a faceId array, a face list or a large face list. faceId array + /// contains the faces created by [Face - + /// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236), + /// which will expire 24 hours after creation. A "faceListId" is + /// created by [FaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039524b) + /// containing persistedFaceIds that will not expire. And a + /// "largeFaceListId" is created by [LargeFaceList - + /// Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc) + /// containing persistedFaceIds that will also not expire. Depending on + /// the input the returned similar faces list contains faceIds or + /// persistedFaceIds ranked by similarity. + /// <br/>Find similar has two working modes, "matchPerson" and + /// "matchFace". "matchPerson" is the default mode that it tries to + /// find faces of the same person as possible by using internal + /// same-person thresholds. It is useful to find a known person's other + /// photos. Note that an empty list will be returned if no faces pass + /// the internal thresholds. "matchFace" mode ignores same-person + /// thresholds and returns ranked similar faces anyway, even the + /// similarity is low. It can be used in the cases like searching + /// celebrity-looking faces. + /// <br/>The 'recognitionModel' associated with the query face's + /// faceId should be the same as the 'recognitionModel' used by the + /// target faceId array, face list or large face list. + /// /// /// /// FaceId of the query face. User needs to call Face - Detect first to @@ -78,7 +102,24 @@ public partial interface IFaceOperations /// Task>> FindSimilarWithHttpMessagesAsync(System.Guid faceId, string faceListId = default(string), string largeFaceListId = default(string), IList faceIds = default(IList), int? maxNumOfCandidatesReturned = 20, FindSimilarMatchMode mode = default(FindSimilarMatchMode), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Divide candidate faces into groups based on face similarity. + /// Divide candidate faces into groups based on face similarity.<br + /// /> + /// * The output is one or more disjointed face groups and a + /// messyGroup. A face group contains faces that have similar looking, + /// often of the same person. Face groups are ranked by group size, + /// i.e. number of faces. Notice that faces belonging to a same person + /// might be split into several groups in the result. + /// * MessyGroup is a special face group containing faces that cannot + /// find any similar counterpart face from original faces. The + /// messyGroup will not appear in the result if all faces found their + /// counterparts. + /// * Group API needs at least 2 candidate faces and 1000 at most. We + /// suggest to try [Face - + /// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a) + /// when you only have 2 candidate faces. + /// * The 'recognitionModel' associated with the query faces' faceIds + /// should be the same. + /// /// /// /// Array of candidate faceId created by Face - Detect. The maximum is @@ -104,6 +145,37 @@ public partial interface IFaceOperations /// 1-to-many identification to find the closest matches of the /// specific query person face from a person group or large person /// group. + /// <br/> For each face in the faceIds array, Face Identify will + /// compute similarities between the query face and all the faces in + /// the person group (given by personGroupId) or large person group + /// (given by largePersonGroupId), and return candidate person(s) for + /// that face ranked by similarity confidence. The person group/large + /// person group should be trained to make it ready for identification. + /// See more in [PersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249) + /// and [LargePersonGroup - + /// Train](/docs/services/563879b61984550e40cbbe8d/operations/599ae2d16ac60f11b48b5aa4). + /// <br/> + /// + /// Remarks:<br /> + /// * The algorithm allows more than one face to be identified + /// independently at the same request, but no more than 10 faces. + /// * Each person in the person group/large person group could have + /// more than one face, but no more than 248 faces. + /// * Higher face image quality means better identification precision. + /// Please consider high-quality faces: frontal, clear, and face size + /// is 200x200 pixels (100 pixels between eyes) or bigger. + /// * Number of candidates returned is restricted by + /// maxNumOfCandidatesReturned and confidenceThreshold. If no person is + /// identified, the returned candidates will be an empty array. + /// * Try [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237) + /// when you need to find similar faces from a face list/large face + /// list instead of a person group/large person group. + /// * The 'recognitionModel' associated with the query faces' faceIds + /// should be the same as the 'recognitionModel' used by the target + /// person group or large person group. + /// /// /// /// Array of query faces faceIds, created by the Face - Detect. Each of @@ -148,6 +220,17 @@ public partial interface IFaceOperations /// /// Verify whether two faces belong to a same person or whether one /// face belongs to a person. + /// <br/> + /// Remarks:<br /> + /// * Higher face image quality means better identification precision. + /// Please consider high-quality faces: frontal, clear, and face size + /// is 200x200 pixels (100 pixels between eyes) or bigger. + /// * For the scenarios that are sensitive to accuracy please make your + /// own judgment. + /// * The 'recognitionModel' associated with the query faces' faceIds + /// should be the same as the 'recognitionModel' used by the target + /// face, person group or large person group. + /// /// /// /// FaceId of the first face, comes from Face - Detect @@ -172,8 +255,48 @@ public partial interface IFaceOperations /// Task> VerifyFaceToFaceWithHttpMessagesAsync(System.Guid faceId1, System.Guid faceId2, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Detect human faces in an image and returns face locations, and - /// optionally with faceIds, landmarks, and attributes. + /// Detect human faces in an image, return face rectangles, and + /// optionally with faceIds, landmarks, and attributes.<br /> + /// * 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 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. + /// * JPEG, PNG, GIF (the first frame), and BMP format are supported. + /// The allowed image file size is from 1KB to 6MB. + /// * Faces are detectable when its size is 36x36 to 4096x4096 pixels. + /// If need to detect very small but clear faces, please try to enlarge + /// the input image. + /// * Up to 64 faces can be returned for an image. Faces are ranked by + /// face rectangle size from large to small. + /// * Face detector prefer frontal and near-frontal faces. There are + /// cases that faces may not be detected, e.g. exceptionally large face + /// angles (head-pose) or being occluded, or wrong image orientation. + /// * Attributes (age, gender, headPose, smile, facialHair, glasses, + /// emotion, hair, makeup, occlusion, accessories, blur, exposure and + /// noise) may not be perfectly accurate. HeadPose's pitch value is a + /// reserved field and will always return 0. + /// * 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) + /// /// /// /// Publicly reachable URL of an image @@ -193,6 +316,20 @@ public partial interface IFaceOperations /// facialHair, glasses and emotion. Note that each face attribute /// analysis has additional computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face + /// features are extracted and associated with detected faceIds, + /// (Large)FaceList or (Large)PersonGroup. A recognition model name can + /// be provided when performing Face - Detect or (Large)FaceList - + /// Create or (Large)PersonGroup - Create. The default value is + /// 'recognition_01', if latest model needed, please explicitly specify + /// the model you need. Possible values include: 'recognition_01', + /// 'recognition_02' + /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -208,7 +345,7 @@ public partial interface IFaceOperations /// /// Thrown when a required parameter is null /// - Task>> DetectWithUrlWithHttpMessagesAsync(string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> DetectWithUrlWithHttpMessagesAsync(string url, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Verify whether two faces belong to a same person. Compares a face /// Id with a Person Id @@ -271,6 +408,20 @@ public partial interface IFaceOperations /// facialHair, glasses and emotion. Note that each face attribute /// analysis has additional computational and time cost. /// + /// + /// Name of recognition model. Recognition model is used when the face + /// features are extracted and associated with detected faceIds, + /// (Large)FaceList or (Large)PersonGroup. A recognition model name can + /// be provided when performing Face - Detect or (Large)FaceList - + /// Create or (Large)PersonGroup - Create. The default value is + /// 'recognition_01', if latest model needed, please explicitly specify + /// the model you need. Possible values include: 'recognition_01', + /// 'recognition_02' + /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -286,6 +437,6 @@ public partial interface IFaceOperations /// /// Thrown when a required parameter is null /// - Task>> DetectWithStreamWithHttpMessagesAsync(Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> DetectWithStreamWithHttpMessagesAsync(Stream image, bool? returnFaceId = true, bool? returnFaceLandmarks = false, IList returnFaceAttributes = default(IList), string recognitionModel = default(string), bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); } } diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargeFaceListOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargeFaceListOperations.cs index b3a7fc7b57f8..5da7e7de1c8b 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargeFaceListOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargeFaceListOperations.cs @@ -24,8 +24,42 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public partial interface ILargeFaceListOperations { /// - /// Create an empty large face list. Up to 64 large face lists are - /// allowed to exist in one subscription. + /// Create an empty large face list with user-specified + /// largeFaceListId, name, an optional userData and recognitionModel. + /// <br /> Large face list is a list of faces, up to 1,000,000 + /// faces, and used by [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> After creation, user should use [LargeFaceList Face - + /// 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 - + /// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) + /// is called. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> + /// * Free-tier subscription quota: 64 large face lists. + /// * S0-tier subscription quota: 1,000,000 large face lists. + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular large face list. @@ -36,6 +70,9 @@ public partial interface ILargeFaceListOperations /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The headers that will be added to request. /// @@ -48,13 +85,18 @@ public partial interface ILargeFaceListOperations /// /// Thrown when a required parameter is null /// - Task CreateWithHttpMessagesAsync(string largeFaceListId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task CreateWithHttpMessagesAsync(string largeFaceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Retrieve a large face list's information. + /// Retrieve a large face list’s largeFaceListId, name, userData and + /// recognitionModel. /// /// /// Id referencing a particular large face list. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -70,7 +112,7 @@ public partial interface ILargeFaceListOperations /// /// Thrown when a required parameter is null /// - Task> GetWithHttpMessagesAsync(string largeFaceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task> GetWithHttpMessagesAsync(string largeFaceListId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Update information of a large face list. /// @@ -140,9 +182,34 @@ public partial interface ILargeFaceListOperations /// Task> GetTrainingStatusWithHttpMessagesAsync(string largeFaceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Retrieve information about all existing large face lists. Only - /// largeFaceListId, name and userData will be returned. + /// List large face lists’ information of largeFaceListId, name, + /// userData and recognitionModel. <br /> + /// To get face information inside largeFaceList use [LargeFaceList + /// Face - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br + /// /> + /// * Large face lists are stored in alphabetical order of + /// largeFaceListId. + /// * "start" parameter (string, optional) is a user-provided + /// largeFaceListId value that returned entries have larger ids by + /// string comparison. "start" set to empty to indicate return from the + /// first item. + /// * "top" parameter (int, optional) specifies the number of entries + /// to return. A maximal of 1000 entries can be returned in one call. + /// To fetch more, you can specify "start" with the last retuned + /// entry’s Id of the current call. + /// <br /> + /// For example, total 5 large person lists: "list1", ..., "list5". + /// <br /> "start=&top=" will return all 5 lists. + /// <br /> "start=&top=2" will return "list1", "list2". + /// <br /> "start=list2&top=3" will return "list3", "list4", + /// "list5". + /// /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -158,7 +225,7 @@ public partial interface ILargeFaceListOperations /// /// Thrown when a required parameter is null /// - Task>> ListWithHttpMessagesAsync(Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> ListWithHttpMessagesAsync(bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Queue a large face list training task, the training task may not be /// started immediately. diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargePersonGroupOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargePersonGroupOperations.cs index 1dc0e72f7309..22dcf157ebd5 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargePersonGroupOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/ILargePersonGroupOperations.cs @@ -23,8 +23,37 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public partial interface ILargePersonGroupOperations { /// - /// Create a new large person group with specified largePersonGroupId, - /// name and user-provided userData. + /// Create a new large person group with user-specified + /// largePersonGroupId, name, an optional userData and + /// recognitionModel. + /// <br /> 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. + /// <br /> 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). + /// <br /> The person face, image, 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. + /// <br /> + /// * Free-tier subscription quota: 1,000 large person groups. + /// * S0-tier subscription quota: 1,000,000 large person groups. + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular large person group. @@ -35,6 +64,9 @@ public partial interface ILargePersonGroupOperations /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The headers that will be added to request. /// @@ -47,7 +79,7 @@ public partial interface ILargePersonGroupOperations /// /// Thrown when a required parameter is null /// - Task CreateWithHttpMessagesAsync(string largePersonGroupId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task CreateWithHttpMessagesAsync(string largePersonGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Delete an existing large person group. Persisted face features of /// all people in the large person group will also be deleted. @@ -70,11 +102,20 @@ public partial interface ILargePersonGroupOperations Task DeleteWithHttpMessagesAsync(string largePersonGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Retrieve the information of a large person group, including its - /// name and userData. + /// name, userData and recognitionModel. This API returns large person + /// group information only, use [LargePersonGroup Person - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) + /// instead to retrieve person information under the large person + /// group. + /// /// /// /// Id referencing a particular large person group. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -90,7 +131,7 @@ public partial interface ILargePersonGroupOperations /// /// Thrown when a required parameter is null /// - Task> GetWithHttpMessagesAsync(string largePersonGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task> GetWithHttpMessagesAsync(string largePersonGroupId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Update an existing large person group's display name and userData. /// The properties which does not appear in request body will not be @@ -142,7 +183,25 @@ public partial interface ILargePersonGroupOperations /// Task> GetTrainingStatusWithHttpMessagesAsync(string largePersonGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// List large person groups and their information. + /// List all existing large person groups’s largePersonGroupId, name, + /// userData and recognitionModel.<br /> + /// * Large person groups are stored in alphabetical order of + /// largePersonGroupId. + /// * "start" parameter (string, optional) is a user-provided + /// largePersonGroupId value that returned entries have larger ids by + /// string comparison. "start" set to empty to indicate return from the + /// first item. + /// * "top" parameter (int, optional) specifies the number of entries + /// to return. A maximal of 1000 entries can be returned in one call. + /// To fetch more, you can specify "start" with the last retuned + /// entry’s Id of the current call. + /// <br /> + /// For example, total 5 large person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", + /// "group4", "group5". + /// /// /// /// List large person groups from the least largePersonGroupId greater @@ -151,6 +210,10 @@ public partial interface ILargePersonGroupOperations /// /// The number of large person groups to list. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -166,7 +229,7 @@ public partial interface ILargePersonGroupOperations /// /// Thrown when a required parameter is null /// - Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Queue a large person group training task, the training task may not /// be started immediately. diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IPersonGroupOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IPersonGroupOperations.cs index 0fef02f6a473..521baf7cec68 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IPersonGroupOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/IPersonGroupOperations.cs @@ -23,8 +23,40 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public partial interface IPersonGroupOperations { /// - /// Create a new person group with specified personGroupId, name and - /// user-provided userData. + /// Create a new person group with specified personGroupId, name, + /// user-provided userData and recognitionModel. + /// <br /> A person group is the container of the uploaded person + /// data, including face images and face recognition features. + /// <br /> 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). + /// <br /> The person's face, image, 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. + /// <br /> + /// * 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). + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular person group. @@ -35,6 +67,9 @@ public partial interface IPersonGroupOperations /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The headers that will be added to request. /// @@ -47,7 +82,7 @@ public partial interface IPersonGroupOperations /// /// Thrown when a required parameter is null /// - Task CreateWithHttpMessagesAsync(string personGroupId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task CreateWithHttpMessagesAsync(string personGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Delete an existing person group. Persisted face features of all /// people in the person group will also be deleted. @@ -69,12 +104,18 @@ public partial interface IPersonGroupOperations /// Task DeleteWithHttpMessagesAsync(string personGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// Retrieve the information of a person group, including its name and - /// userData. + /// Retrieve person group name, userData and recognitionModel. To get + /// person information under this personGroup, use [PersonGroup Person + /// - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). /// /// /// Id referencing a particular person group. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -90,7 +131,7 @@ public partial interface IPersonGroupOperations /// /// Thrown when a required parameter is null /// - Task> GetWithHttpMessagesAsync(string personGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task> GetWithHttpMessagesAsync(string personGroupId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Update an existing person group's display name and userData. The /// properties which does not appear in request body will not be @@ -142,7 +183,24 @@ public partial interface IPersonGroupOperations /// Task> GetTrainingStatusWithHttpMessagesAsync(string personGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// - /// List person groups and their information. + /// List person groups’s personGroupId, name, userData and + /// recognitionModel.<br /> + /// * Person groups are stored in alphabetical order of personGroupId. + /// * "start" parameter (string, optional) is a user-provided + /// personGroupId value that returned entries have larger ids by string + /// comparison. "start" set to empty to indicate return from the first + /// item. + /// * "top" parameter (int, optional) specifies the number of entries + /// to return. A maximal of 1000 entries can be returned in one call. + /// To fetch more, you can specify "start" with the last retuned + /// entry’s Id of the current call. + /// <br /> + /// For example, total 5 person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", + /// "group4", "group5". + /// /// /// /// List person groups from the least personGroupId greater than the @@ -151,6 +209,10 @@ public partial interface IPersonGroupOperations /// /// The number of person groups to list. /// + /// + /// A value indicating whether the operation should return + /// 'recognitionModel' in response. + /// /// /// The headers that will be added to request. /// @@ -166,7 +228,7 @@ public partial interface IPersonGroupOperations /// /// Thrown when a required parameter is null /// - Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); + Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)); /// /// Queue a person group training task, the training task may not be /// started immediately. diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperations.cs index 727024226951..ba5b545deb62 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperations.cs @@ -51,8 +51,40 @@ public LargeFaceListOperations(FaceClient client) public FaceClient Client { get; private set; } /// - /// Create an empty large face list. Up to 64 large face lists are allowed to - /// exist in one subscription. + /// Create an empty large face list with user-specified largeFaceListId, name, + /// an optional userData and recognitionModel. + /// <br /> Large face list is a list of faces, up to 1,000,000 faces, and + /// used by [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> After creation, user should use [LargeFaceList Face - + /// 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 - + /// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) + /// is called. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> + /// * Free-tier subscription quota: 64 large face lists. + /// * S0-tier subscription quota: 1,000,000 large face lists. + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular large face list. @@ -63,6 +95,9 @@ public LargeFaceListOperations(FaceClient client) /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// Headers that will be added to request. /// @@ -81,7 +116,7 @@ public LargeFaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task CreateWithHttpMessagesAsync(string largeFaceListId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task CreateWithHttpMessagesAsync(string largeFaceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -116,11 +151,12 @@ public LargeFaceListOperations(FaceClient client) throw new ValidationException(ValidationRules.MaxLength, "userData", 16384); } } - NameAndUserDataContract body = new NameAndUserDataContract(); - if (name != null || userData != null) + MetaDataContract body = new MetaDataContract(); + if (name != null || userData != null || recognitionModel != null) { body.Name = name; body.UserData = userData; + body.RecognitionModel = recognitionModel; } // Tracing bool _shouldTrace = ServiceClientTracing.IsEnabled; @@ -228,11 +264,16 @@ public LargeFaceListOperations(FaceClient client) } /// - /// Retrieve a large face list's information. + /// Retrieve a large face list’s largeFaceListId, name, userData and + /// recognitionModel. /// /// /// Id referencing a particular large face list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -254,7 +295,7 @@ public LargeFaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task> GetWithHttpMessagesAsync(string largeFaceListId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task> GetWithHttpMessagesAsync(string largeFaceListId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -283,6 +324,7 @@ public LargeFaceListOperations(FaceClient client) _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("largeFaceListId", largeFaceListId); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "Get", tracingParameters); } @@ -291,6 +333,15 @@ public LargeFaceListOperations(FaceClient client) var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "largefacelists/{largeFaceListId}"; _url = _url.Replace("{Endpoint}", Client.Endpoint); _url = _url.Replace("{largeFaceListId}", System.Uri.EscapeDataString(largeFaceListId)); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; @@ -876,9 +927,30 @@ public LargeFaceListOperations(FaceClient client) } /// - /// Retrieve information about all existing large face lists. Only - /// largeFaceListId, name and userData will be returned. + /// List large face lists’ information of largeFaceListId, name, userData and + /// recognitionModel. <br /> + /// To get face information inside largeFaceList use [LargeFaceList Face - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br + /// /> + /// * Large face lists are stored in alphabetical order of largeFaceListId. + /// * "start" parameter (string, optional) is a user-provided largeFaceListId + /// value that returned entries have larger ids by string comparison. "start" + /// set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 large person lists: "list1", ..., "list5". + /// <br /> "start=&top=" will return all 5 lists. + /// <br /> "start=&top=2" will return "list1", "list2". + /// <br /> "start=list2&top=3" will return "list3", "list4", "list5". + /// /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -900,7 +972,7 @@ public LargeFaceListOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> ListWithHttpMessagesAsync(Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> ListWithHttpMessagesAsync(bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -913,6 +985,7 @@ public LargeFaceListOperations(FaceClient client) { _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "List", tracingParameters); } @@ -920,6 +993,15 @@ public LargeFaceListOperations(FaceClient client) var _baseUrl = Client.BaseUri; var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "largefacelists"; _url = _url.Replace("{Endpoint}", Client.Endpoint); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperationsExtensions.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperationsExtensions.cs index 9acd9c5398b0..a4cb0c8aeaa6 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperationsExtensions.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargeFaceListOperationsExtensions.cs @@ -23,8 +23,40 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public static partial class LargeFaceListOperationsExtensions { /// - /// Create an empty large face list. Up to 64 large face lists are allowed to - /// exist in one subscription. + /// Create an empty large face list with user-specified largeFaceListId, name, + /// an optional userData and recognitionModel. + /// <br /> Large face list is a list of faces, up to 1,000,000 faces, and + /// used by [Face - Find + /// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237). + /// <br /> After creation, user should use [LargeFaceList Face - + /// 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 - + /// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd) + /// is called. + /// <br /> 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 + /// [PersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244) + /// / + /// [LargePersonGroup](/docs/services/563879b61984550e40cbbe8d/operations/599acdee6ac60f11b48b5a9d) + /// and [Face - + /// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239). + /// <br /> + /// * Free-tier subscription quota: 64 large face lists. + /// * S0-tier subscription quota: 1,000,000 large face lists. + /// <br /> + /// '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. + /// /// /// /// The operations group for this extension method. @@ -38,16 +70,20 @@ public static partial class LargeFaceListOperationsExtensions /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The cancellation token. /// - public static async Task CreateAsync(this ILargeFaceListOperations operations, string largeFaceListId, string name = default(string), string userData = default(string), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task CreateAsync(this ILargeFaceListOperations operations, string largeFaceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), CancellationToken cancellationToken = default(CancellationToken)) { - (await operations.CreateWithHttpMessagesAsync(largeFaceListId, name, userData, null, cancellationToken).ConfigureAwait(false)).Dispose(); + (await operations.CreateWithHttpMessagesAsync(largeFaceListId, name, userData, recognitionModel, null, cancellationToken).ConfigureAwait(false)).Dispose(); } /// - /// Retrieve a large face list's information. + /// Retrieve a large face list’s largeFaceListId, name, userData and + /// recognitionModel. /// /// /// The operations group for this extension method. @@ -55,12 +91,16 @@ public static partial class LargeFaceListOperationsExtensions /// /// Id referencing a particular large face list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task GetAsync(this ILargeFaceListOperations operations, string largeFaceListId, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task GetAsync(this ILargeFaceListOperations operations, string largeFaceListId, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.GetWithHttpMessagesAsync(largeFaceListId, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.GetWithHttpMessagesAsync(largeFaceListId, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } @@ -128,18 +168,39 @@ public static partial class LargeFaceListOperationsExtensions } /// - /// Retrieve information about all existing large face lists. Only - /// largeFaceListId, name and userData will be returned. + /// List large face lists’ information of largeFaceListId, name, userData and + /// recognitionModel. <br /> + /// To get face information inside largeFaceList use [LargeFaceList Face - + /// Get](/docs/services/563879b61984550e40cbbe8d/operations/5a158cf2d2de3616c086f2d5)<br + /// /> + /// * Large face lists are stored in alphabetical order of largeFaceListId. + /// * "start" parameter (string, optional) is a user-provided largeFaceListId + /// value that returned entries have larger ids by string comparison. "start" + /// set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 large person lists: "list1", ..., "list5". + /// <br /> "start=&top=" will return all 5 lists. + /// <br /> "start=&top=2" will return "list1", "list2". + /// <br /> "start=list2&top=3" will return "list3", "list4", "list5". + /// /// /// /// The operations group for this extension method. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> ListAsync(this ILargeFaceListOperations operations, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> ListAsync(this ILargeFaceListOperations operations, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.ListWithHttpMessagesAsync(null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.ListWithHttpMessagesAsync(returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperations.cs index 97ebad890187..e35178be5cf6 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperations.cs @@ -51,8 +51,35 @@ public LargePersonGroupOperations(FaceClient client) public FaceClient Client { get; private set; } /// - /// Create a new large person group with specified largePersonGroupId, name and - /// user-provided userData. + /// Create a new large person group with user-specified largePersonGroupId, + /// name, an optional userData and recognitionModel. + /// <br /> 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. + /// <br /> 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). + /// <br /> The person face, image, 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. + /// <br /> + /// * Free-tier subscription quota: 1,000 large person groups. + /// * S0-tier subscription quota: 1,000,000 large person groups. + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular large person group. @@ -63,6 +90,9 @@ public LargePersonGroupOperations(FaceClient client) /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// Headers that will be added to request. /// @@ -81,7 +111,7 @@ public LargePersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task CreateWithHttpMessagesAsync(string largePersonGroupId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task CreateWithHttpMessagesAsync(string largePersonGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -116,11 +146,12 @@ public LargePersonGroupOperations(FaceClient client) throw new ValidationException(ValidationRules.MaxLength, "userData", 16384); } } - NameAndUserDataContract body = new NameAndUserDataContract(); - if (name != null || userData != null) + MetaDataContract body = new MetaDataContract(); + if (name != null || userData != null || recognitionModel != null) { body.Name = name; body.UserData = userData; + body.RecognitionModel = recognitionModel; } // Tracing bool _shouldTrace = ServiceClientTracing.IsEnabled; @@ -372,12 +403,20 @@ public LargePersonGroupOperations(FaceClient client) } /// - /// Retrieve the information of a large person group, including its name and - /// userData. + /// Retrieve the information of a large person group, including its name, + /// userData and recognitionModel. This API returns large person group + /// information only, use [LargePersonGroup Person - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) + /// instead to retrieve person information under the large person group. + /// /// /// /// Id referencing a particular large person group. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -399,7 +438,7 @@ public LargePersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task> GetWithHttpMessagesAsync(string largePersonGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task> GetWithHttpMessagesAsync(string largePersonGroupId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -428,6 +467,7 @@ public LargePersonGroupOperations(FaceClient client) _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("largePersonGroupId", largePersonGroupId); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "Get", tracingParameters); } @@ -436,6 +476,15 @@ public LargePersonGroupOperations(FaceClient client) var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "largepersongroups/{largePersonGroupId}"; _url = _url.Replace("{Endpoint}", Client.Endpoint); _url = _url.Replace("{largePersonGroupId}", System.Uri.EscapeDataString(largePersonGroupId)); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; @@ -879,7 +928,24 @@ public LargePersonGroupOperations(FaceClient client) } /// - /// List large person groups and their information. + /// List all existing large person groups’s largePersonGroupId, name, userData + /// and recognitionModel.<br /> + /// * Large person groups are stored in alphabetical order of + /// largePersonGroupId. + /// * "start" parameter (string, optional) is a user-provided + /// largePersonGroupId value that returned entries have larger ids by string + /// comparison. "start" set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 large person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", "group4", + /// "group5". + /// /// /// /// List large person groups from the least largePersonGroupId greater than the @@ -888,6 +954,10 @@ public LargePersonGroupOperations(FaceClient client) /// /// The number of large person groups to list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -909,7 +979,7 @@ public LargePersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -939,6 +1009,7 @@ public LargePersonGroupOperations(FaceClient client) Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("start", start); tracingParameters.Add("top", top); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "List", tracingParameters); } @@ -955,6 +1026,10 @@ public LargePersonGroupOperations(FaceClient client) { _queryParameters.Add(string.Format("top={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(top, Client.SerializationSettings).Trim('"')))); } + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } if (_queryParameters.Count > 0) { _url += "?" + string.Join("&", _queryParameters); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperationsExtensions.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperationsExtensions.cs index e22c33ea2f77..b776942e57e5 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperationsExtensions.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/LargePersonGroupOperationsExtensions.cs @@ -22,8 +22,35 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public static partial class LargePersonGroupOperationsExtensions { /// - /// Create a new large person group with specified largePersonGroupId, name and - /// user-provided userData. + /// Create a new large person group with user-specified largePersonGroupId, + /// name, an optional userData and recognitionModel. + /// <br /> 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. + /// <br /> 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). + /// <br /> The person face, image, 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. + /// <br /> + /// * Free-tier subscription quota: 1,000 large person groups. + /// * S0-tier subscription quota: 1,000,000 large person groups. + /// <br /> + /// '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. + /// /// /// /// The operations group for this extension method. @@ -37,12 +64,15 @@ public static partial class LargePersonGroupOperationsExtensions /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The cancellation token. /// - public static async Task CreateAsync(this ILargePersonGroupOperations operations, string largePersonGroupId, string name = default(string), string userData = default(string), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task CreateAsync(this ILargePersonGroupOperations operations, string largePersonGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), CancellationToken cancellationToken = default(CancellationToken)) { - (await operations.CreateWithHttpMessagesAsync(largePersonGroupId, name, userData, null, cancellationToken).ConfigureAwait(false)).Dispose(); + (await operations.CreateWithHttpMessagesAsync(largePersonGroupId, name, userData, recognitionModel, null, cancellationToken).ConfigureAwait(false)).Dispose(); } /// @@ -64,8 +94,12 @@ public static partial class LargePersonGroupOperationsExtensions } /// - /// Retrieve the information of a large person group, including its name and - /// userData. + /// Retrieve the information of a large person group, including its name, + /// userData and recognitionModel. This API returns large person group + /// information only, use [LargePersonGroup Person - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/599adda06ac60f11b48b5aa1) + /// instead to retrieve person information under the large person group. + /// /// /// /// The operations group for this extension method. @@ -73,12 +107,16 @@ public static partial class LargePersonGroupOperationsExtensions /// /// Id referencing a particular large person group. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task GetAsync(this ILargePersonGroupOperations operations, string largePersonGroupId, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task GetAsync(this ILargePersonGroupOperations operations, string largePersonGroupId, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.GetWithHttpMessagesAsync(largePersonGroupId, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.GetWithHttpMessagesAsync(largePersonGroupId, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } @@ -130,7 +168,24 @@ public static partial class LargePersonGroupOperationsExtensions } /// - /// List large person groups and their information. + /// List all existing large person groups’s largePersonGroupId, name, userData + /// and recognitionModel.<br /> + /// * Large person groups are stored in alphabetical order of + /// largePersonGroupId. + /// * "start" parameter (string, optional) is a user-provided + /// largePersonGroupId value that returned entries have larger ids by string + /// comparison. "start" set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 large person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", "group4", + /// "group5". + /// /// /// /// The operations group for this extension method. @@ -142,12 +197,16 @@ public static partial class LargePersonGroupOperationsExtensions /// /// The number of large person groups to list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> ListAsync(this ILargePersonGroupOperations operations, string start = default(string), int? top = 1000, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> ListAsync(this ILargePersonGroupOperations operations, string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.ListWithHttpMessagesAsync(start, top, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.ListWithHttpMessagesAsync(start, top, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/DetectedFace.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/DetectedFace.cs index 2d64fce0d116..a6095814bb31 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/DetectedFace.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/DetectedFace.cs @@ -30,9 +30,12 @@ public DetectedFace() /// /// Initializes a new instance of the DetectedFace class. /// - public DetectedFace(FaceRectangle faceRectangle, System.Guid? faceId = default(System.Guid?), FaceLandmarks faceLandmarks = default(FaceLandmarks), FaceAttributes faceAttributes = default(FaceAttributes)) + /// Possible values include: + /// 'recognition_01', 'recognition_02' + public DetectedFace(FaceRectangle faceRectangle, System.Guid? faceId = default(System.Guid?), string recognitionModel = default(string), FaceLandmarks faceLandmarks = default(FaceLandmarks), FaceAttributes faceAttributes = default(FaceAttributes)) { FaceId = faceId; + RecognitionModel = recognitionModel; FaceRectangle = faceRectangle; FaceLandmarks = faceLandmarks; FaceAttributes = faceAttributes; @@ -49,6 +52,13 @@ public DetectedFace() [JsonProperty(PropertyName = "faceId")] public System.Guid? FaceId { get; set; } + /// + /// Gets or sets possible values include: 'recognition_01', + /// 'recognition_02' + /// + [JsonProperty(PropertyName = "recognitionModel")] + public string RecognitionModel { get; set; } + /// /// [JsonProperty(PropertyName = "faceRectangle")] diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/FaceList.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/FaceList.cs index 8b4dc1030a00..ab9d1d0b70b2 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/FaceList.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/FaceList.cs @@ -19,7 +19,7 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models /// /// Face list object. /// - public partial class FaceList : NameAndUserDataContract + public partial class FaceList : MetaDataContract { /// /// Initializes a new instance of the FaceList class. @@ -38,10 +38,12 @@ public FaceList() /// 128. /// User specified data. Length should not /// exceed 16KB. + /// Possible values include: + /// 'recognition_01', 'recognition_02' /// Persisted faces within the face /// list. - public FaceList(string faceListId, string name = default(string), string userData = default(string), IList persistedFaces = default(IList)) - : base(name, userData) + public FaceList(string faceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string), IList persistedFaces = default(IList)) + : base(name, userData, recognitionModel) { FaceListId = faceListId; PersistedFaces = persistedFaces; diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargeFaceList.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargeFaceList.cs index d5c6da592b97..eea07aa64a1e 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargeFaceList.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargeFaceList.cs @@ -17,7 +17,7 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models /// /// Large face list object. /// - public partial class LargeFaceList : NameAndUserDataContract + public partial class LargeFaceList : MetaDataContract { /// /// Initializes a new instance of the LargeFaceList class. @@ -36,8 +36,10 @@ public LargeFaceList() /// 128. /// User specified data. Length should not /// exceed 16KB. - public LargeFaceList(string largeFaceListId, string name = default(string), string userData = default(string)) - : base(name, userData) + /// Possible values include: + /// 'recognition_01', 'recognition_02' + public LargeFaceList(string largeFaceListId, string name = default(string), string userData = default(string), string recognitionModel = default(string)) + : base(name, userData, recognitionModel) { LargeFaceListId = largeFaceListId; CustomInit(); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargePersonGroup.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargePersonGroup.cs index 18d800d5d556..53d3d553dd3a 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargePersonGroup.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/LargePersonGroup.cs @@ -17,7 +17,7 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models /// /// Large person group object. /// - public partial class LargePersonGroup : NameAndUserDataContract + public partial class LargePersonGroup : MetaDataContract { /// /// Initializes a new instance of the LargePersonGroup class. @@ -36,8 +36,10 @@ public LargePersonGroup() /// 128. /// User specified data. Length should not /// exceed 16KB. - public LargePersonGroup(string largePersonGroupId, string name = default(string), string userData = default(string)) - : base(name, userData) + /// Possible values include: + /// 'recognition_01', 'recognition_02' + public LargePersonGroup(string largePersonGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string)) + : base(name, userData, recognitionModel) { LargePersonGroupId = largePersonGroupId; CustomInit(); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/MetaDataContract.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/MetaDataContract.cs new file mode 100644 index 000000000000..6a49e1329b73 --- /dev/null +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/MetaDataContract.cs @@ -0,0 +1,70 @@ +// +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. See License.txt in the project root for +// license information. +// +// Code generated by Microsoft (R) AutoRest Code Generator. +// Changes may cause incorrect behavior and will be lost if the code is +// regenerated. +// + +namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models +{ + using Newtonsoft.Json; + using System.Linq; + + /// + /// A combination of user defined name and user specified data and + /// recognition model name for largePersonGroup/personGroup, and + /// largeFaceList/faceList. + /// + public partial class MetaDataContract : NameAndUserDataContract + { + /// + /// Initializes a new instance of the MetaDataContract class. + /// + public MetaDataContract() + { + CustomInit(); + } + + /// + /// Initializes a new instance of the MetaDataContract class. + /// + /// User defined name, maximum length is + /// 128. + /// User specified data. Length should not + /// exceed 16KB. + /// Possible values include: + /// 'recognition_01', 'recognition_02' + public MetaDataContract(string name = default(string), string userData = default(string), string recognitionModel = default(string)) + : base(name, userData) + { + RecognitionModel = recognitionModel; + CustomInit(); + } + + /// + /// An initialization method that performs custom operations like setting defaults + /// + partial void CustomInit(); + + /// + /// Gets or sets possible values include: 'recognition_01', + /// 'recognition_02' + /// + [JsonProperty(PropertyName = "recognitionModel")] + public string RecognitionModel { get; set; } + + /// + /// Validate the object. + /// + /// + /// Thrown if validation fails + /// + public override void Validate() + { + base.Validate(); + } + } +} diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/PersonGroup.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/PersonGroup.cs index 7794e32f2bdb..15302ae44023 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/PersonGroup.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/PersonGroup.cs @@ -17,7 +17,7 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models /// /// Person group object. /// - public partial class PersonGroup : NameAndUserDataContract + public partial class PersonGroup : MetaDataContract { /// /// Initializes a new instance of the PersonGroup class. @@ -36,8 +36,10 @@ public PersonGroup() /// 128. /// User specified data. Length should not /// exceed 16KB. - public PersonGroup(string personGroupId, string name = default(string), string userData = default(string)) - : base(name, userData) + /// Possible values include: + /// 'recognition_01', 'recognition_02' + public PersonGroup(string personGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string)) + : base(name, userData, recognitionModel) { PersonGroupId = personGroupId; CustomInit(); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/RecognitionModel.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/RecognitionModel.cs new file mode 100644 index 000000000000..e4c82d54fb3b --- /dev/null +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/Models/RecognitionModel.cs @@ -0,0 +1,22 @@ +// +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. See License.txt in the project root for +// license information. +// +// Code generated by Microsoft (R) AutoRest Code Generator. +// Changes may cause incorrect behavior and will be lost if the code is +// regenerated. +// + +namespace Microsoft.Azure.CognitiveServices.Vision.Face.Models +{ + + /// + /// Defines values for RecognitionModel. + /// + public static class RecognitionModel + { + public const string Recognition01 = "recognition_01"; + public const string Recognition02 = "recognition_02"; + } +} diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperations.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperations.cs index 1f6a387a086e..f20f085adc39 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperations.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperations.cs @@ -51,8 +51,38 @@ public PersonGroupOperations(FaceClient client) public FaceClient Client { get; private set; } /// - /// Create a new person group with specified personGroupId, name and - /// user-provided userData. + /// Create a new person group with specified personGroupId, name, user-provided + /// userData and recognitionModel. + /// <br /> A person group is the container of the uploaded person data, + /// including face images and face recognition features. + /// <br /> 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). + /// <br /> The person's face, image, 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. + /// <br /> + /// * 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). + /// <br /> + /// '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. + /// /// /// /// Id referencing a particular person group. @@ -63,6 +93,9 @@ public PersonGroupOperations(FaceClient client) /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// Headers that will be added to request. /// @@ -81,7 +114,7 @@ public PersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task CreateWithHttpMessagesAsync(string personGroupId, string name = default(string), string userData = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task CreateWithHttpMessagesAsync(string personGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -116,11 +149,12 @@ public PersonGroupOperations(FaceClient client) throw new ValidationException(ValidationRules.MaxLength, "userData", 16384); } } - NameAndUserDataContract body = new NameAndUserDataContract(); - if (name != null || userData != null) + MetaDataContract body = new MetaDataContract(); + if (name != null || userData != null || recognitionModel != null) { body.Name = name; body.UserData = userData; + body.RecognitionModel = recognitionModel; } // Tracing bool _shouldTrace = ServiceClientTracing.IsEnabled; @@ -372,12 +406,17 @@ public PersonGroupOperations(FaceClient client) } /// - /// Retrieve the information of a person group, including its name and - /// userData. + /// Retrieve person group name, userData and recognitionModel. To get person + /// information under this personGroup, use [PersonGroup Person - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). /// /// /// Id referencing a particular person group. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -399,7 +438,7 @@ public PersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task> GetWithHttpMessagesAsync(string personGroupId, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task> GetWithHttpMessagesAsync(string personGroupId, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -428,6 +467,7 @@ public PersonGroupOperations(FaceClient client) _invocationId = ServiceClientTracing.NextInvocationId.ToString(); Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("personGroupId", personGroupId); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "Get", tracingParameters); } @@ -436,6 +476,15 @@ public PersonGroupOperations(FaceClient client) var _url = _baseUrl + (_baseUrl.EndsWith("/") ? "" : "/") + "persongroups/{personGroupId}"; _url = _url.Replace("{Endpoint}", Client.Endpoint); _url = _url.Replace("{personGroupId}", System.Uri.EscapeDataString(personGroupId)); + List _queryParameters = new List(); + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } + if (_queryParameters.Count > 0) + { + _url += "?" + string.Join("&", _queryParameters); + } // Create HTTP transport objects var _httpRequest = new HttpRequestMessage(); HttpResponseMessage _httpResponse = null; @@ -878,7 +927,23 @@ public PersonGroupOperations(FaceClient client) } /// - /// List person groups and their information. + /// List person groups’s personGroupId, name, userData and + /// recognitionModel.<br /> + /// * Person groups are stored in alphabetical order of personGroupId. + /// * "start" parameter (string, optional) is a user-provided personGroupId + /// value that returned entries have larger ids by string comparison. "start" + /// set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", "group4", + /// "group5". + /// /// /// /// List person groups from the least personGroupId greater than the "start". @@ -886,6 +951,10 @@ public PersonGroupOperations(FaceClient client) /// /// The number of person groups to list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// Headers that will be added to request. /// @@ -907,7 +976,7 @@ public PersonGroupOperations(FaceClient client) /// /// A response object containing the response body and response headers. /// - public async Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) + public async Task>> ListWithHttpMessagesAsync(string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, Dictionary> customHeaders = null, CancellationToken cancellationToken = default(CancellationToken)) { if (Client.Endpoint == null) { @@ -937,6 +1006,7 @@ public PersonGroupOperations(FaceClient client) Dictionary tracingParameters = new Dictionary(); tracingParameters.Add("start", start); tracingParameters.Add("top", top); + tracingParameters.Add("returnRecognitionModel", returnRecognitionModel); tracingParameters.Add("cancellationToken", cancellationToken); ServiceClientTracing.Enter(_invocationId, this, "List", tracingParameters); } @@ -953,6 +1023,10 @@ public PersonGroupOperations(FaceClient client) { _queryParameters.Add(string.Format("top={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(top, Client.SerializationSettings).Trim('"')))); } + if (returnRecognitionModel != null) + { + _queryParameters.Add(string.Format("returnRecognitionModel={0}", System.Uri.EscapeDataString(Rest.Serialization.SafeJsonConvert.SerializeObject(returnRecognitionModel, Client.SerializationSettings).Trim('"')))); + } if (_queryParameters.Count > 0) { _url += "?" + string.Join("&", _queryParameters); diff --git a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperationsExtensions.cs b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperationsExtensions.cs index 728e30fa9e28..67dbeab38e13 100644 --- a/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperationsExtensions.cs +++ b/src/SDKs/CognitiveServices/dataPlane/Vision/Face/Face/Generated/PersonGroupOperationsExtensions.cs @@ -22,8 +22,38 @@ namespace Microsoft.Azure.CognitiveServices.Vision.Face public static partial class PersonGroupOperationsExtensions { /// - /// Create a new person group with specified personGroupId, name and - /// user-provided userData. + /// Create a new person group with specified personGroupId, name, user-provided + /// userData and recognitionModel. + /// <br /> A person group is the container of the uploaded person data, + /// including face images and face recognition features. + /// <br /> 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). + /// <br /> The person's face, image, 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. + /// <br /> + /// * 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). + /// <br /> + /// '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. + /// /// /// /// The operations group for this extension method. @@ -37,12 +67,15 @@ public static partial class PersonGroupOperationsExtensions /// /// User specified data. Length should not exceed 16KB. /// + /// + /// Possible values include: 'recognition_01', 'recognition_02' + /// /// /// The cancellation token. /// - public static async Task CreateAsync(this IPersonGroupOperations operations, string personGroupId, string name = default(string), string userData = default(string), CancellationToken cancellationToken = default(CancellationToken)) + public static async Task CreateAsync(this IPersonGroupOperations operations, string personGroupId, string name = default(string), string userData = default(string), string recognitionModel = default(string), CancellationToken cancellationToken = default(CancellationToken)) { - (await operations.CreateWithHttpMessagesAsync(personGroupId, name, userData, null, cancellationToken).ConfigureAwait(false)).Dispose(); + (await operations.CreateWithHttpMessagesAsync(personGroupId, name, userData, recognitionModel, null, cancellationToken).ConfigureAwait(false)).Dispose(); } /// @@ -64,8 +97,9 @@ public static partial class PersonGroupOperationsExtensions } /// - /// Retrieve the information of a person group, including its name and - /// userData. + /// Retrieve person group name, userData and recognitionModel. To get person + /// information under this personGroup, use [PersonGroup Person - + /// List](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395241). /// /// /// The operations group for this extension method. @@ -73,12 +107,16 @@ public static partial class PersonGroupOperationsExtensions /// /// Id referencing a particular person group. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task GetAsync(this IPersonGroupOperations operations, string personGroupId, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task GetAsync(this IPersonGroupOperations operations, string personGroupId, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.GetWithHttpMessagesAsync(personGroupId, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.GetWithHttpMessagesAsync(personGroupId, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; } @@ -129,7 +167,23 @@ public static partial class PersonGroupOperationsExtensions } /// - /// List person groups and their information. + /// List person groups’s personGroupId, name, userData and + /// recognitionModel.<br /> + /// * Person groups are stored in alphabetical order of personGroupId. + /// * "start" parameter (string, optional) is a user-provided personGroupId + /// value that returned entries have larger ids by string comparison. "start" + /// set to empty to indicate return from the first item. + /// * "top" parameter (int, optional) specifies the number of entries to + /// return. A maximal of 1000 entries can be returned in one call. To fetch + /// more, you can specify "start" with the last retuned entry’s Id of the + /// current call. + /// <br /> + /// For example, total 5 person groups: "group1", ..., "group5". + /// <br /> "start=&top=" will return all 5 groups. + /// <br /> "start=&top=2" will return "group1", "group2". + /// <br /> "start=group2&top=3" will return "group3", "group4", + /// "group5". + /// /// /// /// The operations group for this extension method. @@ -140,12 +194,16 @@ public static partial class PersonGroupOperationsExtensions /// /// The number of person groups to list. /// + /// + /// A value indicating whether the operation should return 'recognitionModel' + /// in response. + /// /// /// The cancellation token. /// - public static async Task> ListAsync(this IPersonGroupOperations operations, string start = default(string), int? top = 1000, CancellationToken cancellationToken = default(CancellationToken)) + public static async Task> ListAsync(this IPersonGroupOperations operations, string start = default(string), int? top = 1000, bool? returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken)) { - using (var _result = await operations.ListWithHttpMessagesAsync(start, top, null, cancellationToken).ConfigureAwait(false)) + using (var _result = await operations.ListWithHttpMessagesAsync(start, top, returnRecognitionModel, null, cancellationToken).ConfigureAwait(false)) { return _result.Body; }