API Sandboxで各メソッドの動作を確認する

前回に引き続き、Face.comの顔認識APIについて紹介する。face.com developersには顔認識APIを試してみるための「API Sandbox」が用意されている。このツールを使って、任意の写真に対して各メソッドを実行した場合のレスポンスを見ることができる。使い方は、左の[Method:]の部分から試したいメソッドを選択し、上部にある写真を選んでクリックするだけ。もしくは、[Method Patrameters:]の[urls:]に写真のURLを指定して[Call Method]ボタンをクリックすれば、任意の写真に対してメソッドを実行することができる。

図1はface.detectを実行してみた様子。顔の中心および目、鼻、口の座標や、性別、眼鏡の有無、笑ってるかどうかなどが検出される。図2はfaces.recognizeを実行してみた様子。faces.recognizeを使うにはFacebookかTwitterのアカウントが必要。結果には顔の情報のほかにタグに関する情報も含まれており、写真の人物が98%の確率で筆者であると伝えている(前回示したように、FacebookにはPhoto Taggerでタグ付けした写真がアップしてある)。

図1 face.detectで顔写真の情報を取得する

"図2 face.recognizeで顔認識を行い、タグ情報を取得する

このツールでタグを新たに付けたり、変更したりすることも可能。またPHPライブラリを使った場合の呼び出しコードの例や、REST呼び出しのURLの例なども表示されるので、各メソッドの動作の確認に利用できる。

JavaScriptでface.com APIを使う

では、今度は自作のプログラムでface.com APIを利用してみよう。face.com APIではダウンロードページにおいてPHP用、JavaScript用、そして非公式だがPython用のクライアントライブラリが提供されている。そのほかに、顔写真へのタグ付けをサポートする「JavaScript Tagger Widget」も用意されている。今回はJavaScript用クライアントライブラリを使ってみる。したがっては「api_client.js」というファイルをダウンロードすればよい。

クライアントライブラリとは別に、face.com APIを利用するにはAPIキーを取得しなければならない。APIキーを取得するには、まずアカウントページからサインアップしてアカウントを登録する。その後、ログインしてアカウントページの「Click here to set up a new application」のリンクをクリックすればアプリケーションの登録を行うことができる。登録が完了すると、そのアプリケーション用のAPIキーが発行される。。

api_client.jsにはFaceClientAPIというオブジェクトが定義されており、以下の関数が提供されている。

  • faces_detect - face.com APIのfaces.detectメソッドに対応
  • faces_recognize - face.com APIのfaces.recognizeメソッドに対応
  • faces_train - face.com APIのfaces.trainメソッドに対応
  • faces_status - face.com APIのfaces.statusメソッドに対応
  • tags_save - face.com APIのtags.saveメソッドに対応
  • tags_add - face.com APIのtags.addメソッドに対応
  • tags_remove - face.com APIのtags.removeメソッドに対応
  • tags_get - face.com APIのtags.getメソッドに対応
  • account_limits - face.com APIのaccount.limitsメソッドに対応
  • account_authenticate - アカウント認証を行う
  • facebook_get - Facebookから指定されたアカウントでアクセスできる顔写真をすべて取得する
  • init - APIキーを指定して初期化する
  • getApiKey - 設定されたAPIキーを返す

ここではface_detect関数を使って写真から顔の位置などの情報を検出してみる。FaceClientAPIオブジェクトを使用するには、まず次のようにinit関数に取得したAPIキーを渡して初期化する。

リスト1

var api = FaceClientAPI;
api.init("取得したAPIキー");

faces_detectを呼び出す場合には、第1引数に写真のURLを、第2引数にコールバック関数を指定する。第1引数にはURLの配列を渡すことで複数の写真に対して同時に顔認証を行うこともできる。以下はコールバック関数としてdisplayKey関数を指定した例である。

リスト2

api.faces_detect("画像のURL", コールバック関数);

コールバック関数には、第1引数として対象の写真のURL(または複数のURLが格納された配列)が、第2引数にJSON形式の結果データが渡される。face.com APIには結果をXMLで返す方法も用意されているが、JavaScript用クライアントライブラリではまだサポートされていない。

結果データはこのページで示された形になっている。tagsフィールドにそれぞれの顔の情報がリスト化されており、その各要素にタグID(tidフィールドの値)とセットで顔の中心や目、鼻、口の座標といった情報が埋め込まれている。座標以外では、yaw/pitch/rollがそれぞれ首を回す方向の傾き/上下(頷く方向)の傾き/首を傾げる方向の傾きの角度を表す。attributesフィールドにあるface/gender/glasses/smillngは、それぞれ顔であるか/性別/眼鏡の有無/笑っているか否かと、その確率が格納される。

以上を踏まえ、今回は以下のようなJavaScriptおよびHTMLを作成してみた。これはフォームに画像のURLを記入してボタンを押すと、その画像にある顔を検出して各パーツの座標情報を表示するというものである。

リスト3

<html>
  <head>
    <meta http-equiv="content-type" content="text/html;charset=utf-8">
    <title>Face.comを使った顔認識のサンプル</title>
    <script type="text/javascript" src="api_client.js"></script>

    <script type="text/javascript">
      <!--
     function faceDetect() {
       var api = FaceClientAPI;
       api.init("取得としたAPIキー");

       var url = document.getElementById("url").value;
       api.faces_detect(url, displayData);
     }

     // 結果を表示
     function displayData(urls,data) {
       document.getElementById("image").innerHTML = "<img src='" + urls + "'/>";
       document.getElementById("result").innerHTML = parseJSON(data);
     }

     // JSONのデータを解析して表示
     function parseJSON(jsData) {
       var resultData = "";

       var photos = jsData.photos;
       var tags = photos[0].tags;
       for (var i in tags) {
         resultData += "<table border='1' align='left'>";
         resultData += "<caption>【顔" + i + "】</caption>";
         resultData += "<tr><th>ターゲット</th><th>x座標</th><th>y座標</th></tr>";
         resultData += "<tr><td>中央</td><td>" + tags[i].center.x + "</td><td>" + tags[i].center.y + "</td><tr>";
         resultData += "<tr><td>左目</td><td>" + tags[i].eye_left.x + "</td><td>" + tags[i].eye_left.y + "</td><tr>";
         resultData += "<tr><td>右目</td><td>" + tags[i].eye_right.x + "</td><td>" + tags[i].eye_right.y + "</td><tr>";
         resultData += "<tr><td>口の左端</td><td>" + tags[i].mouth_left.x + "</td><td>" + tags[i].mouth_left.y + "</td><tr>";
         resultData += "<tr><td>口の中央</td><td>" + tags[i].mouth_center.x + "</td><td>" + tags[i].mouth_center.y + "</td><tr>";
         resultData += "<tr><td>口の右端</td><td>" + tags[i].mouth_right.x + "</td><td>" + tags[i].mouth_right.y + "</td><tr>";
         resultData += "<tr><td>鼻</td><td>" + tags[i].nose.x + "</td><td>" + tags[i].nose.y + "</td><tr>";
         resultData += "</table>";
       }

       return resultData;
     }
// -->
    </script>
  </head>

  <body>
    <h1>Face.comを使った顔認識のサンプル</h1>
    <p>Face.comのAPIを利用して顔写真を調べます。</p>

    <form name="ajaxForm">
      URL: <input id="url" type="input"/><br/>
      <input type="button" value="顔写真を調べる" onClick="faceDetect()"><br/>
    </form>

    <div id="result"></div>
    <div id="image"></div>

  </body>
</html>

このHTMLファイルをWebサーバ上にアップロードし、適当な画像ファイルのURLを指定して顔認識を実行すると、図3のように目や鼻などの座標が表示される。今回使用しているのはface.detectメソッドだけなのでFacebookなどのアカウントは必要ないが、その代わりに他の顔写真と照合することはできない。他の顔写真との照合を行うにはface.recognizeメソッドを使う必要がある。

face_detect関数を利用して顔写真の情報を取得する例