Пример: Идентификация лиц на изображенииExample: Identify faces in images

В этом руководстве показано, как идентифицировать неизвестные лица с помощью объектов PersonGroups, заранее созданных из изображений лиц знакомых людей.This guide demonstrates how to identify unknown faces by using PersonGroup objects, which are created from known people in advance. Примеры написаны на языке C# с использованием клиентской библиотеки API Распознавания лиц службы Azure Cognitive Services.The samples are written in C# by using the Azure Cognitive Services Face API client library.

ПодготовкаPreparation

В этом примере демонстрируются следующее:This sample demonstrates:

  • Как создать PersonGroup.How to create a PersonGroup. Объект PersonGroup содержит список знакомых людей.This PersonGroup contains a list of known people.
  • Как сопоставлять изображения лиц с определенными людьми.How to assign faces to each person. Изображения лица используются как основа для идентификации человека.These faces are used as a baseline to identify people. Мы рекомендуем использовать четкие снимки с лицами анфас.We recommend that you use clear frontal views of faces. Лучше всего подходят фотографии на документах.An example is a photo ID. Оптимальный набор состоит из фотографий лица одного человека в разных позах, в одежде разных цветов или с разными прическами.A good set of photos includes faces of the same person in different poses, clothing colors, or hairstyles.

Чтобы выполнить демонстрацию этого примера, подготовьте следующее:To carry out the demonstration of this sample, prepare:

  • Несколько фотографий с лицом человека.A few photos with the person's face. Скачайте примеры фотографий Анны, Билла и Клэр.Download sample photos for Anna, Bill, and Clare.
  • Серия тестовых фотографий.A series of test photos. Фотографии, на части которых есть лица Анны, Билла или Клэр.The photos might or might not contain the faces of Anna, Bill, or Clare. Они используются для тестирования идентификации.They're used to test identification. Выберите также некоторые примеры изображений из набора по ссылке выше.Also select some sample images from the preceding link.

Шаг 1. Авторизация вызова APIStep 1: Authorize the API call

Каждый вызов API распознавания лиц требует ключ подписки.Every call to the Face API requires a subscription key. Этот ключ может быть передан через параметр строки запроса или указан в заголовке запроса.This key can be either passed through a query string parameter or specified in the request header. Чтобы передать ключ подписки через строку запроса, изучите URL-адрес запроса Face-Detect в качестве примера.To pass the subscription key through a query string, see the request URL for the Face - Detect as an example:

https://westus.api.cognitive.microsoft.com/face/v1.0/detect[?returnFaceId][&returnFaceLandmarks][&returnFaceAttributes]
&subscription-key=<Subscription key>

Ключ подписки также можно указать в заголовке HTTP-запроса ocp-apim-subscription-key: <Ключ подписки> .As an alternative, specify the subscription key in the HTTP request header ocp-apim-subscription-key: <Subscription Key>. Если вы используете клиентскую библиотеку, ключ подписки передается через конструктор класса FaceClient.When you use a client library, the subscription key is passed in through the constructor of the FaceClient class. Например:For example:

private readonly IFaceClient faceClient = new FaceClient(
            new ApiKeyServiceClientCredentials("<subscription key>"),
            new System.Net.Http.DelegatingHandler[] { });

Чтобы получить ключ подписки, откройте Azure Marketplace через портал Azure.To get the subscription key, go to the Azure Marketplace from the Azure portal. Дополнительные сведения см. на странице Пробная версия Cognitive Services.For more information, see Subscriptions.

Шаг 2. Создание PersonGroupStep 2: Create the PersonGroup

На этом шаге объект PersonGroup с именем MyFriends содержит фотографии Анны, Билла и Клэр.In this step, a PersonGroup named "MyFriends" contains Anna, Bill, and Clare. Каждый пользователь имеет несколько зарегистрированных лиц.Each person has several faces registered. Лица должны распознаваться на изображениях.The faces must be detected from the images. После выполнения всех этих шагов у вас есть PersonGroup, как показано на следующем изображении:After all of these steps, you have a PersonGroup like the following image:

MyFriends

Шаг 2.1. Назначение людей в PersonGroupStep 2.1: Define people for the PersonGroup

Пользователь является базовой единицей идентификации.A person is a basic unit of identify. Для пользователя может быть зарегистрировано одно или несколько известных лиц.A person can have one or more known faces registered. PersonGroup — это совокупность людей.A PersonGroup is a collection of people. Каждый человек определяется в конкретной группе PersonGroup.Each person is defined within a particular PersonGroup. Идентификация выполняется по принадлежности к PersonGroup.Identification is done against a PersonGroup. Итак, нам нужно создать объект PersonGroup и добавить в него изображения людей, например Анны, Билла и Клэр.The task is to create a PersonGroup, and then create the people in it, such as Anna, Bill, and Clare.

Для начала создайте PersonGroup с помощью API-интерфейса PersonGroup — Create.First, create a new PersonGroup by using the PersonGroup - Create API. Соответствующим API клиентской библиотеки является метод CreatePersonGroupAsync для класса FaceClient.The corresponding client library API is the CreatePersonGroupAsync method for the FaceClient class. Идентификатор группы, указанный при ее создании, уникален для каждой подписки.The group ID that's specified to create the group is unique for each subscription. Вы можете извлекать, обновлять и удалять объекты PersonGroup через другие API-интерфейсы PersonGroup.You also can get, update, or delete PersonGroups by using other PersonGroup APIs.

Определив группу, вы можете назначить в нее людей с помощью API PersonGroup Person — Create.After a group is defined, you can define people within it by using the PersonGroup Person - Create API. Метод клиентской библиотеки — CreatePersonAsync.The client library method is CreatePersonAsync. Вы можете добавлять в PersonGroup изображения лица каждого человека из группы.You can add a face to each person after they're created.

// Create an empty PersonGroup
string personGroupId = "myfriends";
await faceClient.PersonGroup.CreateAsync(personGroupId, "My Friends");
 
// Define Anna
CreatePersonResult friend1 = await faceClient.PersonGroupPerson.CreateAsync(
    // Id of the PersonGroup that the person belonged to
    personGroupId,    
    // Name of the person
    "Anna"            
);
 
// Define Bill and Clare in the same way

Шаг 2.2. Распознавание лица и его сопоставление с определенным человекомStep 2.2: Detect faces and register them to the correct person

Обнаружение выполняется путем отправки веб-запроса POST в API Face — Detect с файлом изображения в теле запроса HTTP.Detection is done by sending a "POST" web request to the Face - Detect API with the image file in the HTTP request body. При использовании клиентской библиотеки распознавание лиц выполняется в методе DetectAsync из класса FaceClient.When you use the client library, face detection is done through the DetectAsync method for the FaceClient class.

Для каждого обнаруженного лица вызовите PersonGroup Person — Add Face, чтобы добавить его к соответствующему человеку.For each face that's detected, call PersonGroup Person – Add Face to add it to the correct person.

Следующий код демонстрирует процесс определения лица с изображения и добавления его к человеку:The following code demonstrates the process of how to detect a face from an image and add it to a person:

// Directory contains image files of Anna
const string friend1ImageDir = @"D:\Pictures\MyFriends\Anna\";
 
foreach (string imagePath in Directory.GetFiles(friend1ImageDir, "*.jpg"))
{
    using (Stream s = File.OpenRead(imagePath))
    {
        // Detect faces in the image and add to Anna
        await faceClient.PersonGroupPerson.AddFaceFromStreamAsync(
            personGroupId, friend1.PersonId, s);
    }
}
// Do the same for Bill and Clare

Если изображение содержит несколько лиц, добавляется только лицо с наибольшим размером.If the image contains more than one face, only the largest face is added. Вы можете добавить несколько изображений лиц для одного человека.You can add other faces to the person. Передайте строку в формате "targetFace = левый край, верхний край, ширина, высота" через параметр запроса targetFace для API-интерфейса PersonGroup Person — Add Face.Pass a string in the format of "targetFace = left, top, width, height" to PersonGroup Person - Add Face API's targetFace query parameter. Для добавления новых лиц также можно использовать необязательный параметр targetFace в методе AddPersonFaceAsync.You also can use the targetFace optional parameter for the AddPersonFaceAsync method to add other faces. Каждому добавленному лицу присваивается уникальный постоянный идентификатор лица.Each face added to the person is given a unique persisted face ID. Вы можете использовать этот идентификатор в интерфейсах PersonGroup Person — Delete Face и Face —Identify.You can use this ID in PersonGroup Person – Delete Face and Face – Identify.

Шаг 3. Обучение PersonGroupStep 3: Train the PersonGroup

Нужно выполнить обучение PersonGroup, чтобы идентификация работала правильно.The PersonGroup must be trained before an identification can be performed by using it. После добавления человека в PersonGroup, удаления его из группы или изменения зарегистрированного для него лица необходимо повторно выполнить обучение PersonGroup.The PersonGroup must be retrained after you add or remove any person or if you edit a person's registered face. Обучение выполняется API-интерфейсом PersonGroup — Train.The training is done by the PersonGroup – Train API. При использовании клиентской библиотеки достаточно вызвать метод TrainPersonGroupAsync:When you use the client library, it's a call to the TrainPersonGroupAsync method:

