Azure face APIで遊んでみよう　その２~顔の認識

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

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

![image.png](https://qiita-image-store.s3.amazonaws.com/0/117736/32044084-19b4-8e19-0030-328080dbf816.png)

person groupを作成するには、[Person Group - Create a Person Group](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244)を使用します。

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

```json:json1
{
    "name":"group1",
    "userData":"user-provided data attached to the person group"
}
```
処理が成功した場合には空のレスポンスが返されます。

##personの作成
次に、作成したperson groupに対してpersonを定義します。
personの定義は[Person - Create a Person](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c)を使用します。

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

```json:json2
{
    "name":"mom",
    "userData":"User-provided data attached to the person"
}
```
成功すると以下のようなpersonIdが含まれたJSONが返されます。

```json:response2
{
  "personId": "662b9d2e-a9e2-4a0a-87bd-a6a056179ebf"
}
```
##person faceの追加
作成したpersonに対して顔写真を登録します。
登録は[Person - Add a Person Face](https://westcentralus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b/console)を使用します。

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

データとしては以下のように顔が含まれる写真のURLを指定します。今回はサンプルとして利用可能な次の写真を利用します。
![image.png](https://qiita-image-store.s3.amazonaws.com/0/117736/2f0ecc10-3f45-765e-9957-0b4b30be5590.png)


```json:json3
{
    "url":"https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/PersonGroup/Family1-Mom/Family1-Mom1.jpg"
}
```
写真に顔が複数含まれる場合には、targetfaceパラメータで顔の位置を指定することが可能です。指定しない場合には一番大きな顔が登録されるようです。

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

```json:response3
{
  "persistedFaceId": "e5275806-d8fd-4d5e-82c0-50a8fc1001e4"
}
```
##トレーニングの実施
作成したperson groupをトレーニングします。personやperson faceを追加した場合にはトレーニングを行う必要があります。

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

トレーニングは非同期で行われます。トレーニングの状況を確認するには[Person Group - Get Person Group Training Status](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395247)を使用します。

https://westcentralus.api.cognitive.microsoft.com/face/v1.0/persongroups/myfamily/training

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

```json: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](https://westcentralus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239/console)を使用します。

https://westcentralus.api.cognitive.microsoft.com/face/v1.0/identify

次の写真を用いてテストしました。
![image.png](https://qiita-image-store.s3.amazonaws.com/0/117736/c9428c5c-9d2d-dbed-cc3f-2ed508f55be2.png)

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

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

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

```json: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メソッドを用いて、双子を区別できるか試してみたいと思います。