CompareFaces - 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á.

CompareFaces

Compara um rosto nofonteimagem de entrada com cada uma das 100 maiores faces detectadas nometaimagem de entrada.

Se a imagem de origem contiver várias faces, o serviço detectará a maior e a compara com cada face detectada na imagem de destino.

nota

O CompareFaces usa algoritmos de aprendizado de máquina, que são probabilísticos. Um falso negativo é uma previsão incorreta de que uma face na imagem de destino tem um baixo índice de confiança de similaridade quando comparado ao rosto na imagem de origem. Para reduzir a probabilidade de falsos negativos, recomendamos que você compare a imagem de destino com várias imagens de origem. Se você planeja usarCompareFacespara tomar uma decisão que impacta os direitos, a privacidade ou o acesso a serviços de um indivíduo, recomendamos que você passe o resultado para um ser humano para revisão e validação adicional antes de tomar medidas.

Você passa as imagens de entrada e de destino como bytes de imagem codificados em base64 ou como referências a imagens em um bucket do Amazon S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não será oferecido o suporte à passagem de bytes da imagem. A imagem deve ser formatada como um arquivo PNG ou JPEG.

Em resposta, a operação retorna uma matriz de correspondências de face ordenadas por pontuação de similaridade em ordem decrescente. Para cada correspondência de face, a resposta fornece uma caixa delimitadora do rosto, pontos de referência faciais, detalhes de pose (pitch, roll e guinada), qualidade (brilho e nitidez) e valor de confiança (indicando o nível de confiança de que a caixa delimitadora contém um rosto). A resposta também fornece uma pontuação de similaridade, que indica o quão próximo as faces correspondem.

nota

Por padrão, apenas faces com uma pontuação de similaridade maior ou igual a 80% são retornadas na resposta. Você pode alterar esse valor especificando aSimilarityThresholdparâmetro .

CompareFacestambém retorna uma matriz de faces que não correspondem à imagem de origem. Para cada face, ele retorna uma caixa delimitadora, valor de confiança, pontos de referência, detalhes de pose e qualidade. A resposta também retorna informações sobre a face na imagem de origem, incluindo a caixa delimitadora da face e o valor de confiança.

OQualityFilterparâmetro de entrada permite filtrar faces detectadas que não atendem a uma barra de qualidade necessária. A barra de qualidade é baseada em uma variedade de casos de uso comuns. Usar oQualityFilterpara definir a barra de qualidade especificandoLOW,MEDIUM, ouHIGH. Se você não quiser filtrar faces detectadas, especifiqueNONE. O valor padrão é NONE.

Se a imagem não contiver metadados Exif,CompareFacesretorna informações de orientação para as imagens de origem e destino. Use esses valores para exibir as imagens com a orientação de imagem correta.

Se nenhuma face for detectada nas imagens de origem ou de destino,CompareFacesretorna umInvalidParameterExceptionERROR

nota

Esta é uma operação de API sem estado. Ou seja, os dados retornados por essa operação não persistem.

Para ver um exemplo, consulte Comparação de faces em imagens.

Essa operação exige permissões para executar a ação rekognition:CompareFaces.

Sintaxe da solicitação

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

Parâmetros de solicitação

A solicitação aceita os dados a seguir no formato JSON.

QualityFilter

Um filtro que especifica uma barra de qualidade para quanta filtragem é feita para identificar rostos. As faces filtradas não são comparadas. Se você especificarAUTO, o Amazon Rekognition escolhe a barra de qualidade. Se você especificarLOW,MEDIUM, ouHIGH, a filtragem remove todas as faces que não atendem à barra de qualidade escolhida. A barra de qualidade é baseada em uma variedade de casos de uso comuns. Detecções de baixa qualidade podem ocorrer por uma série de razões. Alguns exemplos são um objeto identificado erroneamente como um rosto, um rosto muito embaçado ou um rosto com uma pose muito extrema para usar. Se você especificarNONE, nenhuma filtragem é executada. O valor padrão é NONE.

Para usar a filtragem de qualidade, a coleção que você está usando deve estar associada com a versão 3 do modelo de faces ou posterior.

Type: String

Valores válidos: NONE | AUTO | LOW | MEDIUM | HIGH

: obrigatório Não

SimilarityThreshold

O nível mínimo de confiança na face corresponde que uma partida deve atender para ser incluída noFaceMatchesmatriz.

Type: Float

Intervalo válido Valor mínimo de 0. Valor máximo de 100.

: obrigatório Não

SourceImage

A imagem de entrada como bytes codificados em base64 ou um objeto S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não será oferecido o suporte à passagem de bytes de imagem codificados em base64.

Se você estiver usando um AWS SDK para chamar o Amazon Rekognition, talvez não seja necessário codificar bytes de imagem com base 64 passados usando oBytescampo. Para obter mais informações, consulte Especificações.

Tipo: objeto Image

: obrigatório Sim

TargetImage

A imagem de destino como bytes codificados em base64 ou um objeto S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não será oferecido o suporte à passagem de bytes de imagem codificados em base64.

Se você estiver usando um AWS SDK para chamar o Amazon Rekognition, talvez não seja necessário codificar bytes de imagem com base 64 passados usando oBytescampo. Para obter mais informações, consulte Especificações.

Tipo: objeto Image

: obrigatório Sim

Sintaxe da resposta

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

Elementos de resposta

Se a ação for bem-sucedida, o serviço reenviará uma resposta HTTP 200.

Os seguintes dados são retornados no formato JSON pelo serviço.

FaceMatches

Uma matriz de faces na imagem de destino que correspondam à face da imagem de origem. EACHCompareFacesMatcho objeto fornece a caixa delimitadora, o nível de confiança que a caixa delimitadora contém uma face e a pontuação de similaridade para a face na caixa delimitadora e a face na imagem de origem.

Type: Matriz deCompareFacesMatchobjetos

SourceImageFace

O rosto na imagem de origem que foi usada para comparação.

Tipo: objeto ComparedSourceImageFace

SourceImageOrientationCorrection

O valor deSourceImageOrientationCorrectioné sempre nulo.

Se a imagem de entrada estiver no formato.jpeg, ela poderá conter metadados em formato Exif. O Amazon Rekognition usa essas informações de orientação para executar a correção de imagem. As coordenadas da caixa delimitadora são traduzidas para representar locais do objeto após as informações de orientação nos metadados Exif serem usadas para corrigir a orientação da imagem. As imagens em formato .png não contêm metadados do Exif.

O Amazon Rekognition não executa correção de imagem para imagens no formato.png e imagens.jpeg sem informações de orientação nos metadados Exif da imagem. As coordenadas da caixa delimitadora não são traduzidas e representam os locais do objeto antes que a imagem seja girada.

Type: String

Valores válidos: ROTATE_0 | ROTATE_90 | ROTATE_180 | ROTATE_270

TargetImageOrientationCorrection

O valor deTargetImageOrientationCorrectioné sempre nulo.

Se a imagem de entrada estiver no formato.jpeg, ela poderá conter metadados em formato Exif. O Amazon Rekognition usa essas informações de orientação para executar a correção de imagem. As coordenadas da caixa delimitadora são traduzidas para representar locais do objeto após as informações de orientação nos metadados Exif serem usadas para corrigir a orientação da imagem. As imagens em formato .png não contêm metadados do Exif.

O Amazon Rekognition não executa correção de imagem para imagens no formato.png e imagens.jpeg sem informações de orientação nos metadados Exif da imagem. As coordenadas da caixa delimitadora não são traduzidas e representam os locais do objeto antes que a imagem seja girada.

Type: String

Valores válidos: ROTATE_0 | ROTATE_90 | ROTATE_180 | ROTATE_270

UnmatchedFaces

Uma matriz de faces na imagem de destino que não correspondia à face da imagem de origem.

Type: Matriz deComparedFaceobjetos

Errors

AccessDeniedException

Você não está autorizado a executar a ação.

Código de status HTTP: 400

ImageTooLargeException

O tamanho da imagem de entrada excede o limite permitido. Se você estiver ligandoDetectProtectiveEquipment, O tamanho ou a resolução da imagem excede o limite permitido. Para obter mais informações, consulte Diretrizes e cotas no Amazon Rekognition.

Código de status HTTP: 400

InternalServerError

O Amazon Rekognition teve um problema de serviço. Tente fazer a chamada novamente.

Código de status HTTP: 500

InvalidImageFormatException

O formato da imagem fornecida não é compatível.

Código de status HTTP: 400

InvalidParameterException

Um parâmetro de entrada violou uma restrição. Valide seu parâmetro antes de chamar a operação de API novamente.

Código de status HTTP: 400

InvalidS3ObjectException

O Amazon Rekognition não pode acessar o objeto do S3 especificado na solicitação.

Código de status HTTP: 400

ProvisionedThroughputExceededException

O número de solicitações excedeu o limite da taxa de transferência. Se precisar aumentar esse limite, entre em contato com o Amazon Rekognition.

Código de status HTTP: 400

ThrottlingException

O Amazon Rekognition está temporariamente indisponível para processar a solicitação. Tente fazer a chamada novamente.

Código de status HTTP: 500

Consulte também

Para obter mais informações sobre como usar essa API em um dos AWS SDKs específicos de linguagem, consulte o seguinte: