예제: 이미지에서 얼굴 식별Example: Identify faces in images

이 가이드에서는 미리 알려진 사람으로부터 만들어진 PersonGroup 개체를 사용하여 알 수 없는 얼굴을 식별하는 방법을 보여 줍니다.This guide demonstrates how to identify unknown faces by using PersonGroup objects, which are created from known people in advance. 샘플은 Azure Cognitive Services Face API 클라이언트 라이브러리를 사용하여 C#으로 작성되었습니다.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. 예를 들어 사진 ID가 있습니다.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. Anna, Bill 및 Clare에 대한 샘플 사진을 다운로드합니다.Download sample photos for Anna, Bill, and Clare.
  • 일련의 테스트 사진.A series of test photos. 사진에는 Anna, Bill 또는 Clare의 얼굴이 포함되거나 포함되지 않을 수 있습니다.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단계: 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. 쿼리 문자열을 통해 구독 키를 전달하려면 다음 예제와 같은 Face - Detect에 대한 요청 URL을 참조하세요.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>

대안으로 구독 키를 ocp-apim-subscription-key: <구독 키> HTTP 요청 헤더에 지정합니다.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 Portal에서 Azure Marketplace로 이동합니다.To get the subscription key, go to the Azure Marketplace from the Azure portal. 자세한 내용은 구독을 참조하세요.For more information, see Subscriptions.

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

이 단계에서는 Anna, Bill 및 Clare가 "MyFriends"라는 PersonGroup에 포함됩니다.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단계: PersonGroup에 대한 사람 정의Step 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을 만든 다음, 여기에 Anna, Bill 및 Clare와 같은 사람을 만드는 것입니다.The task is to create a PersonGroup, and then create the people in it, such as Anna, Bill, and Clare.

먼저 PersonGroup - Create API를 사용하여 새 PersonGroup을 만듭니다.First, create a new PersonGroup by using the PersonGroup - Create API. 해당 클라이언트 라이브러리 API는 FaceClient 클래스에 대한 CreatePersonGroupAsync 메서드입니다.The corresponding client library API is the CreatePersonGroupAsync method for the FaceClient class. 그룹을 만들기 위해 지정된 그룹 ID는 각 구독에 대해 고유합니다.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.

그룹이 정의되면 PersonGroup Person - Create API를 사용하여 그룹 내의 사람을 정의할 수 있습니다.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. 사람이 만들어지면 각 사람에게 얼굴을 추가할 수 있습니다.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

감지는 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. 클라이언트 라이브러리를 사용하는 경우 얼굴 감지는 FaceClient 클래스에 대한 DetectAsync 메서드를 통해 수행됩니다.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 = 왼쪽, 위쪽, 너비, 높이" 형식의 문자열을 PersonGroup Person - Add Face API의 targetFace 쿼리 매개 변수에 전달합니다.Pass a string in the format of "targetFace = left, top, width, height" to PersonGroup Person - Add Face API's targetFace query parameter. 또한 AddPersonFaceAsync 메서드에 대한 targetFace 선택적 매개 변수를 사용하여 다른 얼굴을 추가할 수도 있습니다.You also can use the targetFace optional parameter for the AddPersonFaceAsync method to add other faces. 사람에게 추가된 각 얼굴에는 고유한 지속형 얼굴 ID가 지정됩니다.Each face added to the person is given a unique persisted face ID. 이 ID는 PersonGroup 사람 – Delete FaceFace – Identify에서 사용할 수 있습니다.You can use this ID 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 by using it. 사람을 추가하거나 제거한 후에 또는 등록된 사람 얼굴을 편집한 경우 PersonGroup이 다시 학습되어야 합니다.The PersonGroup must be retrained after you add or remove any person or if you edit a person's registered face. 학습은 PersonGroup – 학습 API를 통해 수행됩니다.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. PersonGroup - Get Training Status API 또는 클라이언트 라이브러리의 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단계: 정의된 PersonGroup에 대해 얼굴 식별Step 4: Identify a face against a defined PersonGroup

Face 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. 이 프로세스는 Face - Identify API 또는 클라이언트 라이브러리의 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. 그런 다음, 얼굴 ID를 두 번째 인수로 식별 API에 전달합니다.Then the face ID is passed to the identification API as a second argument. 여러 얼굴 ID를 한 번에 식별할 수 있습니다.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. 얼굴 감지를 위해 업로드한 이미지에 따라 Anna, Bill 또는 Clare의 얼굴이 정확하게 식별되는지 확인합니다.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. 백만 명 규모까지 확장하는 시나리오에 대한 자세한 내용은 대규모 기능을 사용하는 방법을 참조하세요.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: