예: 이미지에서 얼굴을 식별하는 방법Example: How to identify faces in images

이 가이드에서는 미리 알려진 사람들로 만든 PersonGroups를 사용하여 알 수 없는 얼굴을 식별하는 방법을 보여 줍니다.This guide demonstrates how to identify unknown faces using PersonGroups, which are created from known people in advance. 샘플은 Face API 클라이언트 라이브러리를 사용하여 C#에서 작성되었습니다.The samples are written in C# using the Face API client library.

개념Concepts

이 가이드에서 다음 개념에 대해 익숙지 않다면 언제든지 용어집에 나와 있는 정의를 검색하세요.If you are not familiar with the following concepts in this guide, please search for the definitions in our glossary at any time:

  • 얼굴 - 감지Face - Detect
  • 얼굴 - 식별Face - Identify
  • PersonGroupPersonGroup

준비Preparation

이 샘플에서는 다음에 대해 설명합니다.In this sample, we demonstrate the following:

  • PersonGroup을 만드는 방법 - 이 PersonGroup에는 알려진 사용자 목록이 포함되어 있습니다.How to create a 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. 사진 ID와 마찬가지로, 선명한 정면 얼굴을 사용하는 것이 좋습니다.It is recommended to use clear front faces, just like your photo ID. 좋은 사진 모음에는 다른 동작을 하거나, 다른 색상의 옷을 입거나, 다른 머리 스타일을 하고 있는 같은 사람의 얼굴이 포함되어 있습니다.A good set of photos should contain faces of the same person in different poses, clothes' colors or hair styles.

이 샘플의 데모를 수행하려면 다음과 같은 여러 장의 사진을 준비해야 합니다.To carry out the demonstration of this sample, you need to prepare a bunch of pictures:

  • 사람 얼굴을 포함하는 몇 장의 사진.A few photos with the person's face. Anna, Bill 및 Clare의 샘플 사진을 다운로드하려면 여기를 클릭하세요.Click here to download sample photos for Anna, Bill, and Clare.
  • 식별을 테스트하는 데 사용되는 Anna, Bill 또는 Clare의 얼굴을 포함하거나 포함하지 않을 수 있는 일련의 테스트 사진.A series of test photos, which may or may not contain the faces of Anna, Bill or Clare used to test identification. 이전 링크에서 일부 샘플 이미지를 선택할 수도 있습니다.You can also select some sample images from the preceding link.

1단계: API 호출 권한 부여Step 1: Authorize the API call

Face 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을 참조하세요. 다음은 예제입니다.To pass the subscription key through query string, please refer to 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: <Subscription Key> 클라이언트 라이브러리를 사용할 경우 구독 키가 FaceServiceClient 클래스의 생성자를 통해 전달됩니다.As an alternative, the subscription key can also be specified in the HTTP request header: ocp-apim-subscription-key: <Subscription Key> When using a client library, the subscription key is passed in through the constructor of the FaceServiceClient class. 예: For example:

faceServiceClient = new FaceServiceClient("<Subscription Key>");

구독 키는 Azure Portal의 Marketplace 페이지에서 얻을 수 있습니다.The subscription key can be obtained from the Marketplace page of your Azure portal. 구독을 참조하세요.See Subscriptions.

2단계: PersonGroup 만들기Step 2: Create the PersonGroup

이 단계에서는 세 명의 사용자인 Anna, Bill, Clare를 포함하는 "MyFriends"라는 PersonGroup을 만들었습니다.In this step, we created a PersonGroup named "MyFriends" that contains three people: Anna, Bill, and Clare. 각 사람은 몇 개의 얼굴을 등록했습니다.Each person has several faces registered. 얼굴은 이미지에서 검색되어야 합니다.The faces need to be detected from the images. 이러한 모든 단계를 수행하면 다음 이미지와 같은 PersonGroup이 생성됩니다.After all of these steps, you have a PersonGroup like the following image:

HowToIdentify1

2.1 PersonGroup에 대한 사람 정의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은 사람들의 모음이며, 각 사람은 특정 PersonGroup 내에서 정의됩니다.However, a PersonGroup is a collection of people, and each person is defined within a particular PersonGroup. 식별은 PersonGroup에 대해 수행됩니다.The identification is done against a PersonGroup. 따라서 PersonGroup을 만들고, 여기에 Anna, Bill, Clare와 같은 사람을 만듭니다.So, the task is to create a PersonGroup, and then create people in it, such as Anna, Bill, and Clare.

먼저 새 PersonGroup을 만들어야 합니다.First, you need to create a new PersonGroup. 이 작업은 PersonGroup - 만들기 API를 사용하여 실행됩니다.This is executed by using the PersonGroup - Create API. 해당 클라이언트 라이브러리 API는 FaceServiceClient 클래스에 대한 CreatePersonGroupAsync 메서드입니다.The corresponding client library API is the CreatePersonGroupAsync method for the FaceServiceClient class. 그룹을 만들기 위해 지정된 그룹 ID는 각 구독에 대해 고유합니다. 따라서 다른 PersonGroup API를 사용하여 PersonGroup을 가져오거나 업데이트하거나 삭제할 수도 있습니다.The group ID specified to create the group is unique for each subscription –you can also get, update, or delete PersonGroups using other PersonGroup APIs. 그룹이 정의되면, PersonGroup Person - 만들기 API를 사용하여 그룹 안에 사람을 정의할 수 있습니다.Once a group is defined, people can then be defined within it by using the PersonGroup Person - Create API. 클라이언트 라이브러리 메서드는 CreatePersonAsync입니다.The client library method is CreatePersonAsync. 각 사용자를 만든 후에는 얼굴을 추가할 수 있습니다.You can add face to each person after they're created.

// Create an empty PersonGroup
string personGroupId = "myfriends";
await faceServiceClient.CreatePersonGroupAsync(personGroupId, "My Friends");

// Define Anna
CreatePersonResult friend1 = await faceServiceClient.CreatePersonAsync(
    // 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 얼굴을 감지한 후 올바른 사람에게 등록2.2 Detect faces and register them to correct person

감지는 HTTP 요청 본문에 이미지 파일을 사용하여 얼굴 - 감지 API로 "POST" 웹 요청을 전송하여 진행됩니다.Detection is done by sending a "POST" web request to the Face - Detect API with the image file in the HTTP request body. 클라이언트 라이브러리를 사용할 때는 FaceServiceClient 클래스에 대한 DetectAsync 메서드를 통해 얼굴 감지가 실행됩니다.When using the client library, face detection is executed through the DetectAsync method for the FaceServiceClient class.

감지된 각 얼굴에 대해 PersonGroup Person – 얼굴 추가를 호출하여 올바른 사용자에게 추가할 수 있습니다.For each face detected you can 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 faceServiceClient.AddPersonFaceAsync(
            personGroupId, friend1.PersonId, s);
    }
}
// Do the same for Bill and Clare

이미지에 둘 이상의 얼굴이 포함되어 있는 경우 가장 큰 얼굴만 추가됩니다.Notice that if the image contains more than one face, only the largest face is added. "targetFace = left, top, width, height" 형식의 문자열을 PersonGroup Person - 얼굴 추가 API의 targetFace 쿼리 매개 변수에 제공하거나, AddPersonFaceAsync 메서드에 대해 targetFace 선택적 매개 변수를 사용하여 사람에게 다른 얼굴을 추가할 수 있습니다.You can add other faces to the person by passing a string in the format of "targetFace = left, top, width, height" to PersonGroup Person - Add Face API's targetFace query parameter, or using the targetFace optional parameter for the AddPersonFaceAsync method to add other faces. 사람에게 추가한 각 얼굴에는 고유한 지속형 얼굴 ID가 지정되며 이 ID는 PersonGroup Person – 얼굴 삭제얼굴 - 식별에서 사용될 수 있습니다.Each face added to the person will be given a unique persisted face ID, which can be used in PersonGroup Person – Delete Face and Face – Identify.

3단계: PersonGroup 학습Step 3: Train the PersonGroup

PersonGroup을 사용하여 식별을 수행하려면 먼저 PersonGroup이 학습되어야 합니다.The PersonGroup must be trained before an identification can be performed using it. 그뿐 아니라 사람을 추가 또는 제거한 후에나 사람의 등록된 얼굴이 편집된 경우 다시 학습되어야 합니다.Moreover, it has to be retrained after adding or removing any person, or if any person has their registered face edited. 학습은 PersonGroup – 학습 API를 통해 수행됩니다.The training is done by the PersonGroup – Train API. 클라이언트 라이브러리를 사용할 때 다음과 같이 TrainPersonGroupAsync 메서드를 호출하기만 하면 됩니다.When using the client library, it is simply a call to the TrainPersonGroupAsync method:

await faceServiceClient.TrainPersonGroupAsync(personGroupId);

학습은 비동기 프로세스입니다.The training is an asynchronous process. TrainPersonGroupAsync 메서드가 반환된 후에도 완료되지 않을 수 있습니다.It may not be finished even after the TrainPersonGroupAsync method returned. PersonGroup - 학습 상태 가져오기 API 또는 클라이언트 라이브러리의 GetPersonGroupTrainingStatusAsync 메서드를 사용하여 학습 상태를 쿼리해야 할 수도 있습니다.You may need to query the training status by PersonGroup - Get Training Status API or GetPersonGroupTrainingStatusAsync method of the client library. 다음 코드에서는 PersonGroup 학습이 완료될 때까지 기다리는 간단한 논리를 보여 줍니다.The following code demonstrates a simple logic of waiting PersonGroup training to finish:

TrainingStatus trainingStatus = null;
while(true)
{
    trainingStatus = await faceServiceClient.GetPersonGroupTrainingStatusAsync(personGroupId);

    if (trainingStatus.Status != Status.Running)
    {
        break;
    }

    await Task.Delay(1000);
} 

4단계: 정의된 PersonGroup에 대해 얼굴 식별Step 4: Identify a face against a defined PersonGroup

식별을 수행할 때 Face API는 그룹 내의 모든 얼굴 중에서 테스트 얼굴의 유사성을 계산할 수 있으며, 해당 테스트 얼굴과 가장 비슷한 사람을 반환합니다.When performing identifications, the Face API can compute the similarity of a test face among all the faces within a group, and returns the most comparable person(s) for that testing face. 이 작업은 얼굴 - 식별 API 또는 클라이언트 라이브러리의 IdentifyAsync 메서드를 통해 수행됩니다.This is done through the Face - Identify API or the IdentifyAsync method of the client library.

테스트 얼굴이 이전 단계를 사용하여 감지되면 얼굴 ID가 또 다른 인수로서 식별 API로 전달됩니다.The testing face needs to be detected using the previous steps, and then the face ID is passed to the identify API as a second argument. 여러 얼굴 ID를 바로 식별할 수 있으며 결과에 모든 식별 결과가 포함됩니다.Multiple face IDs can be identified at once, and the result will contain all the identify results. 기본적으로 식별을 수행하면 테스트 얼굴과 가장 잘 일치하는 1명의 사람만 반환됩니다.By default, the identify returns only one person that matches the test face best. 원할 경우 선택적 매개 변수 maxNumOfCandidatesReturned를 지정하여 식별 기능이 더 많은 후보를 반환하도록 할 수 있습니다.If you prefer, you can specify the optional parameter maxNumOfCandidatesReturned to let the identify return more candidates.

다음 코드에서는 식별 프로세스를 보여 줍니다.The following code demonstrates the process of identify:

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

using (Stream s = File.OpenRead(testImageFile))
{
    var faces = await faceServiceClient.DetectAsync(s);
    var faceIds = faces.Select(face => face.FaceId).ToArray();

    var results = await faceServiceClient.IdentifyAsync(personGroupId, faceIds);
    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 faceServiceClient.GetPersonAsync(personGroupId, candidateId);
            Console.WriteLine("Identified as {0}", person.Name);
        }
    }
}

이러한 단계를 완료한 경우, 다른 얼굴을 식별해보고, 얼굴 감지를 위해 업로드된 이미지에 따라 Anna, Bill 또는 Clare의 얼굴이 올바르게 식별될 수 있는지 확인할 수 있습니다.When you have finished the steps, you can try to identify different faces and see if the faces of Anna, Bill or Clare can be correctly identified, according to the image(s) uploaded for face detection. 다음 예제를 참조하세요.See the following examples:

HowToIdentify2

5단계: 대규모에 대한 요청Step 5: Request for large-scale

알려진 것처럼 PersonGroup은 이전 디자인 제한점 때문에 최대 10,000명의 사람을 보유할 수 있습니다.As is known, a PersonGroup can hold up to 10,000 persons due to the limitation of previous design. 백만 명 규모까지 확장하는 시나리오에 대한 자세한 내용은 대규모 기능을 사용하는 방법을 참조하세요.For more information about up to million-scale scenarios, see How to use the large-scale feature.

요약Summary

이 가이드에서는 PersonGroup을 만들고 사람을 식별하는 프로세스를 배웠습니다.In this guide, you have learned the process of creating a PersonGroup and identifying a person. 다음 항목을 통해 앞에서 설명하고 시연한 기능을 다시 한 번 간략하게 살펴보시기 바랍니다.The following are a quick reminder of the features previously explained and demonstrated: