Amazon Rekognitionで「コレクション」を操作する

2018.06.04

中村です。 AWS Summit から帰ってきましたので、また Rekognition の検証をしていきます。

前回まではこちら

Amazon Rekognition で顔認識用の「コレクション」を作る Amazon Rekognition で2つの画像から顔を検出・比較する

今回は、前回作成したコレクションを操作していきます。 具体的には、画像追加・削除・一覧の表示・検索です。

IndexFaces(画像追加)

既存のコレクションに、検出した顔を追加します。

リクエストパラメータ

Name Type Required Description
Collection ID String 検出した顔を追加したいコレクション ID
Image Structure base64-encode された画像もしくは S3 オブジェクト。 AWS CLI を使う場合は、base64-encode された画像は対応していません
External Image ID String × 検出した顔に指定する ID
Detection Attributes List × リターンする顔属性の配列。DEFAULT と ALL がある。 指定なしもしくは DEFAULT の場合、API は Bounding Box / Confidence / Pose / Quality / Landmarks のサブセットを返す。 ALL の場合は、全て返されるが処理に時間がかかる。
CLI Input JSON String × 提供された JSON 文字列に基づいて操作を実行。 --generate-cli-skeleton によって出力される形式。コマンドラインに他の引数が指定されている場合、CLI 値は JSON 提供の値を上書きします。
Generate CLI Skeleton String × API リクエストを送信せずに JSON スケルトンを標準出力する。値または値の入力がない場合は、--cli-input-json の引数として使用できるサンプル入力 JSON を出力。出力値が提供されている場合は、コマンド入力を検証し、そのコマンドのサンプル出力 JSON を返します。

サンプルコード・レスポンス

    $ aws rekognition index-faces --collection-id 'XXXXXXXX' --image '{"S3Object":{"Bucket":"XXXXXXXX","Name":"mai.jpg"}}' --external-image-id 'mai'
{
    "FaceRecords": [
        {
            "FaceDetail": {
                "BoundingBox": {
                    "Width": 0.6206896305084229,
                    "Top": 0.14505495131015778,
                    "Left": 0.12732096016407013,
                    "Height": 0.5142857432365417
                },
                "Landmarks": [
                    {
                        "Y": 0.34067580103874207,
                        "X": 0.3299688398838043,
                        "Type": "eyeLeft"
                    },
                    {
                        "Y": 0.3718206286430359,
                        "X": 0.5413291454315186,
                        "Type": "eyeRight"
                    },
                    {
                        "Y": 0.4536939263343811,
                        "X": 0.39416512846946716,
                        "Type": "nose"
                    },
                    {
                        "Y": 0.5066270232200623,
                        "X": 0.319728821516037,
                        "Type": "mouthLeft"
                    },
                    {
                        "Y": 0.5370627045631409,
                        "X": 0.5031372308731079,
                        "Type": "mouthRight"
                    }
                ],
                "Pose": {
                    "Yaw": -12.5783052444458,
                    "Roll": 10.427962303161621,
                    "Pitch": -7.994979381561279
                },
                "Quality": {
                    "Sharpness": 99.97486114501953,
                    "Brightness": 65.7033462524414
                },
                "Confidence": 99.86449432373047
            },
            "Face": {
                "BoundingBox": {
                    "Width": 0.6206896305084229,
                    "Top": 0.14505495131015778,
                    "Left": 0.12732096016407013,
                    "Height": 0.5142857432365417
                },
                "FaceId": "fbbca2a4-df0b-46f6-9c9b-e12f62f9bc3b",
                "ExternalImageId": "mai",
                "Confidence": 99.86449432373047,
                "ImageId": "c147a204-2c52-591d-8f0a-24008ed096a4"
            }
        }
    ],
    "FaceModelVersion": "3.0",
    "OrientationCorrection": "ROTATE_0"
}

External Image ID = mai と指定したので、Face プロパティの中に ExternalImageId に入力されています。 このように人間が認識できる ID が振れます。

ListFaces(一覧表示)

コレクション内の顔をリスト化します。

リクエストパラメータ

Name Type Required Description
Collection ID String 検出した顔を削除したいコレクション ID
CLI Input JSON String × 提供された JSON 文字列に基づいて操作を実行。 --generate-cli-skeleton によって出力される形式。コマンドラインに他の引数が指定されている場合、CLI 値は JSON 提供の値を上書きします。
Starting Token String × 結果が分割した場合に、次のアイテム取得を開始するのに必要な値。
Page Size Integer × AWSサービスコールで取得する各ページのサイズ(コマンドの出力に返される項目の数には影響なし)
Max Items Integer × コマンド出力する項目の最大数
Generate CLI Skeleton String × API リクエストを送信せずに JSON スケルトンを標準出力する。値または値の入力がない場合は、--cli-input-json の引数として使用できるサンプル入力 JSON を出力。出力値が提供されている場合は、コマンド入力を検証し、そのコマンドのサンプル出力 JSON を返します。

サンプルコード・レスポンス

    $ aws rekognition list-faces --collection-id 'XXXXXXXX'
{
    "FaceModelVersion": "3.0",
    "Faces": [
        {
            "BoundingBox": {
                "Width": 0.6206899881362915,
                "Top": 0.14505499601364136,
                "Left": 0.1273210048675537,
                "Height": 0.5142859816551208
            },
            "FaceId": "fbbca2a4-df0b-46f6-9c9b-e12f62f9bc3b",
            "ExternalImageId": "mai",
            "Confidence": 99.864501953125,
            "ImageId": "c147a204-2c52-591d-8f0a-24008ed096a4"
        }
    ]
}

DeleteFaces(画像削除)

パラメーターで指定した Face ID をコレクションから削除します。

リクエストパラメータ

Name Type Required Description
Collection ID String 検出した顔を削除したいコレクション ID
Face IDs List 削除したい顔の ID
CLI Input JSON String × 提供された JSON 文字列に基づいて操作を実行。 --generate-cli-skeleton によって出力される形式。コマンドラインに他の引数が指定されている場合、CLI 値は JSON 提供の値を上書きします。
Generate CLI Skeleton String × API リクエストを送信せずに JSON スケルトンを標準出力する。値または値の入力がない場合は、--cli-input-json の引数として使用できるサンプル入力 JSON を出力。出力値が提供されている場合は、コマンド入力を検証し、そのコマンドのサンプル出力 JSON を返します。

サンプルコード・レスポンス

    $ aws rekognition delete-faces --collection-id 'XXXXXXXX' --face-ids 'cc5ddb6c-0d92-4947-9364-583cc24c2ab5'
{
    "DeletedFaces": [
        "cc5ddb6c-0d92-4947-9364-583cc24c2ab5"
    ]
}

ちなみに画像を複数削除する場合は、このような書き方になります。

$ aws rekognition delete-faces --collection-id 'XXXXXXXX' --face-ids XXXXXXXXXXXXXXXX XXXXXXXXXXXXXXXX

SearchFaces(検索)

パラメータで与えられた、 Face ID とマッチした顔を検索します。Face ID に指定した顔は一覧には含まれません。

リクエストパラメータ

Name Type Required Description
Collection ID String 検索したいコレクション ID
Face ID String コレクション内の画像とマッチさせたい Face ID
Max Faces Integer × 検索する顔の最大数。最も高い信頼度を持つ顔の最大数が返される。
Face Match Thresold float × 返す顔マッチの最小信頼度( Similarity )を指定する。
CLI Input JSON String × 提供された JSON 文字列に基づいて操作を実行。 --generate-cli-skeleton によって出力される形式。コマンドラインに他の引数が指定されている場合、CLI 値は JSON 提供の値を上書きします。
Generate CLI Skeleton String × API リクエストを送信せずに JSON スケルトンを標準出力する。値または値の入力がない場合は、--cli-input-json の引数として使用できるサンプル入力 JSON を出力。出力値が提供されている場合は、コマンド入力を検証し、そのコマンドのサンプル出力 JSON を返します。

サンプルコード・レスポンス

コレクション内の画像
$ aws rekognition list-faces --collection-id XXXXXXXX
{
    "FaceModelVersion": "3.0",
    "Faces": [
        {
            "BoundingBox": {
                "Width": 0.594406008720398,
                "Top": 0.18610399961471558,
                "Left": 0.16483500599861145,
                "Height": 0.49627798795700073
            },
            "FaceId": "189b07b5-6568-4160-954e-c30e2c2e7900",
            "ExternalImageId": "mai_19",
            "Confidence": 99.91909790039062,
            "ImageId": "c7f123d9-542f-54bf-a7f9-2349bbae361e"
        },
        {
            "BoundingBox": {
                "Width": 0.6372550129890442,
                "Top": 0.19931499660015106,
                "Left": 0.15459999442100525,
                "Height": 0.5263159871101379
            },
            "FaceId": "3b5e1d4d-b26a-479d-a3a3-5c681668fffd",
            "ExternalImageId": "mai_15",
            "Confidence": 99.96369934082031,
            "ImageId": "2d3a75d0-5de9-5d19-9f27-1c937a098014"
        },
        {
            "BoundingBox": {
                "Width": 0.6206899881362915,
                "Top": 0.14505499601364136,
                "Left": 0.1273210048675537,
                "Height": 0.5142859816551208
            },
            "FaceId": "b3652c2f-4489-44c9-a032-3ec7fa53a3f1",
            "ExternalImageId": "mai",
            "Confidence": 99.864501953125,
            "ImageId": "c147a204-2c52-591d-8f0a-24008ed096a4"
        }
    ]
}
サンプルコード

ExternalImageId: mai を Face ID にして、 mai_15 / mai_19 を検索します。( mai / mai_15 / mai_19 は同一人物の画像です。)

$ aws rekognition search-faces --collection-id XXXXXXXX --face-id b3652c2f-4489-44c9-a032-3ec7fa53a3f1
{
    "SearchedFaceId": "b3652c2f-4489-44c9-a032-3ec7fa53a3f1",
    "FaceModelVersion": "3.0",
    "FaceMatches": [
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.594406008720398,
                    "Top": 0.18610399961471558,
                    "Left": 0.16483500599861145,
                    "Height": 0.49627798795700073
                },
                "FaceId": "189b07b5-6568-4160-954e-c30e2c2e7900",
                "ExternalImageId": "mai_19",
                "Confidence": 99.91909790039062,
                "ImageId": "c7f123d9-542f-54bf-a7f9-2349bbae361e"
            },
            "Similarity": 98.52896118164062
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.6372550129890442,
                    "Top": 0.19931499660015106,
                    "Left": 0.15459999442100525,
                    "Height": 0.5263159871101379
                },
                "FaceId": "3b5e1d4d-b26a-479d-a3a3-5c681668fffd",
                "ExternalImageId": "mai_15",
                "Confidence": 99.96369934082031,
                "ImageId": "2d3a75d0-5de9-5d19-9f27-1c937a098014"
            },
            "Similarity": 95.05223846435547
        }
    ]
}

SearchFacesByImage(検索)

パラメータで与えられた、 画像とマッチした顔を検索します。

リクエストパラメータ

Name Type Required Description
Collection ID String 検索したいコレクション ID
Image String base64-encode された画像もしくは S3 オブジェクト。 AWS CLI を使う場合は、base64-encode された画像は対応していません
Max Faces Integer × 検索する顔の最大数。最も高い信頼度を持つ顔の最大数が返される。
Face Match Thresold float × 返す顔マッチの最小信頼度を指定する。
CLI Input JSON String × 提供された JSON 文字列に基づいて操作を実行。 --generate-cli-skeleton によって出力される形式。コマンドラインに他の引数が指定されている場合、CLI 値は JSON 提供の値を上書きします。
Generate CLI Skeleton String × API リクエストを送信せずに JSON スケルトンを標準出力する。値または値の入力がない場合は、--cli-input-json の引数として使用できるサンプル入力 JSON を出力。出力値が提供されている場合は、コマンド入力を検証し、そのコマンドのサンプル出力 JSON を返します。

サンプルコード・レスポンス

S3 に mai_8.jpg(他の mai と同一人物) をアップロードしました。 mai_8.jpg を Image に設定し、検索します。

$ aws rekognition search-faces-by-image --collection-id XXXXXXXX --image '{"S3Object":{"Bucket": "XXXXXXXX","Name":"mai_8.jpg"}}'
{
    "SearchedFaceBoundingBox": {
        "Width": 0.5096153616905212,
        "Top": 0.20222045481204987,
        "Left": 0.2572115361690521,
        "Height": 0.4203013479709625
    },
    "SearchedFaceConfidence": 99.84368133544922,
    "FaceMatches": [
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.6372550129890442,
                    "Top": 0.19931499660015106,
                    "Left": 0.15459999442100525,
                    "Height": 0.5263159871101379
                },
                "FaceId": "3b5e1d4d-b26a-479d-a3a3-5c681668fffd",
                "ExternalImageId": "mai_15",
                "Confidence": 99.96369934082031,
                "ImageId": "2d3a75d0-5de9-5d19-9f27-1c937a098014"
            },
            "Similarity": 97.67920684814453
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.594406008720398,
                    "Top": 0.18610399961471558,
                    "Left": 0.16483500599861145,
                    "Height": 0.49627798795700073
                },
                "FaceId": "189b07b5-6568-4160-954e-c30e2c2e7900",
                "ExternalImageId": "mai_19",
                "Confidence": 99.91909790039062,
                "ImageId": "c7f123d9-542f-54bf-a7f9-2349bbae361e"
            },
            "Similarity": 91.8482666015625
        },
        {
            "Face": {
                "BoundingBox": {
                    "Width": 0.6206899881362915,
                    "Top": 0.14505499601364136,
                    "Left": 0.1273210048675537,
                    "Height": 0.5142859816551208
                },
                "FaceId": "b3652c2f-4489-44c9-a032-3ec7fa53a3f1",
                "ExternalImageId": "mai",
                "Confidence": 99.864501953125,
                "ImageId": "c147a204-2c52-591d-8f0a-24008ed096a4"
            },
            "Similarity": 81.37322998046875
        }
    ],
    "FaceModelVersion": "3.0"
}

まとめ

いかがでしたでしょうか。 SearchFaces でなかなかデータが出ずに(パラメータのデータのみしかなかったので)戸惑いました。

次回も引き続き、 Rekognition の検証をしていきます。