Face APIで登録した顔の人物情報を取得する



Microsoft AzureのCognitive Servicesから、Face APIを使って顔の登録、登録した顔の人物名を取得するという流れを触る機会がありましたので、ここでまとめさせていただきます。
なお、ここでは、Azureのアカウントを取得し、Face APIへのアクセスキーを取得していることが前提になります。

参考記事：
https://docs.microsoft.com/ja-jp/azure/cognitive-services/face/face-api-how-to-topics/howtoidentifyfacesinimage

# Face API上でのデータ構造
まず、導入として、Face APIの中で人の顔がどのようなデータ構造になって保存され、人物情報と紐づいているかを説明します。
![image](https://qiita-image-store.s3.amazonaws.com/0/171449/b0ec69b0-5a65-363e-0447-75fdc23d5d62.png)
図としてはこんな感じです。

Person Groupは識別してほしい人のグループをまとめたものになっています。所属するコミュニティによって関わりあう人は違いますよね。
「友達」とか、「仕事仲間」とか、識別したいグループを表します。
別に一律でもいいよという方は、Person Groupを1個だけにしてしまえば問題ないと思います。
Personはその名の通り、人の情報です。
そのPersonに紐づいている顔の情報が、Persisted Faceになります。
「Persisted」と書かれているため、この顔は永続的にFace APIの中で記録されます。


# 顔を登録してみよう
## 1. Person Groupを作成する
まずは大きなところから。Person Groupを作成します。
リクエストに入れるpersonGroupIdはルールに守ってさえいれば何でもいいです。
[Person Group - Create a Person Group](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395244)

作成したPerson Group IDはまた使いますので、どこかに記録、保管しておいてください。

## 2. Personを作成する
作成したPerson Groupに対して、人の情報を組み込んでいきます。
まずは登録する人の情報を作成します。名前のほか、16KBまで使えるユーザーデータもあります。
[Person - Create a Person](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523c)

Personを作成すると、Person IDがレスポンスされます。こちらはGUIDの形式で返ってきます。
この後の顔の登録で使うので、Person Group IDと一緒に記録、保管しておいてください。

## 3. 顔を登録する
人を作成した後は、じゃんじゃんその人の顔を登録していきます。
以下のAPIに画像データまたは画像データへのリンクを投げて、顔を登録します。
[Person - Add a Person Face](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523b)


ここで注意すべきことは、**画像の中には顔が必ず1つであること**です。2つ以上あると、どっちの顔か分からないですよね。
なお、「画像内に2人以上写っているけど、右側の人だけ指定したい」といった場合は、リクエストパラメータにあるtargetFaceで矩形選択することで画像の一部分を反映させることができます。

## 4. あとは繰り返し！
同じ人で複数の顔を登録したい場合は、[顔の登録](#3-顔を登録する)を、別の人の顔を登録したい場合は[人物の作成](#2-Personを作成する)をやっていきます。

## 5. 最後にPerson Groupを学習させる
全ての人物と顔の登録が終わって、「ふぅー、もういけるな」と考えていたら大間違い。
最後の仕上げとして、Face APIに登録した顔を学習させます。
学習はPerson Group単位で行います。
[Person Group - Train Person Group](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395249)

数枚であれば一瞬で終わりますが、枚数が多いと時間がかかるかもしれません（5枚程度で試しただけでしたので、枚数が多い場合の動作は未確認です）。
なお、学習のステータス確認もできます。
[Person Group - Get Person Group Training Status](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395247)

# 登録した顔を検出してみよう
せっかく登録したモノを使わないのでは意味がないので、登録した顔を検出して、その人の名前が取得できるかやってみましょう。

## 1. 顔を検出する
Face APIの一番メジャーなAPI、顔検出のAPIでまずは顔の検出を行います。
画像データまたは画像データへのリンクをリクエストパラメータにして、APIにリクエストしてやります。
[Face - Detect](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395236)

その結果、検知した顔が返ってきます。複数の顔が検出された時は、複数の顔情報が返ってきます。
検出された顔の情報は大きく分けて以下の4つのデータに分かれます。

* faceId - Face API内部で管理している顔のID。24時間したらIDは切れます。
* faceRectangle - 顔が画像上のどこにあるかを示す長方形。
* faceLandmarks - 目や口などの位置が画像上のどこにあるかを示す座標。
* faceAttributes - 画像から顔の年齢、性別、表情、向いている方向などを出力。

このうち重要なのは**faceId**になります。このIDをどこかに保管しておいてください。

## 2. 検出した顔から人物を検索する
先ほど検出した顔のfaceIDから、人の情報を検索します。
下記APIのリクエストパラメータにfaceIDを列挙していきます。なお、**一度のリクエストで検索できるのは10人まで**ですのでご注意ください、
[Face - Identify](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395239)

完了すると、candidatesの中にその人物のPerson IDが返ってきます。
検出した顔が登録した人に当てはまらない場合は、candidatesが空の配列で返ってきます。

## 3. Person IDから名前を取得する
最後に、検索されたPerson IDから、その人の名前などの情報を引き出します。
[Person - Get a Person](https://westus.dev.cognitive.microsoft.com/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f3039523f)

これでうまくいけば、登録した人の名前がレスポンスされるはずです。

# 注意点
以上がFace APIで顔の登録、登録した顔の検出を行うまでの流れになります。
使ってみた中で1点だけ注意点がありますので、是非頭の中に入れていただけると嬉しいです。

それは、Face APIは無料で使おうと思うと、**1分間に20呼び出しまで**ということです。
特に顔検出においては、[顔の検出](#1-顔を検出する)、[人物の検索](#2-検出した顔から人物を検索する)までは複数人を同時に1回ないし数回の呼び出しで何とかなりますが、最後の[名前の取得](#3-Person-IDから名前を取得する)は一人一人に対して1回ずつ呼び出す必要があります。
20人の顔を検知して、20人検索できたら、もう一発でアウトなんですよね・・・。
そのため、Person IDから人物情報を取得するところだけは、DBなどで補ってあげた方がいいかもしれません。

でも、ここまで楽に顔画像から人の情報につなげられるのはすごいですよね。
今後もどんどんCognitive Servicesを追っていきたいと思っています。

今回はかなり概念的なお話でしたが、次回はできるだけ実装寄りの話をさせていただきたいと思っています。
以上です。お読みいただきありがとうございました。