/// <summary>
/// List all persons’ information in the specified person group, including personId, name, userData and persistedFaceIds of registered person faces.
/// </summary>
/// <param name="personGroupId">personGroupId of the target person group.</param>
/// <param name="start">List persons from the least personId greater than the "start". It contains no more than 64 characters. Default is empty.</param>
/// <param name="top">The number of persons to list, ranging in [1, 1000]. Default is 1000.</param>
/// <returns>A successful call returns an array of person information that belong to the person group. </returns>
public static async Task <PersonInfo[]> GetPersonListAsync(string personGroupId, string start = "", int top = 1000)
{
var query = string.Format(GetPersonQuery, FaceApiClient.ResourceRegion.ToString().ToLower(), personGroupId, string.Format("?start={0}&top={1}", start, top));
Rest.Response response = await Rest.GetAsync(query, FaceApiClient.FaceApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <PersonList>(string.Format("{{\"People\":{0}}}", response.ResponseBody)).People : null);
}
/// <summary>
/// Retrieve a person's name and userData, and the persisted faceIds representing the registered person face image.
/// </summary>
/// <param name="personGroupId">Specifying the person group containing the target person.</param>
/// <param name="personId">Specifying the target person.</param>
/// <returns>A successful call returns the person's information.</returns>
public static async Task <PersonInfo?> GetPersonAsync(string personGroupId, string personId)
{
var query = string.Format(GetPersonQuery, FaceApiClient.ResourceRegion.ToString().ToLower(), personGroupId, "/" + personId);
Rest.Response response = await Rest.GetAsync(query, FaceApiClient.FaceApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <PersonInfo>(response.ResponseBody) : (PersonInfo?)null);
}
/// <summary>
/// To check person group training status completed or still ongoing.
/// </summary>
/// <param name="personGroupId">personGroupId of target person group.</param>
/// <returns>A successful call returns the person group's training status.</returns>
public static async Task <TrainingStatus?> GetTrainingStatusAsync(string personGroupId)
{
var query = string.Format(TrainingStatusQuery, FaceApiClient.ResourceRegion.ToString().ToLower(), personGroupId);
Rest.Response response = await Rest.GetAsync(query, FaceApiClient.ApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <TrainingStatus>(response.ResponseBody) : (TrainingStatus?)null);
}
/// <summary>
/// List person groups’s personGroupId, name, and userData.
/// </summary>
/// <param name="start">List person groups from the least personGroupId greater than the "start". It contains no more than 64 characters. Default is empty.</param>
/// <param name="top">The number of person groups to list, ranging in [1, 1000]. Default is 1000.</param>
/// <returns>A successful call returns an array of person groups and their information (personGroupId, name and userData).</returns>
public static async Task <PersonGroupInfo[]> GetGroupListAsync(string start = "", int top = 1000)
{
string query = string.Format(PersonListQuery, FaceApiClient.ResourceRegion, start, top);
Rest.Response response = await Rest.GetAsync(query, FaceApiClient.ApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <PersonGroupList>(string.Format("{{\"PersonGroups\":{0}}}", response.ResponseBody)).PersonGroups : null);
}
/// <summary>
/// Add a face image to a person into a person group for face identification or verification. To deal with the image of multiple faces, input face
/// can be specified as an image with a targetFace rectangle. It returns a persistedFaceId representing the added face. The face image and related
/// info will be stored on server until PersonGroup PersonFace - Delete, PersonGroup Person - Delete or PersonGroup - Delete is called.
/// </summary>
/// <param name="personId">Target person that the face is added to.</param>
/// <param name="personGroupId">Specifying the person group containing the target person.</param>
/// <param name="imageData">Face image data. Valid image size is from 1KB to 4MB. Only one face is allowed per image.</param>
/// <param name="userData">User-specified data about the target face to add 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>
/// <returns>A successful call returns the new persistedFaceId.</returns>
public static async Task <string> CreateFaceAsync(string personId, string personGroupId, byte[] imageData, string userData = "", FaceRectangle targetFace = null)
{
string args = string.Format("?userData={0}&targetFace={1}", userData, targetFace);
var query = string.Format(PersistedFacesQuery, FaceApiClient.ResourceRegion.ToString().ToLower(), personGroupId, personId, args);
Rest.Response response = await Rest.PostAsync(query, imageData, FaceApiClient.FaceApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <PersistedFaceInfo>(response.ResponseBody).persistedFaceId : string.Empty);
}
/// <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="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="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="maxNumOfCandidatesReturned">The range of maxNumOfCandidatesReturned is between 1 and 100 (default is 10).</param>
/// <param name="confidenceThreshold">Customized identification confidence threshold, in the range of [0, 1]. Advanced user can tweak
/// this value to override default internal threshold for better precision on their scenario data. Note there is no guarantee of this
/// threshold value working on other data and after algorithm updates.</param>
/// <returns>1-to-many identification to find the closest matches of the specific query person face from a person group.</returns>
public static async Task <IdentifyResult[]> IdentifyAsync
(string[] faceIds, string personGroupId, int maxNumOfCandidatesReturned = 10, float confidenceThreshold = 0f)
{
var query = string.Format(IdentityQuery, FaceApiClient.ResourceRegion.ToString().ToLower());
var json = JsonUtility.ToJson(new IdentifyRequest(faceIds, personGroupId, maxNumOfCandidatesReturned, confidenceThreshold));
Rest.Response response = await Rest.PostAsync(query, json, FaceApiClient.FaceApiKeyHeader);
if (!response.Successful)
{
throw new InvalidOperationException(response.ResponseBody);
}
return(JsonUtility.FromJson <IdentifyResultList>(string.Format("{{\"Results\":{0}}}", response.ResponseBody)).Results);
}
/// <summary>
/// Create a new person in a specified person group.
/// </summary>
/// <param name="personName">Display name of the target person. The maximum length is 128.</param>
/// <param name="personGroupId">Specifying the target person group to create the person.</param>
/// <param name="userData">Optional fields for user-provided data attached to a person. Size limit is 16KB.</param>
/// <returns>A successful call returns a new personId created.</returns>
public static async Task <string> CreatePersonAsync(string personName, string personGroupId, string userData = "")
{
if (personName.Length > 128)
{
personName = personName.Substring(0, 128);
}
var query = string.Format(GetPersonQuery, FaceApiClient.ResourceRegion.ToString().ToLower(), personGroupId, "");
var json = JsonUtility.ToJson(new CreatePerson(personName, userData));
Rest.Response response = await Rest.PostAsync(query, json, FaceApiClient.FaceApiKeyHeader);
return(response.Successful ? JsonUtility.FromJson <PersonId>(response.ResponseBody).personId : string.Empty);
}
/// <summary>
/// Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.<para/>
///
/// Optional parameters including faceId, landmarks, and attributes. Attributes include age, gender, headPose, smile, facialHair,
/// glasses, emotion, hair, makeup, occlusion, accessories, blur, exposure and noise.<para/>
/// </summary>
/// <param name="imageData">Ray byte data of the image to use to detect the face.</param>
/// <param name="returnFaceId">Return faceIds of the detected faces or not. The default value is true.</param>
/// <param name="returnFaceLandmarks">Return face landmarks of the detected faces or not. The default value is false.</param>
/// <param name="returnFaceAttributes">Analyze and return the one or more specified face attributes.
/// Face attribute analysis has additional computational and time cost.</param>
/// <returns>A successful call returns an array of face entries ranked by face rectangle size in descending order.
/// An empty response indicates no faces detected.</returns>
public static async Task <FaceInfo[]> DetectAsync
(byte[] imageData, bool returnFaceId = true, bool returnFaceLandmarks = false, FaceAttributes returnFaceAttributes = FaceAttributes.None)
{
var query = string.Format("{0}{1}{2}",
string.Format(DetectQuery, FaceApiClient.ResourceRegion.ToString().ToLower()),
string.Format("?returnFaceId={0}&returnFaceLandmarks={1}", returnFaceId, returnFaceLandmarks),
ParseFaceAttributes(returnFaceAttributes));
Rest.Response response = await Rest.PostAsync(query, imageData, FaceApiClient.FaceApiKeyHeader);
if (!response.Successful)
{
throw new InvalidOperationException(response.ResponseBody);
}
return(JsonUtility.FromJson <FaceList>(string.Format("{{\"Faces\":{0}}}", response.ResponseBody)).Faces);
}