CompareFaces - Amazon Rekognition

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

CompareFaces

内のフェースを比較しますsourceで検出された最大100面のそれぞれを持つ入力画像をtarget入力イメージ。

ソースイメージ内に複数の顔がある場合は、サービスでは最大サイズの顔を検出して、その顔とターゲットイメージ内で検出された各顔を比較します。

注記

CompareFacesは、確率的である機械学習アルゴリズムを使用します。偽陰性とは、ターゲット画像の顔がソース画像の顔と比較して類似度信頼度スコアが低いという誤った予測です。偽陰性の可能性を減らすために、ターゲット画像を複数のソース画像と比較することをお勧めします。を使用する予定の場合は、CompareFacesが個人の権利、プライバシー、またはサービスへのアクセスに影響する決定を下す場合は、アクションを実行する前に、その結果を人間に渡して確認し、さらに検証することをお勧めします。

入力イメージとターゲットイメージは、base64 エンコードされたイメージバイトとして、または Amazon S3 バケット内のイメージへの参照として渡します。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、イメージのバイトを渡すことはサポートされていません。画像は、PNG または JPEG ファイルとしてフォーマットする必要があります。

レスポンスとして、オペレーションでは、類似度スコアでソートされた顔の一致の配列を返します。顔のマッチごとに、顔のバウンディングボックス、顔のランドマーク、ポーズの詳細(ピッチ、ロール、ヨー)、品質(明るさとシャープネス)、および信頼度(バウンディングボックスに顔が含まれていることの信頼度を示す)が提供されます。応答はまた、顔がどの程度一致するかを示す類似度スコアを提供します。

注記

デフォルトでは、類似度スコアが 80% 以上の面のみが応答で返されます。この値は、指定して、変更することができます。SimilarityThresholdパラメータ。

CompareFacesは、ソースイメージと一致しない面の配列も返します。フェースごとに、バウンディングボックス、信頼値、ランドマーク、ポーズの詳細、および品質を返します。レスポンスでは、ソースイメージ内の顔に関する情報 (および顔の境界ボックスと信頼値) も返されます。

-QualityFilter入力パラメータを使用すると、必要な品質基準を満たさない検出されたフェースを除外できます。品質バーは、さまざまな一般的なユースケースに基づいています。を使用するQualityFilterを使用して、品質バーを設定します。LOW,MEDIUM, またはHIGH。検出された面をフィルタしない場合は、NONE。デフォルト値は NONE です。

画像に Exif メタデータが含まれていない場合は、CompareFacesは、ソースイメージとターゲットイメージの方向情報を返します。これらの値を使用して、正しいイメージの向きでイメージを表示します。

ソースイメージまたはターゲットイメージで面が検出されない場合、CompareFaces戻り値はInvalidParameterExceptionというエラーが表示される。

注記

これはステートレス API 操作です。つまり、この操作によって返されるデータは保持されません。

例については、「イメージ内の顔の比較」を参照してください。

このオペレーションには rekognition:CompareFaces アクションを実行するアクセス許可が必要です。

リクエストの構文

{ "QualityFilter": "string", "SimilarityThreshold": number, "SourceImage": { "Bytes": blob, "S3Object": { "Bucket": "string", "Name": "string", "Version": "string" } }, "TargetImage": { "Bytes": blob, "S3Object": { "Bucket": "string", "Name": "string", "Version": "string" } } }

リクエストパラメータ

リクエストは以下のデータを JSON 形式で受け入れます。

QualityFilter

面を識別するために行われるフィルタの量を示す品質バーを指定するフィルタです。フィルタされた面は比較されません。指定すると、AUTOでは、Amazon Rekognition が品質バーを選択します。指定すると、LOW,MEDIUM, またはHIGHを選択すると、フィルタ処理によって、選択した品質バーに適合しないすべての面が削除されます。品質バーは、さまざまな一般的なユースケースに基づいています。低品質の検出は、さまざまな理由で発生する可能性があります。たとえば、顔と誤認されるオブジェクト、ぼやけた顔、極端すぎるポーズの顔などがあります。指定すると、NONEの場合、フィルタリングは実行されません。デフォルト値は NONE です。

品質のフィルタリングを使用するには、使用するコレクションがバージョン 3 以上の顔モデルに関連付けられている必要があります。

Type: 文字列

有効な値: NONE | AUTO | LOW | MEDIUM | HIGH

必須: いいえ

SimilarityThreshold

マッチが満たす必要のあるフェイスマッチの最小信頼レベルは、FaceMatches配列です。

Type: 浮動小数点

有効範囲: 最小値は 0 です。最大値は 100 です。

必須: いいえ

SourceImage

base64 でエンコードされたバイトまたは S3 オブジェクトとしての入力イメージ。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、base64 でエンコードされたイメージのバイトを渡すことはサポートされていません。

AWS SDK を使用して Amazon Rekognition を呼び出す場合は、Bytesフィールド。詳細については、「イメージの仕様」を参照してください。

タイプ: Image オブジェクト

必須: はい

TargetImage

base64 でエンコードされたバイトまたは S3 オブジェクトとしてのターゲットイメージ。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、base64 でエンコードされたイメージのバイトを渡すことはサポートされていません。

AWS SDK を使用して Amazon Rekognition を呼び出す場合は、Bytesフィールド。詳細については、「イメージの仕様」を参照してください。

タイプ: Image オブジェクト

必須: はい

レスポンスの構文

{ "FaceMatches": [ { "Face": { "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "Emotions": [ { "Confidence": number, "Type": "string" } ], "Landmarks": [ { "Type": "string", "X": number, "Y": number } ], "Pose": { "Pitch": number, "Roll": number, "Yaw": number }, "Quality": { "Brightness": number, "Sharpness": number }, "Smile": { "Confidence": number, "Value": boolean } }, "Similarity": number } ], "SourceImageFace": { "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number }, "SourceImageOrientationCorrection": "string", "TargetImageOrientationCorrection": "string", "UnmatchedFaces": [ { "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "Emotions": [ { "Confidence": number, "Type": "string" } ], "Landmarks": [ { "Type": "string", "X": number, "Y": number } ], "Pose": { "Pitch": number, "Roll": number, "Yaw": number }, "Quality": { "Brightness": number, "Sharpness": number }, "Smile": { "Confidence": number, "Value": boolean } } ] }

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

サービスから以下のデータが JSON 形式で返されます。

FaceMatches

ソースイメージの顔と一致するターゲットイメージ内の顔の配列。EachCompareFacesMatchオブジェクトは、バウンディングボックス、バウンディングボックスに面が含まれている信頼レベル、バウンディングボックス内の面とソースイメージ内の面の類似度スコアを提供します。

Type: の配列 CompareFacesMatch objects

SourceImageFace

比較に使用されたソースイメージの顔です。

タイプ: ComparedSourceImageFace オブジェクト

SourceImageOrientationCorrection

valueSourceImageOrientationCorrectionnull です。

入力イメージが .jpeg 形式の場合、イメージの方向を含む交換可能なイメージファイル形式 (Exif) メタデータが含まれる場合があります。Amazon Rekognition は、この方向情報を使用して画像補正を行います。Exif メタデータの方向情報を使用してイメージの方向を修正すると、バウンディングボックスの座標がオブジェクトの位置を表すように変換されます。.png 形式のイメージには Exif メタデータが含まれていません。

Amazon Rekognition は、画像 Exif メタデータに向き情報がない.png 形式の画像および.jpeg 画像の画像補正を実行しません。バウンディングボックスの座標は変換されず、イメージが回転される前のオブジェクトの位置を表します。

Type: 文字列

有効な値: ROTATE_0 | ROTATE_90 | ROTATE_180 | ROTATE_270

TargetImageOrientationCorrection

valueTargetImageOrientationCorrectionnull です。

入力イメージが .jpeg 形式の場合、イメージの方向を含む交換可能なイメージファイル形式 (Exif) メタデータが含まれる場合があります。Amazon Rekognition は、この方向情報を使用して画像補正を行います。Exif メタデータの方向情報を使用してイメージの方向を修正すると、バウンディングボックスの座標がオブジェクトの位置を表すように変換されます。.png 形式のイメージには Exif メタデータが含まれていません。

Amazon Rekognition は、画像 Exif メタデータに向き情報がない.png 形式の画像および.jpeg 画像の画像補正を実行しません。バウンディングボックスの座標は変換されず、イメージが回転される前のオブジェクトの位置を表します。

Type: 文字列

有効な値: ROTATE_0 | ROTATE_90 | ROTATE_180 | ROTATE_270

UnmatchedFaces

ターゲットイメージ内の顔で、ソースイメージの顔と一致しなかった顔配列。

Type: の配列 ComparedFace objects

Errors

AccessDeniedException

アクションを実行する権限がありません。

HTTP ステータスコード:HTTP ステータスコード 400

ImageTooLargeException

入力イメージサイズが制限文字数を超えています。あなたが呼び出す場合 DetectProtectiveEquipment 画像サイズまたは解像度が制限文字数を超えています。詳細については、「Amazon Rekognition のガイドラインとクォータ」を参照してください。

HTTP ステータスコード:HTTP ステータスコード 400

InternalServerError

Amazon Rekognition でサービスの問題が発生しました。もう一度やり直してください。

HTTP ステータスコード:HTTP ステータスコード 500

InvalidImageFormatException

指定されたイメージ形式はサポートされていません。

HTTP ステータスコード:HTTP ステータスコード 400

InvalidParameterException

入力パラメータが制約に違反しています。API オペレーションを再度呼び出す前にパラメータを検証します。

HTTP ステータスコード:HTTP ステータスコード 400

InvalidS3ObjectException

Amazon Rekognition は、リクエストで指定された S3 オブジェクトにアクセスできません。

HTTP ステータスコード:HTTP ステータスコード 400

ProvisionedThroughputExceededException

お客様のスループット制限を超えたリクエストの数。この上限を引き上げる場合は、Amazon Rekognition までお問い合わせください。

HTTP ステータスコード:HTTP ステータスコード 400

ThrottlingException

Amazon Rekognition は一時的にリクエストを処理できませんでした。もう一度やり直してください。

HTTP ステータスコード:HTTP ステータスコード 500

以下の資料も参照してください。

言語固有の API のいずれかでこの API を使用する方法の詳細については、AWSSDK については、以下を参照してください。