Amazon Rekognition
開発者ガイド

イメージ内の顔の検出

Amazon Rekognition Image では、DetectFaces オペレーションを使用して目、鼻、口などの主な顔の特徴を探して入力イメージ内の顔を検出できます。Amazon Rekognition Image では、イメージ内の顔を大きい順に 100 個まで検出します。

入力イメージとして、イメージのバイト配列 (base64 でエンコードされたイメージのバイト) を指定するか、Amazon S3 オブジェクトを指定することができます。次の手順では、イメージ (JPEG または PNG) を S3 バケットにアップロードし、オブジェクトのキー名を指定します。

イメージ内の顔を検出するには

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

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

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

  2. イメージ (1 つ以上の有名人の顔が含まれているもの) を S3 バケットにアップロードします。

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

  3. 以下の例を使用して DetectFaces を呼び出します。

    JavaAWS CLIPython.NET
    Java

    この例では、検出した顔の推定年齢範囲を表示し、すべての検出した顔属性の JSON を一覧表示します。photo の値は、イメージファイル名に変更します。bucket の値は、イメージの保存先の 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.) package aws.example.rekognition.image; import com.amazonaws.services.rekognition.AmazonRekognition; import com.amazonaws.services.rekognition.AmazonRekognitionClientBuilder; import com.amazonaws.services.rekognition.model.AmazonRekognitionException; import com.amazonaws.services.rekognition.model.Image; import com.amazonaws.services.rekognition.model.S3Object; import com.amazonaws.services.rekognition.model.AgeRange; import com.amazonaws.services.rekognition.model.Attribute; import com.amazonaws.services.rekognition.model.DetectFacesRequest; import com.amazonaws.services.rekognition.model.DetectFacesResult; import com.amazonaws.services.rekognition.model.FaceDetail; import com.fasterxml.jackson.databind.ObjectMapper; import java.util.List; public class DetectFaces { public static void main(String[] args) throws Exception { String photo = "input.jpg"; String bucket = "bucket"; AmazonRekognition rekognitionClient = AmazonRekognitionClientBuilder.defaultClient(); DetectFacesRequest request = new DetectFacesRequest() .withImage(new Image() .withS3Object(new S3Object() .withName(photo) .withBucket(bucket))) .withAttributes(Attribute.ALL); // Replace Attribute.ALL with Attribute.DEFAULT to get default values. try { DetectFacesResult result = rekognitionClient.detectFaces(request); List < FaceDetail > faceDetails = result.getFaceDetails(); for (FaceDetail face: faceDetails) { if (request.getAttributes().contains("ALL")) { AgeRange ageRange = face.getAgeRange(); System.out.println("The detected face is estimated to be between " + ageRange.getLow().toString() + " and " + ageRange.getHigh().toString() + " years old."); System.out.println("Here's the complete set of attributes:"); } else { // non-default attributes have null values. System.out.println("Here's the default set of attributes:"); } ObjectMapper objectMapper = new ObjectMapper(); System.out.println(objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(face)); } } catch (AmazonRekognitionException e) { e.printStackTrace(); } } }
    AWS CLI

    この例では、detect-faces AWS CLI オペレーションの JSON 出力を表示します。fileは、イメージファイル名に置き換えます。bucket は、イメージファイルが含まれている Amazon S3 バケットの名前に置き換えます。

    aws rekognition detect-faces \ --image '{"S3Object":{"Bucket":"bucket","Name":"file"}}' \ --attributes "ALL"
    Python

    この例では、検出した顔の推定年齢範囲を表示し、すべての検出した顔属性の JSON を一覧表示します。photo の値は、イメージファイル名に変更します。bucket の値は、イメージの保存先の 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.) import boto3 import json if __name__ == "__main__": photo='input.jpg' bucket='bucket' client=boto3.client('rekognition') response = client.detect_faces(Image={'S3Object':{'Bucket':bucket,'Name':photo}},Attributes=['ALL']) print('Detected faces for ' + photo) for faceDetail in response['FaceDetails']: print('The detected face is between ' + str(faceDetail['AgeRange']['Low']) + ' and ' + str(faceDetail['AgeRange']['High']) + ' years old') print('Here are the other attributes:') print(json.dumps(faceDetail, indent=4, sort_keys=True))
    .NET

    この例では、検出した顔の推定年齢範囲を表示し、すべての検出した顔属性の JSON を一覧表示します。photo の値は、イメージファイル名に変更します。bucket の値は、イメージの保存先の 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 DetectFaces { public static void Example() { String photo = "input.jpg"; String bucket = "bucket"; AmazonRekognitionClient rekognitionClient = new AmazonRekognitionClient(); DetectFacesRequest detectFacesRequest = new DetectFacesRequest() { Image = new Image() { S3Object = new S3Object() { Name = photo, Bucket = bucket }, }, // Attributes can be "ALL" or "DEFAULT". // "DEFAULT": BoundingBox, Confidence, Landmarks, Pose, and Quality. // "ALL": See https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/Rekognition/TFaceDetail.html Attributes = new List<String>() { "ALL" } }; try { DetectFacesResponse detectFacesResponse = rekognitionClient.DetectFaces(detectFacesRequest); bool hasAll = detectFacesRequest.Attributes.Contains("ALL"); foreach(FaceDetail face in detectFacesResponse.FaceDetails) { Console.WriteLine("BoundingBox: top={0} left={1} width={2} height={3}", face.BoundingBox.Left, face.BoundingBox.Top, face.BoundingBox.Width, face.BoundingBox.Height); Console.WriteLine("Confidence: {0}\nLandmarks: {1}\nPose: pitch={2} roll={3} yaw={4}\nQuality: {5}", face.Confidence, face.Landmarks.Count, face.Pose.Pitch, face.Pose.Roll, face.Pose.Yaw, face.Quality); if (hasAll) Console.WriteLine("The detected face is estimated to be between " + face.AgeRange.Low + " and " + face.AgeRange.High + " years old."); } } catch (Exception e) { Console.WriteLine(e.Message); } } }

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

DetectFaces への入力はイメージです。以下の例では、イメージを Amazon S3 バケットからロードします。Attributes パラメータは、すべての顔属性を返すことを指定します。詳細については、「イメージの操作」を参照してください。

{ "Image": { "S3Object": { "Bucket": "bucket", "Name": "input.jpg" } }, "Attributes": [ "ALL" ] }

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

DetectFaces は、検出した顔ごとに以下の情報を返します。

  • 境界ボックス – 顔を囲む境界ボックスの座標。詳細については、「イメージの向きおよび境界ボックス座標の取得」を参照してください。

  • 信頼度 – 境界ボックス内に顔が含まれている信頼度。

  • 顔のランドマーク – 顔のランドマークの配列。ランドマーク (左目、右目、口など) ごとに X 座標と Y 座標がレスポンスで返されます。

  • 顔の属性 – 性別、顔にひげがあるかどうかなどの顔の属性のセット。レスポンスでは、顔属性ごとに値が返されます。値は、ブール値 (サングラスをしているかどうか) や文字列 (男性か女性か) など、さまざまな型で返される場合があります。また、ほとんどの属性では検出した値の信頼度も返されます。

  • 画質 – 顔の明るさとシャープネスを示します。できるだけ最良の顔検出を実現する方法については、「顔認識用の入力イメージに関する推奨事項」を参照してください。

  • ポーズ – イメージ内の顔のローテーションを示します。

  • 感情 – 感情と分析の信頼度のセット。

DetectFaces API コールのレスポンス例を以下に示します。

{ "FaceDetails": [ { "AgeRange": { "High": 36, "Low": 19 }, "Beard": { "Confidence": 99.99388122558594, "Value": false }, "BoundingBox": { "Height": 0.35353535413742065, "Left": 0.10707070678472519, "Top": 0.12777778506278992, "Width": 0.47138047218322754 }, "Confidence": 99.99736785888672, "Emotions": [ { "Confidence": 89.59288024902344, "Type": "HAPPY" }, { "Confidence": 5.3619384765625, "Type": "CALM" }, { "Confidence": 4.1074934005737305, "Type": "ANGRY" } ], "Eyeglasses": { "Confidence": 99.96102142333984, "Value": false }, "EyesOpen": { "Confidence": 99.97982788085938, "Value": true }, "Gender": { "Confidence": 100, "Value": "Female" }, "Landmarks": [ { "Type": "eyeLeft", "X": 0.23772846162319183, "Y": 0.2778792679309845 }, { "Type": "eyeRight", "X": 0.3944779932498932, "Y": 0.2527812421321869 }, { "Type": "nose", "X": 0.28617316484451294, "Y": 0.3367626965045929 }, { "Type": "mouthLeft", "X": 0.288897842168808, "Y": 0.4019121527671814 }, { "Type": "mouthRight", "X": 0.41363197565078735, "Y": 0.38766127824783325 }, { "Type": "leftPupil", "X": 0.25244733691215515, "Y": 0.27739065885543823 }, { "Type": "rightPupil", "X": 0.4029206931591034, "Y": 0.24940147995948792 }, { "Type": "leftEyeBrowLeft", "X": 0.17436790466308594, "Y": 0.24362699687480927 }, { "Type": "leftEyeBrowUp", "X": 0.21201953291893005, "Y": 0.2338741421699524 }, { "Type": "leftEyeBrowRight", "X": 0.2513192892074585, "Y": 0.24069637060165405 }, { "Type": "rightEyeBrowLeft", "X": 0.32193484902381897, "Y": 0.21918891370296478 }, { "Type": "rightEyeBrowUp", "X": 0.38548189401626587, "Y": 0.19604144990444183 }, { "Type": "rightEyeBrowRight", "X": 0.45430734753608704, "Y": 0.2027731090784073 }, { "Type": "leftEyeLeft", "X": 0.20944036543369293, "Y": 0.28281378746032715 }, { "Type": "leftEyeRight", "X": 0.2710888683795929, "Y": 0.2738289535045624 }, { "Type": "leftEyeUp", "X": 0.2339935451745987, "Y": 0.2687133252620697 }, { "Type": "leftEyeDown", "X": 0.23892717063426971, "Y": 0.28660306334495544 }, { "Type": "rightEyeLeft", "X": 0.36334219574928284, "Y": 0.2598327100276947 }, { "Type": "rightEyeRight", "X": 0.4293186664581299, "Y": 0.249033123254776 }, { "Type": "rightEyeUp", "X": 0.39038628339767456, "Y": 0.2431529313325882 }, { "Type": "rightEyeDown", "X": 0.3967171609401703, "Y": 0.26075780391693115 }, { "Type": "noseLeft", "X": 0.28841185569763184, "Y": 0.3598580062389374 }, { "Type": "noseRight", "X": 0.3451237976551056, "Y": 0.3516968786716461 }, { "Type": "mouthUp", "X": 0.3349839448928833, "Y": 0.38809144496917725 }, { "Type": "mouthDown", "X": 0.3422594964504242, "Y": 0.41868656873703003 } ], "MouthOpen": { "Confidence": 99.97990417480469, "Value": false }, "Mustache": { "Confidence": 99.97885131835938, "Value": false }, "Pose": { "Pitch": 1.0711474418640137, "Roll": -10.933034896850586, "Yaw": -25.838171005249023 }, "Quality": { "Brightness": 43.86729431152344, "Sharpness": 99.95819854736328 }, "Smile": { "Confidence": 96.89310455322266, "Value": true }, "Sunglasses": { "Confidence": 80.4033432006836, "Value": false } } ] }

次の点に注意してください。

  • Pose データは、検出された顔のローテーションを示します。BoundingBoxPose データを組み合わせると、アプリケーションで表示する顔の回りに境界ボックスを描画できます。

  • Quality は、顔の明るさとシャープネスを示します。複数のイメージ間で顔を比較し、最善の顔を見つける場合に役立ちます。

  • DetectFaces オペレーションでは、顔の特徴を検出する前に、入力イメージの向きを検出します。レスポンスの OrientationCorrection は、検出したローテーションの角度 (反時計回り) を返します。アプリケーションでは、この値を使用して向きを修正してからイメージを表示できます。

  • 前のレスポンスは、サービスが検出できるすべての顔の landmarks、顔属性、および感情を示しています。これらのすべてをレスポンスで取得するには、attributes パラメータを使用し、値として ALL を指定します。デフォルトでは、DetectFaces API が返す顔属性は BoundingBoxConfidencePoseQuality、および landmarks の 5 つのみです。デフォルトで返されるランドマークは、eyeLefteyeRightnosemouthLeft、および mouthRight です。

  • 次の図は、DetectFaces API オペレーションで返される顔ランドマーク (Landmarks) の相対的な位置を示しています。

イメージ上のラベルは、次の表に示す Landmark データ型に対応します。見やすくするために、左目と右目のランドマークポイントはイメージに表示されていません。

ラベル ランドマーク

b_ll

leftEyeBrowLeft (左眉左側)

b_lu

leftEyeBrowUp (左眉上)

b_lr

leftEyeBrowRight (左眉右側)

e_ll

leftEyeLeft

e_lu

leftEyeUp

e_lr

leftEyeRight

e_ld

leftEyeDown

e_lp

leftPupil (左瞳孔)

n_l

noseLeft

n

nose (鼻)

n_r

noseRight

m_u

mouthUp

m_d

mouthDown

m_l

mouthLeft (左口角)

m_r

mouthRight (右口角)

b_rl

rightEyeBrowLeft (右眉左側)

b_ru

rightEyeBrowUp (右眉上)

b_rr

rightEyeBrowRight (右眉右側)

e_rl

rightEyeLeft

e_ru

rightEyeUp

e_rr

rightEyeRight

e_rp

rightPupil (右瞳孔)

e_rd

rightEyeDown