Adicionar faces a uma coleção - Amazon Rekognition

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Adicionar faces a uma coleção

Você pode usar a operação IndexFaces para detectar faces em uma imagem e adicioná-las a uma coleção. Para cada face detectada, o Amazon Rekognition extrai traços faciais e armazena as informações dos traços em um banco de dados. Além disso, o comando armazena metadados de cada face detectada na coleção de faces especificada. O Amazon Rekognition não armazena os bytes de imagem reais.

Para obter informações sobre como fornecer faces adequadas para a indexação, consulte Recomendações para imagens de entrada de comparação facial.

Para cada face, a operação IndexFaces mantém as seguintes informações:

  • Características faciais multidimensionaisIndexFacesO usa análises faciais para extrair informações multidimensionais sobre os traços faciais e armazena as informações na coleção. Você não pode acessar essas informações diretamente. No entanto, o Amazon Rekognition usa essas informações ao pesquisar uma coleção de faces em busca de correspondências de face.

     

  • Metadados— Entre os metadados de cada face estão uma caixa delimitadora, o nível de confiança (a caixa delimitadora contém uma face), os IDs atribuídos pelo Amazon Rekognition (ID da face e ID da imagem) e um ID da imagem externa (se fornecido) na solicitação. Essas informações são retornadas para você em resposta para a chamada à API IndexFaces. Para obter um exemplo, consulte o elemento face na resposta de exemplo a seguir.

    O serviço retorna esses metadados em resposta para as seguintes chamadas à API:

     

    • ListFaces

    • Pesquisar operações de faces – As respostas para SearchFaces e SearchFacesByImage retornam a confiança na correspondência de cada face, além desses metadados da face correspondente.

O número de faces indexadas por IndexFaces depende da versão do modelo de detecção de faces associado à coleção de entrada. Para obter mais informações, consulte Versionamento de modelo.

As informações sobre faces indexadas são retornadas em uma matriz de objetos FaceRecord.

Você pode desejar associar faces indexadas com a imagem em que foram detectadas. Por exemplo, você pode desejar manter um índice de cliente de imagens e faces nas imagens. Para associar faces a uma imagem, especifique um ID de imagem no parâmetro da solicitação ExternalImageId. O ID da imagem pode ser o nome do arquivo ou outro ID que você criar.

Além das informações anteriores que a API mantém na coleção de faces, a API também retorna detalhes da face que não são mantidos na coleção. (Consulte o elemento faceDetail na resposta de exemplo a seguir.)

nota

O DetectFaces retorna as mesmas informações, portanto, você não precisa chamar DetectFaces e IndexFaces para a mesma imagem.

Filtro de faces

A operação IndexFaces permite que você filtre as faces que são indexadas de uma imagem. Com IndexFaces, você pode especificar um número máximo de faces a serem indexadas ou pode escolher apenas faces detectadas com um índice de alta qualidade.

Você pode especificar o número máximo de faces que são indexadas por IndexFaces usando o parâmetro de entrada MaxFaces. Isso é útil quando você deseja indexar as maiores faces em uma imagem e não deseja indexar as faces menores, como as faces de pessoas em segundo plano.

Por padrão, IndexFaces escolhe um requisito de qualidade que é usado para filtrar faces. É possível usar o parâmetro de entrada QualityFilter para definir explicitamente o requisito de qualidade. Os valores são:

  • AUTO— O Amazon Rekognition escolhe a barra de qualidade usada para filtrar faces (valor padrão).

  • LOW— todas, exceto as faces de qualidade mais baixa, são indexadas.

  • MEDIUM

  • HIGH— Apenas as faces de qualidade mais alta são indexadas.

  • NONE – nenhuma face é filtrada com base na qualidade.

IndexFaces filtra faces pelos seguintes motivos:

  • A face é muito pequena em comparação com as dimensões da imagem.

  • A face está muito embaçada.

  • A imagem é muito escura.

  • A face tem uma pose radical.

  • A face não tem detalhes suficientes para ser adequada à pesquisa de faces.

nota

Para usar a filtragem de qualidade, é necessário ter uma coleção associada à versão 3, ou posterior, do modelo de faces. Para obter a versão do modelo de face associado a uma coleção, chame DescribeCollection.

As informações sobre faces que não estão indexadas por IndexFaces são retornadas em uma matriz de objetos do UnindexedFace. A matriz de Reasons contém uma lista dos motivos pelos quais uma face não é indexada. Por exemplo, um valor de EXCEEDS_MAX_FACES é uma face que não foi indexada porque o número de faces especificado pelo MaxFaces já foi detectado.

Para obter mais informações, consulte Gerenciar faces em uma coleção.

Para adicionar faces a uma coleção (SDK)

  1. Se ainda não tiver feito isso:

    1. Criar ou atualizar um usuário do IAM comAmazonRekognitionFullAccesseAmazonS3ReadOnlyAccessPermissões Para obter mais informações, consulte Etapa 1: Configurar uma conta da AWS e criar um usuário do IAM.

    2. Instale e configure a AWS CLI e os SDKs da AWS. Para obter mais informações, consulte Etapa 2: Configurar aAWS CLIeAWSSDKs da.

  2. Carregue uma imagem (contendo uma ou mais faces) no bucket do Amazon S3.

    Para obter instruções, consulteFazer upload de objetos no Amazon S3noGuia do usuário do Amazon Simple Storage Service.

  3. Use os exemplos a seguir para chamar a operação IndexFaces.

    Java

    Este exemplo exibe os identificadores para faces adicionadas à coleção.

    Altere o valor de collectionId para o nome da coleção a que você deseja adicionar uma face. Substitua os valores debucketephotoCom os nomes do bucket do Amazon S3 e da imagem usada na etapa 2. O parâmetro .withMaxFaces(1) restringe o número de faces indexadas a 1. Remova ou altere seu valor para atender às suas necessidades.

    //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

    Esse código é capturado segundo oAWSExemplos de SDK de documentação do repositório GitHub do. Veja o exemplo completoaqui.

    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); // Display the results. 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); } }
    AWS CLI

    Esse comando da AWS CLI exibe a saída JSON da operação da CLI index-faces.

    Substitua o valor de collection-id pelo nome da coleção em que você deseja que a face seja armazenada. Substitua os valores deBucketeNameCom o bucket do Amazon S3 e o nome do arquivo de imagem usado na etapa 2. O parâmetro max-faces restringe o número de faces indexadas a 1. Remova ou altere seu valor para atender às suas necessidades.

    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

    Este exemplo exibe os identificadores para faces adicionadas à coleção.

    Altere o valor de collectionId para o nome da coleção a que você deseja adicionar uma face. Substitua os valores debucketephotoCom os nomes do bucket do Amazon S3 e da imagem usada na etapa 2. O parâmetro de entrada MaxFaces restringe o número de faces indexadas a 1. Remova ou altere seu valor para atender às suas necessidades.

    #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): client=boto3.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' collection_id='collection' photo='photo' indexed_faces_count=add_faces_to_collection(bucket, photo, collection_id) print("Faces indexed count: " + str(indexed_faces_count)) if __name__ == "__main__": main()
    .NET

    Este exemplo exibe os identificadores para faces adicionadas à coleção.

    Altere o valor de collectionId para o nome da coleção a que você deseja adicionar uma face. Substitua os valores debucketephotoCom os nomes do bucket do Amazon S3 e da imagem usada na etapa 2.

    //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); } }

Solicitação da operação IndexFaces

A entrada para IndexFaces é a imagem a ser indexada e a coleção à qual adicionar a face ou as faces.

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

Resposta da operação IndexFaces

IndexFaces retorna informações sobre as faces que foram detectadas na imagem. Por exemplo, a resposta JSON a seguir inclui os atributos de detecção padrão para faces detectadas na imagem de entrada. O exemplo também mostra faces não indexadas porque o valor doMaxFacesparâmetro de entrada foi excedido — oReasonsarray contémEXCEEDS_MAX_FACES. Se uma face não for indexada por motivos de qualidade, Reasons conterá valores como LOW_SHARPNESS ou LOW_BRIGHTNESS. Para obter mais informações, consulte 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" ] } ] }

Para obter todas as informações faciais, especifique 'ALL' para o parâmetro de solicitação DetectionAttributes. Por exemplo, na resposta do exemplo a seguir, observe as informações adicionais no elemento faceDetail, que não é mantido no servidor:

  • 25 pontos de referência faciais (em comparação com apenas cinco no exemplo anterior)

  • Nove atributos faciais (óculos, barba etc.)

  • Emoções (consulte o elemento emotion)

O elemento face fornece metadados que são mantidos no servidor.

FaceModelVersion é a versão do modelo de face associado à coleção. Para obter mais informações, consulte Versionamento de modelo.

OrientationCorrection é a orientação estimada da imagem. As informações de correção de orientação não serão retornadas se você estiver usando uma versão do modelo de detecção facial que seja superior à versão 3. Para obter mais informações, consulte Obtendo orientação da imagem e coordenadas da caixa delimitadora.

{ "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": [] }