例:画像内の顔を識別する方法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:

手順 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:<サブスクリプション キー>)。クライアント ライブラリを使用するとき、サブスクリプション キーが 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 Poral の [Marketplace] ページから入手できます。The subscription key can be obtained from the Marketplace page of your Azure portal. サブスクリプションに関するページを参照してください。See Subscriptions.

手順 2:PersonGroup を作成するStep 2: Create the PersonGroup

この手順では、"MyFriends" という名前の PersonGroup を作成しました。これには、3 人が含まれています (Anna、Bill、および Clare)。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. ユーザーには、1 つまたは複数の既知の顔を登録することができます。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 - Create 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 は各サブスクリプションに固有です。他の PersonGroups 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 - Create 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 要求の本文に画像ファイルを入れ、"POST" web 要求を Face - Detect API に送信することによって検出を実行します。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 – Add Face を呼び出してそれを正しい人物に追加することができます。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 - Add Face 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 が指定されます。これを PersonGroup Person – Delete Face および Face – Identify で使用できます。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 – Train 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 - Get Training Status 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. これには、Face - Identify API またはクライアント ライブラリの IdentifyAsync メソッドを使用します。This is done through the Face - Identify API or the IdentifyAsync method of the client library.

テスト対象の顔は、前の手順を使用して検出される必要があり、顔 ID は、Identify API に、2 番目の引数として渡されます。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 を識別することができ、結果にすべての 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. 100 万人の規模のシナリオの詳細については、「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 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: