/// <summary>
/// Given query face's faceId, find the similar-looking faces from a faceId
/// array, a face list or a large face list.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='faceId'>
/// FaceId of the query face. User needs to call Face - Detect first to get a
/// valid faceId. Note that this faceId is not persisted and will expire 24
/// hours after the detection call
/// </param>
/// <param name='faceListId'>
/// An existing user-specified unique candidate face list, created in Face List
/// - Create a Face List. Face list contains a set of persistedFaceIds which
/// are persisted and will never expire. Parameter faceListId, largeFaceListId
/// and faceIds should not be provided at the same time。
/// </param>
/// <param name='largeFaceListId'>
/// An existing user-specified unique candidate large face list, created in
/// LargeFaceList - Create. Large face list contains a set of persistedFaceIds
/// which are persisted and will never expire. Parameter faceListId,
/// largeFaceListId and faceIds should not be provided at the same time.
/// </param>
/// <param name='faceIds'>
/// An array of candidate faceIds. All of them are created by Face - Detect and
/// the faceIds will expire 24 hours after the detection call. The number of
/// faceIds is limited to 1000. Parameter faceListId, largeFaceListId and
/// faceIds should not be provided at the same time.
/// </param>
/// <param name='maxNumOfCandidatesReturned'>
/// The number of top similar faces returned. The valid range is [1, 1000].
/// </param>
/// <param name='mode'>
/// Similar face searching mode. It can be "matchPerson" or "matchFace".
/// Possible values include: 'matchPerson', 'matchFace'
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <IList <SimilarFace> > FindSimilarAsync(this IFaceOperations operations, System.Guid faceId, string faceListId = default(string), string largeFaceListId = default(string), IList <System.Guid?> faceIds = default(IList <System.Guid?>), int?maxNumOfCandidatesReturned = 20, FindSimilarMatchMode mode = default(FindSimilarMatchMode), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.FindSimilarWithHttpMessagesAsync(faceId, faceListId, largeFaceListId, faceIds, maxNumOfCandidatesReturned, mode, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Divide candidate faces into groups based on face similarity.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='faceIds'>
/// Array of candidate faceId created by Face - Detect. The maximum is 1000
/// faces
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <GroupResult> GroupAsync(this IFaceOperations operations, IList <System.Guid> faceIds, CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.GroupWithHttpMessagesAsync(faceIds, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Detect human faces in an image and returns face locations, and optionally
/// with faceIds, landmarks, and attributes.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='image'>
/// An image stream.
/// </param>
/// <param name='returnFaceId'>
/// A value indicating whether the operation should return faceIds of detected
/// faces.
/// </param>
/// <param name='returnFaceLandmarks'>
/// A value indicating whether the operation should return landmarks of the
/// detected faces.
/// </param>
/// <param name='returnFaceAttributes'>
/// Analyze and return the one or more specified face attributes in the
/// comma-separated string like "returnFaceAttributes=age,gender". Supported
/// face attributes include age, gender, headPose, smile, facialHair, glasses
/// and emotion. Note that each face attribute analysis has additional
/// computational and time cost.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <IList <DetectedFace> > DetectWithStreamAsync(this IFaceOperations operations, Stream image, bool?returnFaceId = true, bool?returnFaceLandmarks = false, IList <FaceAttributeType> returnFaceAttributes = default(IList <FaceAttributeType>), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.DetectWithStreamWithHttpMessagesAsync(image, returnFaceId, returnFaceLandmarks, returnFaceAttributes, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Verify whether two faces belong to a same person. Compares a face Id with a
/// Person Id
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='faceId'>
/// FaceId of the face, comes from Face - Detect
/// </param>
/// <param name='personId'>
/// Specify a certain person in a person group or a large person group.
/// personId is created in PersonGroup Person - Create or LargePersonGroup
/// Person - Create.
/// </param>
/// <param name='personGroupId'>
/// Using existing personGroupId and personId for fast loading a specified
/// person. personGroupId is created in PersonGroup - Create. Parameter
/// personGroupId and largePersonGroupId should not be provided at the same
/// time.
/// </param>
/// <param name='largePersonGroupId'>
/// Using existing largePersonGroupId and personId for fast loading a specified
/// person. largePersonGroupId is created in LargePersonGroup - Create.
/// Parameter personGroupId and largePersonGroupId should not be provided at
/// the same time.
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <VerifyResult> VerifyFaceToPersonAsync(this IFaceOperations operations, System.Guid faceId, System.Guid personId, string personGroupId = default(string), string largePersonGroupId = default(string), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.VerifyFaceToPersonWithHttpMessagesAsync(faceId, personId, personGroupId, largePersonGroupId, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Verify whether two faces belong to a same person or whether one face
/// belongs to a person.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='faceId1'>
/// FaceId of the first face, comes from Face - Detect
/// </param>
/// <param name='faceId2'>
/// FaceId of the second face, comes from Face - Detect
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <VerifyResult> VerifyFaceToFaceAsync(this IFaceOperations operations, System.Guid faceId1, System.Guid faceId2, CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.VerifyFaceToFaceWithHttpMessagesAsync(faceId1, faceId2, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// 1-to-many identification to find the closest matches of the specific query
/// person face from a person group or large person group.
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='faceIds'>
/// Array of query faces faceIds, created by the Face - Detect. Each of the
/// faces are identified independently. The valid number of faceIds is between
/// [1, 10].
/// </param>
/// <param name='personGroupId'>
/// PersonGroupId of the target person group, created by PersonGroup - Create.
/// Parameter personGroupId and largePersonGroupId should not be provided at
/// the same time.
/// </param>
/// <param name='largePersonGroupId'>
/// LargePersonGroupId of the target large person group, created by
/// LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId
/// should not be provided at the same time.
/// </param>
/// <param name='maxNumOfCandidatesReturned'>
/// The range of maxNumOfCandidatesReturned is between 1 and 5 (default is 1).
/// </param>
/// <param name='confidenceThreshold'>
/// Confidence threshold of identification, used to judge whether one face
/// belong to one person. The range of confidenceThreshold is [0, 1] (default
/// specified by algorithm).
/// </param>
/// <param name='cancellationToken'>
/// The cancellation token.
/// </param>
public static async Task <IList <IdentifyResult> > IdentifyAsync(this IFaceOperations operations, IList <System.Guid> faceIds, string personGroupId = default(string), string largePersonGroupId = default(string), int?maxNumOfCandidatesReturned = 1, double?confidenceThreshold = default(double?), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.IdentifyWithHttpMessagesAsync(faceIds, personGroupId, largePersonGroupId, maxNumOfCandidatesReturned, confidenceThreshold, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
/// <summary>
/// Detect human faces in an image, return face rectangles, and optionally with
/// faceIds, landmarks, and attributes.<br />
/// * No image will be stored. Only the extracted face feature will be stored
/// on server. The faceId is an identifier of the face feature and will be used
/// in [Face -
/// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239),
/// [Face -
/// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
/// and [Face - Find
/// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237).
/// The stored face feature(s) will expire and be deleted 24 hours after the
/// original detection call.
/// * Optional parameters include faceId, landmarks, and attributes. Attributes
/// include age, gender, headPose, smile, facialHair, glasses, emotion, hair,
/// makeup, occlusion, accessories, blur, exposure and noise. Some of the
/// results returned for specific attributes may not be highly accurate.
/// * JPEG, PNG, GIF (the first frame), and BMP format are supported. The
/// allowed image file size is from 1KB to 6MB.
/// * Up to 100 faces can be returned for an image. Faces are ranked by face
/// rectangle size from large to small.
/// * For optimal results when querying [Face -
/// Identify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239),
/// [Face -
/// Verify](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523a),
/// and [Face - Find
/// Similar](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237)
/// ('returnFaceId' is true), please use faces that are: frontal, clear, and
/// with a minimum size of 200x200 pixels (100 pixels between eyes).
/// * The minimum detectable face size is 36x36 pixels in an image no larger
/// than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels
/// will need a proportionally larger minimum face size.
/// * Different 'detectionModel' values can be provided. To use and compare
/// different detection models, please refer to [How to specify a detection
/// model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-detection-model)
/// | Model | Recommended use-case(s) |
/// | ---------- | -------- |
/// | 'detection_01': | The default detection model for [Face -
/// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
/// Recommend for near frontal face detection. For scenarios with exceptionally
/// large angle (head-pose) faces, occluded faces or wrong image orientation,
/// the faces in such cases may not be detected. |
/// | 'detection_02': | Detection model released in 2019 May with improved
/// accuracy especially on small, side and blurry faces. |
///
/// * Different 'recognitionModel' values are provided. If follow-up operations
/// like Verify, Identify, Find Similar are needed, please specify the
/// recognition model with 'recognitionModel' parameter. The default value for
/// 'recognitionModel' is 'recognition_01', if latest model needed, please
/// explicitly specify the model you need in this parameter. Once specified,
/// the detected faceIds will be associated with the specified recognition
/// model. More details, please refer to [How to specify a recognition
/// model](https://docs.microsoft.com/en-us/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model)
/// | Model | Recommended use-case(s) |
/// | ---------- | -------- |
/// | 'recognition_01': | The default recognition model for [Face -
/// Detect](/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236).
/// All those faceIds created before 2019 March are bonded with this
/// recognition model. |
/// | 'recognition_02': | Recognition model released in 2019 March.
/// 'recognition_02' is recommended since its overall accuracy is improved
/// compared with 'recognition_01'. |
/// </summary>
/// <param name='operations'>
/// The operations group for this extension method.
/// </param>
/// <param name='url'>
/// Publicly reachable URL of an image
/// </param>
/// <param name='returnFaceId'>
/// A value indicating whether the operation should return faceIds of detected
/// faces.
/// </param>
/// <param name='returnFaceLandmarks'>
/// A value indicating whether the operation should return landmarks of the
/// detected faces.
/// </param>
/// <param name='returnFaceAttributes'>
/// Analyze and return the one or more specified face attributes in the
/// comma-separated string like "returnFaceAttributes=age,gender". Supported
/// face attributes include age, gender, headPose, smile, facialHair, glasses
/// and emotion. Note that each face attribute analysis has additional
/// computational and time cost.
/// </param>
/// <param name='recognitionModel'>
/// 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'
/// </param>
/// <param name='returnRecognitionModel'>
/// A value indicating whether the operation should return 'recognitionModel'
/// in response.
/// </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 <IList <DetectedFace> > DetectWithUrlAsync(this IFaceOperations operations, string url, bool?returnFaceId = true, bool?returnFaceLandmarks = false, IList <FaceAttributeType> returnFaceAttributes = default(IList <FaceAttributeType>), string recognitionModel = default(string), bool?returnRecognitionModel = false, string detectionModel = default(string), CancellationToken cancellationToken = default(CancellationToken))
{
using (var _result = await operations.DetectWithUrlWithHttpMessagesAsync(url, returnFaceId, returnFaceLandmarks, returnFaceAttributes, recognitionModel, returnRecognitionModel, detectionModel, null, cancellationToken).ConfigureAwait(false))
{
return(_result.Body);
}
}
