7 顔検索クイックスタートガイド

Mercury Cloudの顔検索機能を素早く着手するためのガイドが提供されています。

顔検索APIは、特徴データベースに登録されているすべての顔特徴の中からアップロードした画像から検出された顔を検索し、最も近い結果を返します。顔識別は「1対多」または「1：N」マッチングとも呼ばれます。候補の結果は検索対象の顔特徴との類似性に基づいて返されます。特徴データベースを作成して登録写真をデータベースに追加した後、新しくアップロードされた画像を使用して顔検索を実行できます。

以下の手順では、特徴データベースを作成して特徴データベースにいくつかの顔特徴を追加し、検索画像をアップロード。画像内の最大の顔を検出してから、1つの特徴データベース内で類似する顔を検索します。正常に検出された場合、比較結果と検出された顔情報が返されます。そして最後に、特徴データベースが削除されます。

各APIが特徴データベースを操作する際、db_idは1つの特徴データベースを識別するための一意のキーです。特徴データベース作成API（POST / {app_id} /データベース）の応答内容の中にあるdb_idを記憶するか、特徴データベース一覧API（GET / {app_id} /データベース）で見つけることができます。

7.1 準備

まず、Python環境がインストールされていることを確認してください。

次のPythonファイルをダウンロードしてPythonのパスフォルダーにコピーしてください。

1KB

auth_headers.py

API認証ヘッダー作成

611B

base64_encode.py

写真ファイルをBase64に変換

1KB

create_feature_db.py

特徴データベースを作成

945B

list_feature_db.py

特徴データベースの一覧表示

1KB

check_quality.py

品質チェック

2KB

add_faces.py

顔特徴追加

2KB

search_faces.py

顔検索

1KB

delete_feature_db.py

特徴データベース削除

605B

api_parameters.py

APIパラメータ

2KB

detect_faces.py

顔検知

api_parameters.pyをテキストエディターで開き、パラメーターをお客様の情報に置き換えてください。詳細は3.2節をご参照ください。

Python

# Common parameters. Used for all API calls.
# Base URL for Mercury Open API.
api_url = "https://mercury.japancv.co.jp/openapi/face/v1"
# Provision App Id for API calls.
app_id = "aabbccdd-eeff-0011-2233-445566778899"
# Provision access key to authentication.
access_key = '00112233-4455-6677-8899-aabbccddeeff'
# Provision secret key to authentication.
secret_key = '13579acegijmoqsuwyACEGIJMOPSUWY'

7.2 特徴データベースを作成

次のコマンドで特徴データベース作成のAPIリクエストを送信し、「hoge」という名前でDBサイズが1000の特徴データベースを作成します。パスをPythonライブラリパスに置き換えてください。 DBサイズは、1つの特徴データベースに保存できる顔特徴の最大数を制限します。この数量は、お客様がご購入したサブスクリプションで許容しているID数を超えられないので、ご注意ください。

Bash

python {python_path}\create_feature_db.py hoge 1000

APIを送信後、結果は次のようになります。ここには一意のdb_idが含まれます。

Compare feature database: name: hoge max size: 1000
Http status code: 200
response: {
 "trace_id": "de2557f6b435c836dd12447413bc9966",
 "name": "hoge",
 "db_id": "4caf27d2-f621-4cbf-acec-a7553f226000",
 "object_type": "OBJECT_FACE",
 "feature_version": 24902,
 "description": "Description for database hoge",
 "created_at": "2021-07-15T04:11:04.744807758Z",
 "max_size": 1000,
 "size": 0
}

このdb_idは忘れずに記録しておいてください。 それ以後の他のAPIを呼び出すときに使用されます。

7.3 特徴データベースの一覧表示

次のコマンドで、特徴データベースの一覧を表示するAPIリクエストを送信し、先ほど作成した特徴データベースの存在を確認します。

Bash

python {python_path}\list_feature_db.py

結果は次のようになります。

List feature databases:
Http status code: 200
db_ids: [
 "4caf27d2-f621-4cbf-acec-a7553f226000"
]

同じdb_idの特徴データベースが返されることを確認できます。

7.4 画像品質チェック

品質チェックAPIは、顔のサイズ、角度、明るさ、鋭さ、遮蔽などを分析し、すべての要素の値を応答します。顔特徴を特徴データベースに追加する前に、画像の品質チェックを行うことを強く推奨します。これは画質が高いほど認識精度が高くなるためです。

次のコマンドで、品質チェックのAPIリクエストを送信します。

Bash

python {python_path}\check_quality.py "{image_path}\image.jpg"

結果は次のようになります。

Check quality: {image_path}\image.jpg
Http status code: 200
Quality results: {
 "angle": {
  "yaw": 0.0027652662,
  "pitch": 7.864833,
  "roll": 0.049663484
 },
 "quality": {
  "distance2center": 0.08779055,
  "size": 0.36317098,
  "brightness": 0.17242007,
  "sharpness": 1,
  "mouth_open": 0.018774271,
  "missing": 1,
  "align_score": 9.999992
 },
 "occlusion": {
  "eye": 0,
  "nose": 0,
  "mouth": 0,
  "eyebrow": 0,
  "face_line": 0,
  "occlusion_total": 0
 },
 "rectangle": {
  "top": 610,
  "left": 332,
  "width": 777,
  "height": 774
 }
}

お客様はご自身でその許容レベルを決定して、判断する必要があります。そのロジックはご自身のプログラムに組み込まれる必要があります。

ここではパスポート写真の画質に近似する参考値を提供します。ただしお客様のビジネス要件とテスト結果に基づいて、しきい値を調整およびプログラムを構成してください。

パスポート写真の品質基準

項目	値の範囲 （参照用のみ）	説明
angle.yaw	-10.0~10.0	顔が上下を軸にした（ヨー）回転角度 頭が左寄りなほど、値は大きくなります
angle.pitch	-15.0~15.0	顔が左右を軸にした（ピッチ）回転角度 頭が下がるほど、値は大きくなります
angle.roll	-10.0~10.0	顔が前後を軸にした（ロール）回転角度 頭が反時計回りなほど、値は大きくなります
quality.distance2center	0.2~1.0	顔の中心と写真の中心との位置偏差 2つの中心の距離が近いほど、値は大きくなります
occlusion.occlusion_total	0.0~0.02	顔全体が遮蔽された度合い 顔全体の遮蔽が大きいほど、値は大きくなります
occlusion.eye	0.0	目が遮蔽された度合い 目の遮蔽が大きいほど、値は大きくなります
occlusion.nose	0.0	鼻が遮蔽された度合い 鼻の遮蔽が大きいほど、値は大きくなります
occlusion.mouth	0.0~0.4	口が遮蔽された度合い 口の遮蔽が大きいほど、値は大きくなります
occlusion.eyebrow	0.0	眉毛が遮蔽された度合い 眉毛の遮蔽が大きいほど、値は大きくなります
occlusion.face_line	0.0~0.1	顔の輪郭が遮蔽された度合い 顔の輪郭の遮蔽が大きいほど、値は大きくなります
quality.align_score	1.0~	顔ランドマークのスコア 揃いが良いほど、値は大きくなります
quality.brightness	-0.5~0.5	顔枠の平均明るさ 明るいほど、値は大きくなります
quality.sharpness	0.8~1.0	MAGICアルゴリズムで計算したシャープネス（鋭さ） 鋭いほど、値は大きくなります
quality.mouth_open	0.0~0.4	口が開いている度合い 口が開いているほど、値は大きくなります
quality.missing	0.9~1.0	ランディングポイントが写真の中に含めない度合い 含まれていないランディングポイントが少ないほど、値は大きくなります
quality.size	0~0.85	写真全体に対する顔枠面積の比率 顔枠の面積が大きいほど、値は大きくなります

7.5 特徴データベースに画像を追加

顔特徴一括追加APIは複数の顔特徴を追加するために、1つのリクエストで特徴データベースに複数の画像から送信します。特徴データベースに追加された各顔特徴は、一意のfeature_idがを割り当てされます。同一の画像または同じ人物に属する複数の画像を特徴データベースに複数回追加する場合、いくつかの異なるfeature_idが割り当てされます。 つまりfeature_idは1人の人間と同等に必要はなく、その時点で追加された顔特徴になります。

次のコマンドで、特徴データベースに顔特徴を追加のAPIリクエストを送信し、指定したフォルダー内のすべての画像を、先ほど作成した特徴データベースに追加します。

Bash

python {python_path}\add_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" {image_path}

結果は次のようになります。ここでは2枚の写真を送信しました。

Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image1.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008e
Detect face. rectangle: {'top': 625, 'left': 350, 'width': 793, 'height': 818} angle: {'yaw': -0.42474133, 'pitch': 9.596367, 'roll': 0.07245465}
Predicted attributes:
        Age: 29 ~ 39
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
Add to database: 4caf27d2-f621-4cbf-acec-a7553f226000 image: {image_path}\image2.jpg
Http status code: 200
Face feature_id: 4caf27d2f6214cbfaceca7553f226001000000000000008f
Detect face. rectangle: {'top': 637, 'left': 276, 'width': 844, 'height': 834} angle: {'yaw': 4.691873, 'pitch': 10.485169, 'roll': 1.0859865}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE

2つの画像の顔特徴が特徴データベースに追加されました。

7.6 特徴データベースで顔検索

顔検索APIは画像をアップロードし、検証スコアの結果に基づいて特徴データベース内の上位K個の類似した顔特徴を検索します。ここで提供するサンプルコードは、検証スコアが0.8を超える上位2つの顔特徴に制限します。

次のコマンドで、顔検索のAPIリクエストを送信します。

Bash

python {python_path}\search_faces.py "4caf27d2-f621-4cbf-acec-a7553f226000" "{image_path}\image.jpg"

結果は次のようになります。

Search face: {image_path}\image.jpg in:  4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
Detect face. rectangle: {'top': 342, 'left': 171, 'width': 384, 'height': 392} angle: {'yaw': -1.557804, 'pitch': 10.313386, 'roll': 1.3425148}
Predicted attributes:
        Age: 28 ~ 38
        Gender: MALE
        Cap: HAT_STYLE_TYPE_NONE
        Glasses: TRANSPARENT_GLASSES
        Mask: COLOR_TYPE_NONE
        db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
top 1 score: 0.9813498
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008e', 'key': '', 'extra_info': 'image1.jpg'}
top 2 score: 0.9803276
        feature: {'feature_id': '4caf27d2f6214cbfaceca7553f226001000000000000008f', 'key': '', 'extra_info': 'image2.jpg'}

近似するものが見つかった場合、APIの応答には上位K件の結果が含まれます。 それ以外の場合、結果は返されません。この例では、前の手順で追加された2つの画像と検索画像は同一人物であるため、feature_idsとそのスコアが返されます。

7.7 特徴データベース削除

最後に特徴データベースが不要になった場合は、特徴データベースを削除することを推奨します。削除することで特徴データベースに登録されているすべての顔特徴は、同時に削除されます。 次のコマンドを使用して、削除を実行するAPIを送信します。

Bash

python {python_path}\delete_feature_db.py "4caf27d2-f621-4cbf-acec-a7553f226000"

結は次のようになります。

Delete feature database: db_id: 4caf27d2-f621-4cbf-acec-a7553f226000
Http status code: 200
response: {
 "trace_id": "81c28dcd71c48befdcd2d92afb34c278"
}

特徴データベースおよび追加されたすべての顔特徴は、Mercury Cloud環境から完全に削除されました。