#顔の認識
さて、前回の記事では写真に含まれる顔を検出してみました。今回は、顔の認識、つまり個人の識別を試してみようと思います。

##person groupの作成
faceAPIを使用するにはまず、person groupを作成します。person groupには複数のpersonが含まれ、personは複数の顔が登録されます。認識やトレーニングはperson groupに単位で実行されます。

person groupを作成するには、Person Group - Create a Person Groupを使用します。

例えば、myfamilyというperson groupを作成するには、以下のURLに対して、JSONをPOSTデータとして送信します。
https://westcentralus.api.cognitive.microsoft.com/face/v1.0/persongroups/myfamily

json1

{
    "name":"group1",
    "userData":"user-provided data attached to the person group"
}

処理が成功した場合には空のレスポンスが返されます。

##personの作成
次に、作成したperson groupに対してpersonを定義します。
personの定義はPerson - Create a Personを使用します。

先程のmyfamilyにmomというpersonを作成するには以下のURLにJSONをデータとして送信します。
https://westcentralus.api.cognitive.microsoft.com/face/v1.0/persongroups/myfamily/persons

json2

{
    "name":"mom",
    "userData":"User-provided data attached to the person"
}

成功すると以下のようなpersonIdが含まれたJSONが返されます。

response2

{
  "personId": "662b9d2e-a9e2-4a0a-87bd-a6a056179ebf"
}

##person faceの追加
作成したpersonに対して顔写真を登録します。
登録はPerson - Add a Person Faceを使用します。

最初に指定したperson groupのIDと、先程返されたpersonIdをパラメータとして使用します。
https://westcentralus.api.cognitive.microsoft.com/face/v1.0/persongroups/myfamily/persons/662b9d2e-a9e2-4a0a-87bd-a6a056179ebf/persistedFaces

データとしては以下のように顔が含まれる写真のURLを指定します。今回はサンプルとして利用可能な次の写真を利用します。

json3

{
    "url":"https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/PersonGroup/Family1-Mom/Family1-Mom1.jpg"
}

写真に顔が複数含まれる場合には、targetfaceパラメータで顔の位置を指定することが可能です。指定しない場合には一番大きな顔が登録されるようです。

結果としては次の用にpersistedFaceIdが返されます。

response3

{
  "persistedFaceId": "e5275806-d8fd-4d5e-82c0-50a8fc1001e4"
}

##トレーニングの実施
作成したperson groupをトレーニングします。personやperson faceを追加した場合にはトレーニングを行う必要があります。

トレーニングはPerson Group - Train Person Groupを用いて行います。
myfamilyをトレーニングするには以下のURLにPOSTします。データは必要ありません。
https://westcentralus.api.cognitive.microsoft.com/face/v1.0/persongroups/myfamily/train

トレーニングは非同期で行われます。トレーニングの状況を確認するにはPerson Group - Get Person Group Training Statusを使用します。

以下のようにトレーニング状況が返されます。

response4

{
  "status": "succeeded",
  "createdDateTime": "8/15/2017 2:42:22 PM",
  "lastActionDateTime": "8/15/2017 2:42:22 PM",
  "message": null
}

##顔の認識
トレーニングの完了したperson groupに対して顔の認識を実行するにはFace - Identifyを使用します。

次の写真を用いてテストしました。

まず、Detectメソッドと呼び出して、母親のfaceIdを取得します。次に、取得したfaceIdを指定してidentifyを呼び出します。取得したfaceIdは24時間有効です。

json5

{    
    "personGroupId":"myfamily",
    "faceIds":[
        "d55100c6-f898-4c04-b623-f534614763ab"
    ],
    "maxNumOfCandidatesReturned":1,
    "confidenceThreshold": 0.5
}

先程登録したpersonのIdが正しく返ってきました。

response5

[
  {
    "faceId": "d55100c6-f898-4c04-b623-f534614763ab",
    "candidates": [
      {
        "personId": "662b9d2e-a9e2-4a0a-87bd-a6a056179ebf",
        "confidence": 0.8646
      }
    ]
  }
]

##まとめ
今回は顔の認識を行いました。person groupの作成、personの作成、person faceの追加、person groupのトレーニングまで準備、その後、Detectによる顔の検出とidentifyによる顔の認識と、それなりにステップを踏む必要がありますが、簡単に利用できることがおわかりいただけたかと思います。今回は単なるAPIの使い方で、少しつまらない内容でしたので次回は、verifyメソッドを用いて、双子を区別できるか試してみたいと思います。