Amazon Rekognition
開発者ガイド

コレクションへの顔の追加

IndexFaces オペレーションを使用して、イメージ内の顔を検出し、コレクションに追加できます。Amazon Rekognition は、検出した顔ごとに顔の特徴を抽出し、その特徴情報をデータベースに保存します。さらに、検出した顔ごとのメタデータを、指定された顔コレクションに保存します。Amazon Rekognition は、実際のイメージのバイトを保存しません。

インデックス作成に適した顔の提供については、「顔認識用の入力イメージに関する推奨事項」を参照してください。

IndexFaces オペレーションでは、顔ごとに以下の情報が保持されます。

  • 顔の多次元特徴IndexFaces では顔分析を使用して、顔の特徴に関する多次元情報を抽出し、その情報を顔コレクションに保存します。この情報に直接アクセスすることはできません。ただし、Amazon Rekognition は顔コレクション内で一致する顔を検索するときに、この情報を使用します。

     

  • メタデータ – 各顔のメタデータには、境界ボックス、信頼度 (境界ボックスに顔が含まれている確率)、Amazon Rekognition によって割り当てられた ID (顔 ID とイメージ ID)、およびリクエストの外部イメージ ID (指定した場合) が含まれます。この情報は、IndexFaces API コールのレスポンスで返されます。例については、以下のレスポンスの face 要素を参照してください。

    このメタデータは、以下の API コールのレスポンスで返されます。

     

    • ListFaces

    • 顔の検索オペレーション – SearchFaces および SearchFacesByImage のレスポンスは、一致する顔ごとに一致の信頼度と、一致した顔のメタデータを返します。

IndexFaces でインデックス付けされる顔の数は、入力コレクションに関連付けられている顔検出モデルのバージョンによって異なります。詳細については、「モデルのバージョニング」を参照してください。

インデックスが付けられた顔に関する情報が FaceRecord オブジェクトの配列で返されます。

インデックスが付けられた顔を、顔を検出したイメージに関連付けることができます。たとえば、イメージのクライアント側のインデックスとイメージ内の顔を保持できます。顔をイメージと関連付けるには、ExternalImageId リクエストパラメータでイメージ ID を指定します。イメージ ID として、ファイル名を使用するか、別に作成した ID を使用できます。

API は、顔コレクションに保存する前述の情報に加えて、コレクションに保存されない顔の詳細も返します(以下のレスポンス例の faceDetail 要素を参照してください)。

注記

DetectFaces から同じ情報が返されるため、同じイメージに対して DetectFacesIndexFaces の両方を呼び出す必要はありません。

顔のフィルタリング

IndexFaces オペレーションにより、インデックスが付けられた顔をイメージからフィルタリングすることができます。IndexFaces を使用すると、インデックスの顔の最大数を指定したり、高品質で検出された顔のみにインデックスを付けることを選択したりできます。

MaxFaces 入力パラメーターを使用して IndexFaces によりインデックスが付けられる顔の最大数を指定することができます。この機能は、イメージ内の最も大きい顔にインデックスを付け、背景に立っている人の顔など、小さい顔にインデックスを付けない場合に役立ちます。

デフォルトでは、低品質で検出された顔を IndexFaces がフィルターで除外します。QualityFilter 入力パラメーターの値に AUTO を指定することで、低品質の顔を明示的にフィルターで除外できます。品質に基づいて顔をフィルタリングしない場合、QualityFilterNONE を指定します。IndexFaces は、次の理由で低品質の顔をフィルタリングします。

  • イメージサイズに比べて顔が小さすぎる。

  • 顔が極端にぼやけている。

  • イメージが暗すぎる。

  • 顔が極端なポーズをしている。

注記

品質のフィルタリングを使用するには、バージョン 3 の顔モデルに関連付けられているコレクションが必要です。コレクションに関連付けられている顔モデルのバージョンを取得するには、DescribeCollection を呼び出します。

IndexFaces によりインデックスが付けられていない顔に関する情報が UnindexedFace オブジェクトの配列で返されます。Reasons 配列には、顔にインデックスが付けられていない理由のリストが含まれています。たとえば、EXCEEDS_MAX_FACES の値は、MaxFaces により指定された顔の数が既に検出されているためにインデックスが付けられていない顔です。

詳細については、「コレクション内の顔の管理」を参照してください。

コレクションに顔を追加するには (SDK)

  1. まだ実行していない場合:

    1. AmazonRekognitionFullAccessAmazonS3ReadOnlyAccess のアクセス権限を持つ IAM ユーザーを作成または更新します。詳細については、「ステップ 1: AWS アカウントを設定して IAM ユーザーを作成する」を参照してください。

    2. AWS CLI と AWS SDK をインストールして設定します。詳細については、「ステップ 2: AWS CLI と AWS SDK をセットアップする」を参照してください。

  2. イメージ (1 つ以上の顔を含むもの) を Amazon S3 バケットにアップロードします。

    手順については、『Amazon Simple Storage Service コンソールユーザーガイド』の「Amazon S3 へのオブジェクトのアップロード」を参照してください。

  3. 以下の例を使用して、IndexFaces オペレーションを呼び出します。

    JavaAWS CLIPython.NET
    Java

    この例では、コレクションに追加した顔の識別子を表示します。

    collectionId の値は、顔を追加するコレクションの名前に変更します。bucketphoto の値は、ステップ 2 で使用した Amazon S3 バケット名とイメージ名に置き換えます。.withMaxFaces(1) パラメーターは、インデックスが付けられた顔の数を 1 に制限します。必要に応じて値を変更または削除します。

    //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) package aws.example.rekognition.image; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.FaceRecord; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.IndexFacesRequest; import com.amazonaws.services.rekognition.model.IndexFacesResult; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.UnindexedFace; import java.util.List; public class AddFacesToCollection { public static final String collectionId = "MyCollection"; public static final String bucket = "bucket"; public static final String photo = "input.jpg"; public static void main(String[] args) throws Exception { AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); Image image = new Image() .withS3Object(new S3Object() .withBucket(bucket) .withName(photo)); IndexFacesRequest indexFacesRequest = new IndexFacesRequest() .withImage(image) .withQualityFilter(QualityFilter.AUTO) .withMaxFaces(1) .withCollectionId(collectionId) .withExternalImageId(photo) .withDetectionAttributes("DEFAULT"); IndexFacesResult indexFacesResult = rekognitionClient.indexFaces(indexFacesRequest); System.out.println("Results for " + photo); System.out.println("Faces indexed:"); List<FaceRecord> faceRecords = indexFacesResult.getFaceRecords(); for (FaceRecord faceRecord : faceRecords) { System.out.println(" Face ID: " + faceRecord.getFace().getFaceId()); System.out.println(" Location:" + faceRecord.getFaceDetail().getBoundingBox().toString()); } List<UnindexedFace> unindexedFaces = indexFacesResult.getUnindexedFaces(); System.out.println("Faces not indexed:"); for (UnindexedFace unindexedFace : unindexedFaces) { System.out.println(" Location:" + unindexedFace.getFaceDetail().getBoundingBox().toString()); System.out.println(" Reasons:"); for (String reason : unindexedFace.getReasons()) { System.out.println(" " + reason); } } } }
    AWS CLI

    この AWS CLI コマンドでは、index-faces CLI オペレーションの JSON 出力を表示します。

    collection-id の値は、顔を保存する先のコレクションの名前に置き換えます。BucketName の値は、ステップ 2 で使用した Amazon S3 バケットとイメージファイルに置き換えます。max-faces パラメーターは、インデックスが付けられた顔の数を 1 に制限します。必要に応じて値を変更または削除します。

    aws rekognition index-faces \ --image '{"S3Object":{"Bucket":"bucket-name","Name":"file-name"}}' \ --collection-id "collection-id" \ --max-faces 1 \ --quality-filter "AUTO" \ --detection-attributes "ALL" \ --external-image-id "example-image.jpg"
    Python

    この例では、コレクションに追加した顔の識別子を表示します。

    collectionId の値は、顔を追加するコレクションの名前に変更します。bucketphoto の値は、ステップ 2 で使用した Amazon S3 バケット名とイメージ名に置き換えます。MaxFaces 入力パラメーターは、インデックスが付けられた顔の数を 1 に制限します。必要に応じて値を変更または削除します。

    #Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. #PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) import boto3 if __name__ == "__main__": bucket='bucket' collectionId='MyCollection' photo='photo' client=boto3.client('rekognition') response=client.index_faces response=client.index_faces(CollectionId=collectionId, Image={'S3Object':{'Bucket':bucket,'Name':photo}}, ExternalImageId=photo, MaxFaces=1, QualityFilter="AUTO", DetectionAttributes=['ALL']) print ('Results for ' + photo) print('Faces indexed:') for faceRecord in response['FaceRecords']: print(' Face ID: ' + faceRecord['Face']['FaceId']) print(' Location: {}'.format(faceRecord['Face']['BoundingBox'])) print('Faces not indexed:') for unindexedFace in response['UnindexedFaces']: print(' Location: {}'.format(unindexedFace['FaceDetail']['BoundingBox'])) print(' Reasons:') for reason in unindexedFace['Reasons']: print(' ' + reason)
    .NET

    この例では、コレクションに追加した顔の識別子を表示します。

    collectionId の値は、顔を追加するコレクションの名前に変更します。bucketphoto の値は、ステップ 2 で使用した Amazon S3 バケット名とイメージ名に置き換えます。

    //Copyright 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved. //PDX-License-Identifier: MIT-0 (For details, see https://github.com/awsdocs/amazon-rekognition-developer-guide/blob/master/LICENSE-SAMPLECODE.) using System; using System.Collections.Generic; using Amazon.Rekognition; using Amazon.Rekognition.Model; public class AddFaces { public static void Example() { String collectionId = "MyCollection"; String bucket = "bucket"; String photo = "input.jpg"; AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); Image image = new Image() { S3Object = new S3Object() { Bucket = bucket, Name = photo } }; IndexFacesRequest indexFacesRequest = new IndexFacesRequest() { Image = image, CollectionId = collectionId, ExternalImageId = photo, DetectionAttributes = new List<String>(){ "ALL" } }; IndexFacesResponse indexFacesResponse = rekognitionClient.IndexFaces(indexFacesRequest); Console.WriteLine(photo + " added"); foreach (FaceRecord faceRecord in indexFacesResponse.FaceRecords) Console.WriteLine("Face detected: Faceid is " + faceRecord.Face.FaceId); } }

IndexFaces オペレーションのリクエスト

IndexFaces への入力は、インデックス付けするイメージと顔を追加するコレクションです。

{ "CollectionId": "MyCollection", "Image": { "S3Object": { "Bucket": "bucket", "Name": "input.jpg" } }, "ExternalImageId": "input.jpg", "DetectionAttributes": [ "DEFAULT" ], "MaxFaces": 1, "QualityFilter": "AUTO" }

IndexFaces オペレーションのレスポンス

IndexFaces は、イメージ内で検出された顔に関する情報を返します。たとえば、次の JSON レスポンスは、入力イメージ内で検出された顔のデフォルトの検出属性を返します。この例は、MaxFaces 入力パラメーターの値が — を超えたためにインデックスが付けられていない顔も示しています。Reasons 配列には、EXCEEDS_MAX_FACES が含まれます。品質の理由で顔にインデックスが付けられない場合、Reasons には LOW_SHARPNESSLOW_BRIGHTNESS などの値が含まれます。詳細については、「UnindexedFace」を参照してください。

{ "FaceModelVersion": "3.0", "FaceRecords": [ { "Face": { "BoundingBox": { "Height": 0.3247932195663452, "Left": 0.5055555701255798, "Top": 0.2743072211742401, "Width": 0.21444444358348846 }, "Confidence": 99.99998474121094, "ExternalImageId": "input.jpg", "FaceId": "b86e2392-9da1-459b-af68-49118dc16f87", "ImageId": "09f43d92-02b6-5cea-8fbd-9f187db2050d" }, "FaceDetail": { "BoundingBox": { "Height": 0.3247932195663452, "Left": 0.5055555701255798, "Top": 0.2743072211742401, "Width": 0.21444444358348846 }, "Confidence": 99.99998474121094, "Landmarks": [ { "Type": "eyeLeft", "X": 0.5751981735229492, "Y": 0.4010535478591919 }, { "Type": "eyeRight", "X": 0.6511467099189758, "Y": 0.4017036259174347 }, { "Type": "nose", "X": 0.6314528584480286, "Y": 0.4710812568664551 }, { "Type": "mouthLeft", "X": 0.5879443287849426, "Y": 0.5171778798103333 }, { "Type": "mouthRight", "X": 0.6444502472877502, "Y": 0.5164633989334106 } ], "Pose": { "Pitch": -10.313642501831055, "Roll": -1.0316886901855469, "Yaw": 18.079818725585938 }, "Quality": { "Brightness": 71.2919921875, "Sharpness": 78.74752044677734 } } } ], "OrientationCorrection": "", "UnindexedFaces": [ { "FaceDetail": { "BoundingBox": { "Height": 0.1329464465379715, "Left": 0.5611110925674438, "Top": 0.6832437515258789, "Width": 0.08777777850627899 }, "Confidence": 92.37225341796875, "Landmarks": [ { "Type": "eyeLeft", "X": 0.5796897411346436, "Y": 0.7452847957611084 }, { "Type": "eyeRight", "X": 0.6078574657440186, "Y": 0.742687463760376 }, { "Type": "nose", "X": 0.597953200340271, "Y": 0.7620673179626465 }, { "Type": "mouthLeft", "X": 0.5884202122688293, "Y": 0.7920381426811218 }, { "Type": "mouthRight", "X": 0.60627681016922, "Y": 0.7919750809669495 } ], "Pose": { "Pitch": 15.658954620361328, "Roll": -4.583454608917236, "Yaw": 10.558992385864258 }, "Quality": { "Brightness": 42.54612350463867, "Sharpness": 86.93206024169922 } }, "Reasons": [ "EXCEEDS_MAX_FACES" ] } ] }

すべての顔の情報を取得するには、DetectionAttributes リクエストパラメータに「ALL」を指定します。次のレスポンス例で、faceDetail 要素の追加情報はサーバーに保持されないことに注意してください。

  • 25 の顔ランドマーク (前の例では 5 つのみ)

  • 9 つの顔属性 (眼鏡、ひげなど)

  • 感情 (emotion 要素を参照)

face 要素は、サーバーに保持されるメタデータを提供します。

FaceModelVersion は、コレクションに関連付けられている顔モデルのバージョンです。詳細については、「モデルのバージョニング」を参照してください。

OrientationCorrection は、イメージの向きの予測です。バージョン 3 よりも新しいバージョンの顔検出モデルを使用している場合、方向補正情報は返されません。詳細については、「イメージの向きおよび境界ボックス座標の取得」を参照してください。

{ "FaceModelVersion": "3.0", "FaceRecords": [ { "Face": { "BoundingBox": { "Height": 0.06333333253860474, "Left": 0.17185185849666595, "Top": 0.7366666793823242, "Width": 0.11061728745698929 }, "Confidence": 99.99999237060547, "ExternalImageId": "input.jpg", "FaceId": "578e2e1b-d0b0-493c-aa39-ba476a421a34", "ImageId": "9ba38e68-35b6-5509-9d2e-fcffa75d1653" }, "FaceDetail": { "AgeRange": { "High": 25, "Low": 15 }, "Beard": { "Confidence": 99.98077392578125, "Value": false }, "BoundingBox": { "Height": 0.06333333253860474, "Left": 0.17185185849666595, "Top": 0.7366666793823242, "Width": 0.11061728745698929 }, "Confidence": 99.99999237060547, "Emotions": [ { "Confidence": 95.40877532958984, "Type": "HAPPY" }, { "Confidence": 6.6088080406188965, "Type": "CALM" }, { "Confidence": 0.7385611534118652, "Type": "SAD" } ], "Eyeglasses": { "Confidence": 99.96795654296875, "Value": false }, "EyesOpen": { "Confidence": 64.0671157836914, "Value": true }, "Gender": { "Confidence": 100, "Value": "Female" }, "Landmarks": [ { "Type": "eyeLeft", "X": 0.21361233294010162, "Y": 0.757106363773346 }, { "Type": "eyeRight", "X": 0.2518567442893982, "Y": 0.7599404454231262 }, { "Type": "nose", "X": 0.2262365221977234, "Y": 0.7711842060089111 }, { "Type": "mouthLeft", "X": 0.2050037682056427, "Y": 0.7801263332366943 }, { "Type": "mouthRight", "X": 0.2430567592382431, "Y": 0.7836716771125793 }, { "Type": "leftPupil", "X": 0.2161938101053238, "Y": 0.756662905216217 }, { "Type": "rightPupil", "X": 0.2523181438446045, "Y": 0.7603650689125061 }, { "Type": "leftEyeBrowLeft", "X": 0.20066319406032562, "Y": 0.7501518130302429 }, { "Type": "leftEyeBrowUp", "X": 0.2130996286869049, "Y": 0.7480520606040955 }, { "Type": "leftEyeBrowRight", "X": 0.22584207355976105, "Y": 0.7504606246948242 }, { "Type": "rightEyeBrowLeft", "X": 0.24509544670581818, "Y": 0.7526801824569702 }, { "Type": "rightEyeBrowUp", "X": 0.2582615911960602, "Y": 0.7516844868659973 }, { "Type": "rightEyeBrowRight", "X": 0.26881539821624756, "Y": 0.7554477453231812 }, { "Type": "leftEyeLeft", "X": 0.20624476671218872, "Y": 0.7568746209144592 }, { "Type": "leftEyeRight", "X": 0.22105035185813904, "Y": 0.7582521438598633 }, { "Type": "leftEyeUp", "X": 0.21401576697826385, "Y": 0.7553104162216187 }, { "Type": "leftEyeDown", "X": 0.21317370235919952, "Y": 0.7584449648857117 }, { "Type": "rightEyeLeft", "X": 0.24393919110298157, "Y": 0.7600628137588501 }, { "Type": "rightEyeRight", "X": 0.2598416209220886, "Y": 0.7605880498886108 }, { "Type": "rightEyeUp", "X": 0.2519053518772125, "Y": 0.7582084536552429 }, { "Type": "rightEyeDown", "X": 0.25177454948425293, "Y": 0.7612871527671814 }, { "Type": "noseLeft", "X": 0.2185886949300766, "Y": 0.774715781211853 }, { "Type": "noseRight", "X": 0.23328955471515656, "Y": 0.7759330868721008 }, { "Type": "mouthUp", "X": 0.22446128726005554, "Y": 0.7805567383766174 }, { "Type": "mouthDown", "X": 0.22087252140045166, "Y": 0.7891407608985901 } ], "MouthOpen": { "Confidence": 95.87068939208984, "Value": false }, "Mustache": { "Confidence": 99.9828109741211, "Value": false }, "Pose": { "Pitch": -0.9409101605415344, "Roll": 7.233824253082275, "Yaw": -2.3602254390716553 }, "Quality": { "Brightness": 32.01998519897461, "Sharpness": 93.67259216308594 }, "Smile": { "Confidence": 86.7142105102539, "Value": true }, "Sunglasses": { "Confidence": 97.38925170898438, "Value": false } } } ], "OrientationCorrection": "ROTATE_0" "UnindexedFaces": [] }