将人脸添加到集合 - Amazon Rekognition

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

将人脸添加到集合

您可以使用该IndexFaces操作来检测图像中的人脸并将其添加到集合中。对于检测到的每张人脸,Amazon Rekognition 将提取人脸特征并将特征信息存储到数据库中。此外,该命令将检测到的每个人脸的元数据存储在指定的人脸集合中。Amazon Rekognition 不存储实际的图像字节。

有关提供合适的人脸用于编制索引的信息,请参阅有关面部比较输入图像的建议

对于每个人脸,IndexFaces 操作保留以下信息:

  • 多维人脸特征IndexFaces 使用人脸分析来提取有关人脸特征的多维信息,并将该信息存储在人脸集合中。您无法直接访问此信息。不过,Amazon Rekognition 在人脸集合中搜索匹配的人脸时将使用此信息。

     

  • 元数据 – 每个人脸的元数据在请求中包括一个边界框、置信度级别(边界框包含人脸)、由 Amazon Rekognition 分配的 ID(人脸 ID 和图像 ID)和一个外部图像 ID (如果已提供)。在响应 IndexFaces API 调用时,将为您返回此信息。有关示例,请参阅以下示例响应中的 face 元素。

    该服务将返回此元数据以响应以下 API 调用:

     

IndexFaces 编入索引的人脸数量取决于与输入集合关联的人脸检测模型的版本。有关更多信息,请参阅 模型版本控制

有关索引面孔的信息以FaceRecord对象数组的形式返回。

您可能希望将索引的人脸与检测到人脸的图像相关联。例如,您可能想要保留图像的客户端索引和图像中的人脸。要将人脸与图像关联,请在 ExternalImageId 请求参数中指定图像 ID。图像 ID 可以是您创建的文件名或其他 ID。

除了 API 在人脸集合中保留的前面的信息之外,API 还返回集合中未保留的人脸详细信息。(请参阅以下示例响应中的 faceDetail 元素)。

注意

DetectFaces 将返回相同的信息,因此您无需对同一张图像调用 DetectFacesIndexFaces

筛选人脸

该 IndexFaces 操作使您可以过滤从图像中编制索引的面孔。借助 IndexFaces,您可以指定要编制索引的人脸的最大数目,也可以选择仅为检测到的高质量人脸编制索引。

您可以使用 MaxFaces 输入参数指定由 IndexFaces 编制索引的人脸的最大数目。当您想为图像中的最大人脸编制索引而不想对较小人脸(例如,背景中站立的人的脸)编制索引时,这很有用。

默认情况下, IndexFaces 选择用于筛选出人脸的质量条。您可以使用 QualityFilter 输入参数显式设置质量条。值为:

  • AUTO – Amazon Rekognition 选择用于筛选出人脸的质量条(默认值)。

  • LOW – 除了最低质量人脸之外的所有人脸都将进行索引。

  • MEDIUM

  • HIGH – 仅对质量最高的人脸进行索引。

  • NONE -不会根据质量筛选出任何人脸。

IndexFaces 根据以下条件筛选出人脸:

  • 与图像尺寸相比,人脸太小。

  • 人脸太模糊。

  • 图像太暗。

  • 人脸的姿势很极端。

  • 人脸没有足够的细节,不适合人脸搜索。

注意

要使用质量筛选,您需要一个与版本 3 或更高版本的人脸模型关联的集合。要获取与集合关联的人脸模型版本,请调用DescribeCollection

有关未被索引的人脸的信息将以IndexFacesUnindexedFace对象数组的形式返回。Reasons 数组包含有关未为人脸编制索引的原因的列表。例如,值 EXCEEDS_MAX_FACES 表示未为人脸编制索引,因为检测到的人脸数已达到 MaxFaces 所指定的人脸数。

有关更多信息,请参阅 管理集合中的人脸

将人脸添加到集合 (SDK)
  1. 如果您尚未执行以下操作,请:

    1. 使用 AmazonRekognitionFullAccessAmazonS3ReadOnlyAccess 权限创建或更新用户。有关更多信息,请参阅 步骤 1:设置 AWS 账户并创建用户

    2. 安装和配置 AWS CLI 和 AWS SDK。有关更多信息,请参阅 第 2 步:设置 AWS CLI 和 AWS 软件开发工具包

  2. 将图像(包含一个或多个人脸)上传到您的 Amazon S3 存储桶。

    有关说明,请参阅《Amazon Simple Storage Service 用户指南》中的将对象上传到 Amazon S3

  3. 使用以下示例调用 IndexFaces 操作。

    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.QualityFilter; 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); } } } }
    Java V2

    此代码取自 AWS 文档 SDK 示例 GitHub 存储库。请在此处查看完整示例。

    //snippet-start:[rekognition.java2.add_faces_collection.import] import software.amazon.awssdk.auth.credentials.ProfileCredentialsProvider; import software.amazon.awssdk.core.SdkBytes; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.rekognition.RekognitionClient; import software.amazon.awssdk.services.rekognition.model.IndexFacesResponse; import software.amazon.awssdk.services.rekognition.model.IndexFacesRequest; import software.amazon.awssdk.services.rekognition.model.Image; import software.amazon.awssdk.services.rekognition.model.QualityFilter; import software.amazon.awssdk.services.rekognition.model.Attribute; import software.amazon.awssdk.services.rekognition.model.FaceRecord; import software.amazon.awssdk.services.rekognition.model.UnindexedFace; import software.amazon.awssdk.services.rekognition.model.RekognitionException; import software.amazon.awssdk.services.rekognition.model.Reason; import java.io.FileInputStream; import java.io.FileNotFoundException; import java.io.InputStream; import java.util.List; //snippet-end:[rekognition.java2.add_faces_collection.import] /** * Before running this Java V2 code example, set up your development environment, including your credentials. * * For more information, see the following documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class AddFacesToCollection { public static void main(String[] args) { final String usage = "\n" + "Usage: " + " <collectionId> <sourceImage>\n\n" + "Where:\n" + " collectionName - The name of the collection.\n" + " sourceImage - The path to the image (for example, C:\\AWS\\pic1.png). \n\n"; if (args.length != 2) { System.out.println(usage); System.exit(1); } String collectionId = args[0]; String sourceImage = args[1]; Region region = Region.US_EAST_1; RekognitionClient rekClient = RekognitionClient.builder() .region(region) .credentialsProvider(ProfileCredentialsProvider.create("profile-name")) .build(); addToCollection(rekClient, collectionId, sourceImage); rekClient.close(); } // snippet-start:[rekognition.java2.add_faces_collection.main] public static void addToCollection(RekognitionClient rekClient, String collectionId, String sourceImage) { try { InputStream sourceStream = new FileInputStream(sourceImage); SdkBytes sourceBytes = SdkBytes.fromInputStream(sourceStream); Image souImage = Image.builder() .bytes(sourceBytes) .build(); IndexFacesRequest facesRequest = IndexFacesRequest.builder() .collectionId(collectionId) .image(souImage) .maxFaces(1) .qualityFilter(QualityFilter.AUTO) .detectionAttributes(Attribute.DEFAULT) .build(); IndexFacesResponse facesResponse = rekClient.indexFaces(facesRequest); System.out.println("Results for the image"); System.out.println("\n Faces indexed:"); List<FaceRecord> faceRecords = facesResponse.faceRecords(); for (FaceRecord faceRecord : faceRecords) { System.out.println(" Face ID: " + faceRecord.face().faceId()); System.out.println(" Location:" + faceRecord.faceDetail().boundingBox().toString()); } List<UnindexedFace> unindexedFaces = facesResponse.unindexedFaces(); System.out.println("Faces not indexed:"); for (UnindexedFace unindexedFace : unindexedFaces) { System.out.println(" Location:" + unindexedFace.faceDetail().boundingBox().toString()); System.out.println(" Reasons:"); for (Reason reason : unindexedFace.reasons()) { System.out.println("Reason: " + reason); } } } catch (RekognitionException | FileNotFoundException e) { System.out.println(e.getMessage()); System.exit(1); } } // snippet-end:[rekognition.java2.add_faces_collection.main] }
    AWS CLI

    此 AWS CLI 命令显示 index-faces CLI 操作的 JSON 输出。

    collection-id 的值替换为您希望在其中存储人脸的集合的名称。将BucketName的值替换为您在步骤 2 中使用的 Amazon S3 存储桶和图像文件。max-faces 参数将索引的人脸数限制为 1。删除或更改其值以满足您的需求。将创建 Rekognition 会话的行中的profile_name值替换为您的开发人员资料的名称。

    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" --profile profile-name

    如果您在 Windows 设备上访问 CLI,请使用双引号代替单引号,并用反斜杠(即 \)对内部双引号进行转义,以解决可能遇到的任何解析器错误。例如,请参阅以下内容:

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

    此示例显示添加到集合的人脸的人脸标识符。

    collectionId 的值更改为您要向其中添加人脸的集合的名称。将bucketphoto的值替换为您在步骤 2 中使用的 Amazon S3 存储桶和图像的名称。MaxFaces 输入参数将索引的人脸数限制为 1。删除或更改其值以满足您的需求。将创建 Rekognition 会话的行中的profile_name值替换为您的开发人员资料的名称。

    # 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 def add_faces_to_collection(bucket, photo, collection_id): session = boto3.Session(profile_name='profile-name') client = session.client('rekognition') response = client.index_faces(CollectionId=collection_id, 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) return len(response['FaceRecords']) def main(): bucket = 'bucket-name' collection_id = 'collection-id' photo = 'photo-name' indexed_faces_count = add_faces_to_collection(bucket, photo, collection_id) print("Faces indexed count: " + str(indexed_faces_count)) if __name__ == "__main__": main()
    .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 个人脸标记)

  • 十个人脸属性(眼镜、胡须、遮挡、视线方向等)

  • 情绪(请参阅 emotion 元素)

face 元素提供了服务器上保留的元数据。

FaceModelVersion 是与集合关联的人脸模型的版本。有关更多信息,请参阅 模型版本控制

OrientationCorrection 是估计的图像方向。如果您使用的是高于版本 3 的人脸检测模型版本,则不会返回方向校正信息。有关更多信息,请参阅 获取图像方向和边界框坐标

以下示例响应显示了指定 ["ALL"] 时返回的 JSON:

{ "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" } ], "EyeDirection": { "yaw": 16.299732, "pitch": -6.407457, "confidence": 99.968704 } "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": [] }