Faces Interface

Package:

com.microsoft.azure.cognitiveservices.vision.faceapi

public interface Faces

An instance of this class provides access to all the operations defined in Faces.

Method Summary

Modifier and Type	Method and Description
FacesDetectWithStreamDefinitionStages.WithImage	detectWithStream() Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
List<DetectedFace>	detectWithStream(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter) Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
Observable<List<DetectedFace>>	detectWithStreamAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter) Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
FacesDetectWithUrlDefinitionStages.WithUrl	detectWithUrl() Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
List<DetectedFace>	detectWithUrl(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter) Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
Observable<List<DetectedFace>>	detectWithUrlAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter) Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.
FacesFindSimilarDefinitionStages.WithFaceId	findSimilar() Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.
List<SimilarFace>	findSimilar(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter) Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.
Observable<List<SimilarFace>>	findSimilarAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter) Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.
GroupResult	group(List<UUID> faceIds) Divide candidate faces into groups based on face similarity.
Observable<GroupResult>	groupAsync(List<UUID> faceIds) Divide candidate faces into groups based on face similarity.
FacesIdentifyDefinitionStages.WithPersonGroupId	identify() Identify unknown faces from a person group.
List<IdentifyResult>	identify(String personGroupId, List<UUID> faceIds, IdentifyOptionalParameter identifyOptionalParameter) Identify unknown faces from a person group.
Observable<List<IdentifyResult>>	identifyAsync(String personGroupId, List<UUID> faceIds, IdentifyOptionalParameter identifyOptionalParameter) Identify unknown faces from a person group.
VerifyResult	verifyFaceToFace(UUID faceId1, UUID faceId2) Verify whether two faces belong to a same person or whether one face belongs to a person.
Observable<VerifyResult>	verifyFaceToFaceAsync(UUID faceId1, UUID faceId2) Verify whether two faces belong to a same person or whether one face belongs to a person.
VerifyResult	verifyFaceToPerson(UUID faceId, String personGroupId, UUID personId) Verify whether two faces belong to a same person. Compares a face Id with a Person Id.
Observable<VerifyResult>	verifyFaceToPersonAsync(UUID faceId, String personGroupId, UUID personId) Verify whether two faces belong to a same person. Compares a face Id with a Person Id.

Method Details

detectWithStream

public FacesDetectWithStreamDefinitionStages.WithImage detectWithStream()

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Returns:

the first stage of the detectWithStream call

detectWithStream

public List detectWithStream(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter)

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:

image - An image stream.

detectWithStreamOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the List<DetectedFace> object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

detectWithStreamAsync

public Observable<>> detectWithStreamAsync(byte[] image, DetectWithStreamOptionalParameter detectWithStreamOptionalParameter)

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:

image - An image stream.

detectWithStreamOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the observable to the List<DetectedFace> object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

detectWithUrl

public FacesDetectWithUrlDefinitionStages.WithUrl detectWithUrl()

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Returns:

the first stage of the detectWithUrl call

detectWithUrl

public List detectWithUrl(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter)

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:

url - Publicly reachable URL of an image.

detectWithUrlOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the List<DetectedFace> object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

detectWithUrlAsync

public Observable<>> detectWithUrlAsync(String url, DetectWithUrlOptionalParameter detectWithUrlOptionalParameter)

Detect human faces in an image and returns face locations, and optionally with faceIds, landmarks, and attributes.

Parameters:

url - Publicly reachable URL of an image.

detectWithUrlOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the observable to the List<DetectedFace> object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

findSimilar

public FacesFindSimilarDefinitionStages.WithFaceId findSimilar()

Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.

Returns:

the first stage of the findSimilar call

findSimilar

public List findSimilar(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter)

Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.

Parameters:

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.

findSimilarOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the List<SimilarFace> object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

findSimilarAsync

public Observable<>> findSimilarAsync(UUID faceId, FindSimilarOptionalParameter findSimilarOptionalParameter)

Given query face's faceId, find the similar-looking faces from a faceId array or a faceListId.

Parameters:

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.

findSimilarOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the observable to the List<SimilarFace> object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

group

public GroupResult group(List faceIds)

Divide candidate faces into groups based on face similarity.

Parameters:

faceIds - Array of candidate faceId created by Face - Detect. The maximum is 1000 faces.

Returns:

the GroupResult object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

groupAsync

public Observable groupAsync(List faceIds)

Divide candidate faces into groups based on face similarity.

Parameters:

faceIds - Array of candidate faceId created by Face - Detect. The maximum is 1000 faces.

Returns:

the observable to the GroupResult object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

identify

public FacesIdentifyDefinitionStages.WithPersonGroupId identify()

Identify unknown faces from a person group.

Returns:

the first stage of the identify call

identify

public List identify(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter)

Identify unknown faces from a person group.

Parameters:

personGroupId - PersonGroupId of the target person group, created by PersonGroups.Create.

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].

identifyOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the List<IdentifyResult> object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

identifyAsync

public Observable<>> identifyAsync(String personGroupId, List faceIds, IdentifyOptionalParameter identifyOptionalParameter)

Identify unknown faces from a person group.

Parameters:

personGroupId - PersonGroupId of the target person group, created by PersonGroups.Create.

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].

identifyOptionalParameter - the object representing the optional parameters to be set before calling this API

Returns:

the observable to the List<IdentifyResult> object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

verifyFaceToFace

public VerifyResult verifyFaceToFace(UUID faceId1, UUID faceId2)

Verify whether two faces belong to a same person or whether one face belongs to a person.

Parameters:

faceId1 - FaceId of the first face, comes from Face - Detect.

faceId2 - FaceId of the second face, comes from Face - Detect.

Returns:

the VerifyResult object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

verifyFaceToFaceAsync

public Observable verifyFaceToFaceAsync(UUID faceId1, UUID faceId2)

Verify whether two faces belong to a same person or whether one face belongs to a person.

Parameters:

faceId1 - FaceId of the first face, comes from Face - Detect.

faceId2 - FaceId of the second face, comes from Face - Detect.

Returns:

the observable to the VerifyResult object

Throws:

IllegalArgumentException - thrown if parameters fail the validation

verifyFaceToPerson

public VerifyResult verifyFaceToPerson(UUID faceId, String personGroupId, UUID personId)

Verify whether two faces belong to a same person. Compares a face Id with a Person Id.

Parameters:

faceId - FaceId the face, comes from Face - Detect.

personGroupId - Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create.

personId - Specify a certain person in a person group. personId is created in Persons.Create.

Returns:

the VerifyResult object if successful.

Throws:

IllegalArgumentException - thrown if parameters fail the validation

APIErrorException - thrown if the request is rejected by server

RuntimeException - all other wrapped checked exceptions if the request fails to be sent

verifyFaceToPersonAsync

public Observable verifyFaceToPersonAsync(UUID faceId, String personGroupId, UUID personId)

Verify whether two faces belong to a same person. Compares a face Id with a Person Id.

Parameters:

faceId - FaceId the face, comes from Face - Detect.

personGroupId - Using existing personGroupId and personId for fast loading a specified person. personGroupId is created in Person Groups.Create.

personId - Specify a certain person in a person group. personId is created in Persons.Create.

Returns:

the observable to the VerifyResult object

Throws:

IllegalArgumentException - thrown if parameters fail the validation