await faceClient.PersonGroup.TrainAsync(personGroupId);

Обучение является асинхронным процессом.Training is an asynchronous process. Оно может продолжаться даже после возврата метода TrainPersonGroupAsync.It might not be finished even after the TrainPersonGroupAsync method returns. Если нужно узнать текущее состояние обучения,You might need to query the training status. используйте для этого API PersonGroup — Get Training Status или метод GetPersonGroupTrainingStatusAsync из клиентской библиотеки.Use the PersonGroup - Get Training Status API or GetPersonGroupTrainingStatusAsync method of the client library. В следующем примере демонстрируется простая логика, ожидающая завершения обучения PersonGroup:The following code demonstrates a simple logic of waiting for PersonGroup training to finish:

TrainingStatus trainingStatus = null;
while(true)
{
    trainingStatus = await faceClient.PersonGroup.GetTrainingStatusAsync(personGroupId);
 
    if (trainingStatus.Status != TrainingStatusType.Running)
    {
        break;
    }
 
    await Task.Delay(1000);
} 

Шаг 4. Определение лица для определенной группы PersonGroupStep 4: Identify a face against a defined PersonGroup

При выполнении идентификаций API Распознавания лиц вычисляет сходство распознаваемого лица со всеми лицами в группе.When the Face API performs identifications, it computes the similarity of a test face among all the faces within a group. Оно возвращает людей с лицами, больше всего похожими на распознаваемое лицо.It returns the most comparable persons for the testing face. Этот процесс осуществляется через API Face — Identify или метод клиентской библиотеки IdentifyAsync.This process is done through the Face - Identify API or the IdentifyAsync method of the client library.

Распознаваемое лицо должно определяться на предыдущих шагах.The testing face must be detected by using the previous steps. Идентификатор лица передается в API идентификации в качестве второго аргумента.Then the face ID is passed to the identification API as a second argument. Можно определить несколько идентификаторов лица за раз.Multiple face IDs can be identified at once. Результат будет содержать все выявленные результаты.The result contains all the identified results. По умолчанию процесс идентификации возвращает только одного человека, которому лучше всего соответствует распознаваемое лицо.By default, the identification process returns only one person that matches the test face best. Вы можете указать необязательный параметр maxNumOfCandidatesReturned, чтобы процесс идентификации возвращал больше кандидатов.If you prefer, specify the optional parameter maxNumOfCandidatesReturned to let the identification process return more candidates.

Этот процесс идентификации показан в следующем коде:The following code demonstrates the identification process:

string testImageFile = @"D:\Pictures\test_img1.jpg";

using (Stream s = File.OpenRead(testImageFile))
{
    var faces = await faceClient.Face.DetectAsync(s);
    var faceIds = faces.Select(face => face.FaceId).ToArray();
 
    var results = await faceClient.Face.IdentifyAsync(faceIds, personGroupId);
    foreach (var identifyResult in results)
    {
        Console.WriteLine("Result of face: {0}", identifyResult.FaceId);
        if (identifyResult.Candidates.Length == 0)
        {
            Console.WriteLine("No one identified");
        }
        else
        {
            // Get top 1 among all candidates returned
            var candidateId = identifyResult.Candidates[0].PersonId;
            var person = await faceClient.PersonGroupPerson.GetAsync(personGroupId, candidateId);
            Console.WriteLine("Identified as {0}", person.Name);
        }
    }
}

Когда вы завершите шаги, попробуйте распознать разные лица.After you finish the steps, try to identify different faces. Выясните, удается ли правильно опознать лица Анны, Билла или Клэр по изображениям, загруженным для обнаружения лиц.See if the faces of Anna, Bill, or Clare can be correctly identified according to the images uploaded for face detection. Рассмотрим следующие примеры:See the following examples:

Идентификация разных лиц

Шаг 5. Запрос большого объемаStep 5: Request for large scale

Объект PersonGroup может содержать не более 10 000 человек из-за прежних конструктивных ограничений.A PersonGroup can hold up to 10,000 persons based on the previous design limitation. Дополнительную информацию о миллионных сценариях см. в статье How to use the large-scale feature (Как использовать функцию увеличения масштаба).For more information about up to million-scale scenarios, see How to use the large-scale feature.

СводкаSummary

В этом руководстве вы изучили процесс создания PersonGroup и идентификации человека.In this guide, you learned the process of creating a PersonGroup and identifying a person. Мы объяснили и продемонстрировали следующие возможности:The following features were explained and demonstrated: