FaceClient.Group Method

  • Reference

Definition

Namespace:
Azure.AI.Vision.Face
Assembly:
Azure.AI.Vision.Face.dll
Package:
Azure.AI.Vision.Face v1.0.0-beta.1

Overloads

Group(RequestContent, RequestContext)

[Protocol Method] Divide candidate faces into groups based on face similarity.
Group(IEnumerable<Guid>, CancellationToken)

Divide candidate faces into groups based on face similarity.

Group(RequestContent, RequestContext)

Source:
FaceClient.cs

[Protocol Method] Divide candidate faces into groups based on face similarity.

public virtual Azure.Response Group (Azure.Core.RequestContent content, Azure.RequestContext context = default);
abstract member Group : Azure.Core.RequestContent * Azure.RequestContext -> Azure.Response
override this.Group : Azure.Core.RequestContent * Azure.RequestContext -> Azure.Response
Public Overridable Function Group (content As RequestContent, Optional context As RequestContext = Nothing) As Response

Parameters

content
RequestContent

The content to send as the body of the request.

context
RequestContext

The request context, which can override default behaviors of the client pipeline on a per-call basis.

Returns

Response

The response returned from the service.

Exceptions

ArgumentNullException

content is null.

RequestFailedException

Service returned a non-success status code.

Examples

This sample shows how to call Group and parse the result.

Uri endpoint = new Uri("<https://my-service.azure.com>");
AzureKeyCredential credential = new AzureKeyCredential("<key>");
FaceClient client = new FaceClient(endpoint, credential);

using RequestContent content = RequestContent.Create(new
{
    faceIds = new object[]
    {
        "73f411fe-4f43-4b4b-9cbd-6828d8f4cf9a"
    },
});
Response response = client.Group(content);

JsonElement result = JsonDocument.Parse(response.ContentStream).RootElement;
Console.WriteLine(result.GetProperty("groups")[0][0].ToString());
Console.WriteLine(result.GetProperty("messyGroup")[0].ToString());

This sample shows how to call Group with all request content and parse the result.

Uri endpoint = new Uri("<https://my-service.azure.com>");
AzureKeyCredential credential = new AzureKeyCredential("<key>");
FaceClient client = new FaceClient(endpoint, credential);

using RequestContent content = RequestContent.Create(new
{
    faceIds = new object[]
    {
        "73f411fe-4f43-4b4b-9cbd-6828d8f4cf9a"
    },
});
Response response = client.Group(content);

JsonElement result = JsonDocument.Parse(response.ContentStream).RootElement;
Console.WriteLine(result.GetProperty("groups")[0][0].ToString());
Console.WriteLine(result.GetProperty("messyGroup")[0].ToString());

Applies to

Group(IEnumerable<Guid>, CancellationToken)

Source:
FaceClient.cs

Divide candidate faces into groups based on face similarity.

public virtual Azure.Response<Azure.AI.Vision.Face.FaceGroupingResult> Group (System.Collections.Generic.IEnumerable<Guid> faceIds, System.Threading.CancellationToken cancellationToken = default);
abstract member Group : seq<Guid> * System.Threading.CancellationToken -> Azure.Response<Azure.AI.Vision.Face.FaceGroupingResult>
override this.Group : seq<Guid> * System.Threading.CancellationToken -> Azure.Response<Azure.AI.Vision.Face.FaceGroupingResult>
Public Overridable Function Group (faceIds As IEnumerable(Of Guid), Optional cancellationToken As CancellationToken = Nothing) As Response(Of FaceGroupingResult)

Parameters

faceIds
IEnumerable<Guid>

Array of candidate faceIds created by "Detect". The maximum is 1000 faces.

cancellationToken
CancellationToken

The cancellation token to use.

Returns

Response<FaceGroupingResult>

Exceptions

ArgumentNullException

faceIds is null.

Examples

This sample shows how to call Group.

Uri endpoint = new Uri("<https://my-service.azure.com>");
AzureKeyCredential credential = new AzureKeyCredential("<key>");
FaceClient client = new FaceClient(endpoint, credential);

Response<FaceGroupingResult> response = client.Group(new Guid[] { Guid.Parse("73f411fe-4f43-4b4b-9cbd-6828d8f4cf9a") });

This sample shows how to call Group with all parameters.

Uri endpoint = new Uri("<https://my-service.azure.com>");
AzureKeyCredential credential = new AzureKeyCredential("<key>");
FaceClient client = new FaceClient(endpoint, credential);

Response<FaceGroupingResult> response = client.Group(new Guid[] { Guid.Parse("73f411fe-4f43-4b4b-9cbd-6828d8f4cf9a") });

Remarks

> * * 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 "Verify Face To Face" when you only have 2 candidate faces. * The 'recognitionModel' associated with the query faces' faceIds should be the same.

Applies to