/// <summary>
/// Add a face to a specified large face list, up to 1,000,000 faces.
/// <br /> To deal with an image contains multiple faces, input face can
/// be specified as an image with a targetFace rectangle. It returns a
/// persistedFaceId representing the added face. No image will be stored. Only
/// the extracted face feature will be stored on server until [LargeFaceList
/// Face -
/// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a158c8ad2de3616c086f2d4)
/// or [LargeFaceList -
/// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd)
/// is called.
/// <br /> Note persistedFaceId is different from faceId generated by
/// [Face -
/// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
/// * Higher face image quality means better recognition precision. Please
/// consider high-quality faces: frontal, clear, and face size is 200x200
/// pixels (100 pixels between eyes) or bigger.
/// * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
/// allowed image file size is from 1KB to 6MB.
/// * "targetFace" rectangle should contain one face. Zero or multiple faces
/// will be regarded as an error. If the provided "targetFace" rectangle is not
/// returned from [Face -
/// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236),
/// there’s no guarantee to detect and add the face successfully.
/// * Out of detectable face size (36x36 - 4096x4096 pixels), large head-pose,
/// or large occlusions will cause failures.
/// * Adding/deleting faces to/from a same face list are processed sequentially
/// and to/from different face lists are in parallel.
/// * The minimum detectable face size is 36x36 pixels in an image no larger
/// than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels
/// will need a proportionally larger minimum face size.
/// * Different 'detectionModel' values can be provided. To use and compare
/// different detection models, please refer to [How to specify a detection
/// model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
/// | Model | Recommended use-case(s) |
/// | ---------- | -------- |
/// | 'detection_01': | The default detection model for [LargeFaceList - Add
/// Face](/docs/services/563879b61984550e40cbbe8d/operations/5a158c10d2de3616c086f2d3).
/// Recommend for near frontal face detection. For scenarios with exceptionally
/// large angle (head-pose) faces, occluded faces or wrong image orientation,
/// the faces in such cases may not be detected. |
/// | 'detection_02': | Detection model released in 2019 May with improved
/// accuracy especially on small, side and blurry faces. |
///
/// Quota:
/// * Free-tier subscription quota: 1,000 faces per large face list.
/// * S0-tier subscription quota: 1,000,000 faces per large face list.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='image'>
/// An image stream.
/// </param>
/// <param name='userData'>
/// User-specified data about the face for any purpose. The maximum length is
/// 1KB.
/// </param>
/// <param name='targetFace'>
/// A face rectangle to specify the target face to be added to a person in the
/// format of "targetFace=left,top,width,height". E.g.
/// "targetFace=10,10,100,100". If there is more than one face in the image,
/// targetFace is required to specify which face to add. No targetFace means
/// there is only one face detected in the entire image.
/// </param>
/// <param name='detectionModel'>
/// Name of detection model. Detection model is used to detect faces in the
/// submitted image. A detection model name can be provided when performing
/// Face - Detect or (Large)FaceList - Add Face or (Large)PersonGroup - Add
/// Face. The default value is 'detection_01', if another model is needed,
/// please explicitly specify it. Possible values include: 'detection_01',
/// 'detection_02'
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <PersistedFace> AddFaceFromStreamAsync(this ILargeFaceListOperations operations, string largeFaceListId, Stream image, string userData = default(string), IList <int> targetFace = default(IList <int>), string detectionModel = default(string), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.AddFaceFromStreamWithHttpMessagesAsync(largeFaceListId, image, userData, targetFace, detectionModel, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Retrieve information about a persisted face (specified by persistedFaceId
/// and its belonging largeFaceListId).
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='persistedFaceId'>
/// Id referencing a particular persistedFaceId of an existing face.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <PersistedFace> GetFaceAsync(this ILargeFaceListOperations operations, string largeFaceListId, System.Guid persistedFaceId, CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.GetFaceWithHttpMessagesAsync(largeFaceListId, persistedFaceId, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// List all faces in a large face list, and retrieve face information
/// (including userData and persistedFaceIds of registered faces of the face).
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='start'>
/// Starting face id to return (used to list a range of faces).
/// </param>
/// <param name='top'>
/// Number of faces to return starting with the face id indicated by the
/// 'start' parameter.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <IList <PersistedFace> > ListFacesAsync(this ILargeFaceListOperations operations, string largeFaceListId, string start = default(string), int?top = default(int?), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.ListFacesWithHttpMessagesAsync(largeFaceListId, start, top, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// 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 returned 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".
///
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='returnRecognitionModel'>
/// A value indicating whether the operation should return 'recognitionModel'
/// in response.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <IList <LargeFaceList> > ListAsync(this ILargeFaceListOperations operations, bool?returnRecognitionModel = false, CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.ListWithHttpMessagesAsync(returnRecognitionModel, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Retrieve the training status of a large face list (completed or ongoing).
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <TrainingStatus> GetTrainingStatusAsync(this ILargeFaceListOperations operations, string largeFaceListId, CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.GetTrainingStatusWithHttpMessagesAsync(largeFaceListId, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Initializes client properties.
/// </summary>
private void Initialize()
{
Face = new FaceOperations(this);
PersonGroupPerson = new PersonGroupPerson(this);
PersonGroup = new PersonGroupOperations(this);
FaceList = new FaceListOperations(this);
LargePersonGroupPerson = new LargePersonGroupPerson(this);
LargePersonGroup = new LargePersonGroupOperations(this);
LargeFaceList = new LargeFaceListOperations(this);
BaseUri = "{Endpoint}/face/v1.0";
SerializationSettings = new JsonSerializerSettings
{
Formatting = Newtonsoft.Json.Formatting.Indented,
DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat,
DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc,
NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore,
ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Serialize,
ContractResolver = new ReadOnlyJsonContractResolver(),
Converters = new List <JsonConverter>
{
new Iso8601TimeSpanConverter()
}
};
DeserializationSettings = new JsonSerializerSettings
{
DateFormatHandling = Newtonsoft.Json.DateFormatHandling.IsoDateFormat,
DateTimeZoneHandling = Newtonsoft.Json.DateTimeZoneHandling.Utc,
NullValueHandling = Newtonsoft.Json.NullValueHandling.Ignore,
ReferenceLoopHandling = Newtonsoft.Json.ReferenceLoopHandling.Serialize,
ContractResolver = new ReadOnlyJsonContractResolver(),
Converters = new List <JsonConverter>
{
new Iso8601TimeSpanConverter()
}
};
CustomInitialize();
}
/// <summary>
/// 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 - Find
/// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
/// No image will be stored. Only the extracted face features are stored on
/// server until [LargeFaceList -
/// Delete](/docs/services/563879b61984550e40cbbe8d/operations/5a1580d5d2de3616c086f2cd)
/// is called.
/// <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/>'recognitionModel' should be specified to associate with this
/// large face list. The default value for 'recognitionModel' is
/// 'recognition_01', if the latest model needed, please explicitly specify the
/// model you need in this parameter. New faces that are added to an existing
/// large face list will use the recognition model that's already associated
/// with the collection. Existing face features in a large face list can't be
/// updated to features extracted by another version of recognition model.
/// * 'recognition_01': The default recognition model for [LargeFaceList-
/// Create](/docs/services/563879b61984550e40cbbe8d/operations/5a157b68d2de3616c086f2cc).
/// All those large face lists created before 2019 March are bonded with this
/// recognition model.
/// * 'recognition_02': Recognition model released in 2019 March.
/// 'recognition_02' is recommended since its overall accuracy is improved
/// compared with 'recognition_01'.
///
/// Large face list quota:
/// * Free-tier subscription quota: 64 large face lists.
/// * S0-tier subscription quota: 1,000,000 large face lists.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='name'>
/// User defined name, maximum length is 128.
/// </param>
/// <param name='userData'>
/// User specified data. Length should not exceed 16KB.
/// </param>
/// <param name='recognitionModel'>
/// Possible values include: 'recognition_01', 'recognition_02'
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
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, recognitionModel, null, cancellationToken).ConfigureAwait(false)).Dispose();
}
/// <summary>
/// Update a persisted face's userData field.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='persistedFaceId'>
/// Id referencing a particular persistedFaceId of an existing face.
/// </param>
/// <param name='userData'>
/// User-provided data attached to the face. The size limit is 1KB.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task UpdateFaceAsync(this ILargeFaceListOperations operations, string largeFaceListId, System.Guid persistedFaceId, string userData = default(string), CancellationToken cancellationToken = default(CancellationToken))
{
(await operations.UpdateFaceWithHttpMessagesAsync(largeFaceListId, persistedFaceId, userData, null, cancellationToken).ConfigureAwait(false)).Dispose();
}
/// <summary>
/// Queue a large face list training task, the training task may not be started
/// immediately.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='largeFaceListId'>
/// Id referencing a particular large face list.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task TrainAsync(this ILargeFaceListOperations operations, string largeFaceListId, CancellationToken cancellationToken = default(CancellationToken))
{
(await operations.TrainWithHttpMessagesAsync(largeFaceListId, null, cancellationToken).ConfigureAwait(false)).Dispose();
}