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

IndexFaces

Detecta faces na imagem de entrada e adiciona-as à coleção especificada.

O Amazon Rekognition não salva as faces reais detectadas. Em vez disso, o algoritmo de detecção subjacente detecta primeiramente as faces na imagem de entrada. Para cada face, o algoritmo extrai traços faciais em um vetor de traços de traços e os armazena no banco de dados de back-end. O Amazon Rekognition usa vetores de recursos quando executa operações de correspondência facial e pesquisa usando oSearchFaceseSearchFacesByImageoperações.

Para obter mais informações, consulte Adicionar faces a uma coleção.

Para obter o número de faces em uma coleção, chameDescribeCollection.

Se você estiver usando a versão 1.0 do modelo de detecção facial,IndexFacesindexa as 15 maiores faces na imagem de entrada. As versões posteriores do modelo de detecção de faces indexam as 100 maiores faces na imagem de entrada.

Se você estiver usando a versão 4 ou posterior do modelo de rosto, as informações de orientação da imagem não serão retornadas naOrientationCorrectioncampo.

Para determinar qual versão do modelo você está usando, chameDescribeCollectione forneça o ID da coleção. Você também pode obter a versão do modelo a partir do valor deFaceModelVersionna resposta deIndexFaces

Para obter mais informações, consulte Versionamento de modelo.

Se você fornecer o opcionalExternalImageIdpara a imagem de entrada que você forneceu, o Amazon Rekognition associa esse ID a todas as faces detectadas. Quando você chama oListFacesoperação, a resposta retorna o ID externo. Você pode usar esse ID de imagem externo para criar um índice do lado do cliente para associar as faces a cada imagem. Você pode usar o índice para encontrar todas as faces em uma imagem.

É possível especificar o número máximo de faces a serem indexadas com aMaxFacesparâmetro de entrada. Isso é útil quando você deseja indexar as maiores faces em uma imagem e não deseja indexar as faces menores, como as pertencentes a pessoas em segundo plano.

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. Por padrão,IndexFacesescolhe a barra de qualidade usada para filtrar faces. Também é possível escolher explicitamente a barra de qualidade. Usar oQualityFilter, para definir a barra de qualidade especificandoLOW,MEDIUM, ouHIGH. Se você não quiser filtrar faces detectadas, especifiqueNONE.

nota

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

As informações sobre faces detectadas em uma imagem, mas não indexadas, são retornadas em uma matriz deUnindexedFaceobjetos,UnindexedFaces. Os rostos não são indexados por motivos como:

  • O número de faces detectadas excede o valor doMaxFacesParâmetro de solicitação.

  • 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.

Em resposta, oIndexFacesoperation retorna uma matriz de metadados para todas as faces detectadas,FaceRecords. Isso inclui:

  • A caixa delimitadora,BoundingBox, da face detectada.

  • Um valor de confiança,Confidence, o que indica a confiança da caixa delimitadora que contém uma face.

  • Um ID facial,FaceId, atribuído pelo serviço para cada face detectada e armazenada.

  • Um ID de imagem,ImageId, atribuído pelo serviço para a imagem de entrada.

Se você solicitar todos os atributos faciais (usando odetectionAttributesparâmetro), Amazon Rekognition retorna atributos faciais detalhados, como marcos faciais (por exemplo, localização do olho e boca) e outros atributos faciais. Se você fornecer a mesma imagem, especifique a mesma coleção e use a mesma ID externa naIndexFacesoperação, o Amazon Rekognition não salva metadados faciais duplicados.

A imagem de entrada é passada como bytes de imagem codificados em base64 ou como referência a uma imagem em um bucket do Amazon S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não haverá suporte para a passagem de bytes da imagem. A imagem deve ser formatada como um arquivo PNG ou JPEG.

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

Sintaxe da solicitação

{ "CollectionId": "string", "DetectionAttributes": [ "string" ], "ExternalImageId": "string", "Image": { "Bytes": blob, "S3Object": { "Bucket": "string", "Name": "string", "Version": "string" } }, "MaxFaces": number, "QualityFilter": "string" }

Parâmetros de solicitação

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

CollectionId

O ID de uma coleção existente à qual você deseja adicionar as faces detectadas nas imagens de entrada.

Type: String

Restrições de comprimento: Tamanho mínimo de 1. Tamanho máximo de 255.

Padrão: [a-zA-Z0-9_.\-]+

Obrigatório: Sim

DetectionAttributes

Uma matriz de atributos faciais que você deseja que retornem. Essa pode ser a lista padrão de atributos ou todos os atributos. Se você não especificar um valor paraAttributesou se você especificar["DEFAULT"], a API retorna o seguinte subconjunto de atributos faciais:BoundingBox,Confidence,Pose,Quality, eLandmarks. Se você fornecer["ALL"], todos os atributos faciais são retornados, mas a operação leva mais tempo para ser concluída.

Se você fornecer os dois,["ALL", "DEFAULT"], o serviço usa um operador AND lógico para determinar quais atributos retornar (neste caso, todos os atributos).

Type: Matriz de strings

Valores válidos: DEFAULT | ALL

Obrigatório: Não

ExternalImageId

O ID que você deseja atribuir a todas as faces detectadas na imagem.

Type: String

Restrições de comprimento: Tamanho mínimo de 1. Tamanho máximo de 255.

Padrão: [a-zA-Z0-9_.\-:]+

Obrigatório: Não

Image

A imagem de entrada como bytes codificados em base64 ou um objeto S3. Se você usar a AWS CLI para chamar as operações do Amazon Rekognition, não há suporte para passar 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 da imagem.

Tipo: objeto Image

Obrigatório: Sim

MaxFaces

O número máximo de faces a serem indexadas. O valor deMaxFacesDeve ser maior ou igual a 1.IndexFacesnão retorna mais de 100 faces detectadas em uma imagem, mesmo se você especificar um valor maior paraMaxFaces.

SeIndexFacesdetecta mais faces do que o valor deMaxFaces, os rostos com a menor qualidade são filtrados primeiro. Se ainda houver mais faces do que o valor deMaxFaces, as faces com as menores caixas delimitadoras são filtradas (até o número necessário para satisfazer o valor deMaxFaces). Informações sobre as faces não indexadas estão disponíveis noUnindexedFacesmatriz.

Os rostos que são retornados porIndexFacessão classificados pelo maior tamanho da caixa delimitadora de face para o menor tamanho, em ordem decrescente.

MaxFacespode ser usado com uma coleção associada a qualquer versão do modelo de face.

Type: Inteiro

Intervalo válido: Valor mínimo de 1.

Obrigatório: Não

QualityFilter

Um filtro que especifica uma barra de qualidade para quanta filtragem é feita para identificar rostos. As faces filtradas não são indexadas. Se você especificarAUTO, 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. O valor padrão é AUTO. A barra de qualidade é baseada em uma variedade de casos de uso comuns. As detecções de baixa qualidade podem ocorrer por vários motivos. 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.

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

Sintaxe da resposta

{ "FaceModelVersion": "string", "FaceRecords": [ { "Face": { "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "ExternalImageId": "string", "FaceId": "string", "ImageId": "string", "IndexFacesModelVersion": "string" }, "FaceDetail": { "AgeRange": { "High": number, "Low": number }, "Beard": { "Confidence": number, "Value": boolean }, "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "Emotions": [ { "Confidence": number, "Type": "string" } ], "Eyeglasses": { "Confidence": number, "Value": boolean }, "EyesOpen": { "Confidence": number, "Value": boolean }, "Gender": { "Confidence": number, "Value": "string" }, "Landmarks": [ { "Type": "string", "X": number, "Y": number } ], "MouthOpen": { "Confidence": number, "Value": boolean }, "Mustache": { "Confidence": number, "Value": boolean }, "Pose": { "Pitch": number, "Roll": number, "Yaw": number }, "Quality": { "Brightness": number, "Sharpness": number }, "Smile": { "Confidence": number, "Value": boolean }, "Sunglasses": { "Confidence": number, "Value": boolean } } } ], "OrientationCorrection": "string", "UnindexedFaces": [ { "FaceDetail": { "AgeRange": { "High": number, "Low": number }, "Beard": { "Confidence": number, "Value": boolean }, "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "Emotions": [ { "Confidence": number, "Type": "string" } ], "Eyeglasses": { "Confidence": number, "Value": boolean }, "EyesOpen": { "Confidence": number, "Value": boolean }, "Gender": { "Confidence": number, "Value": "string" }, "Landmarks": [ { "Type": "string", "X": number, "Y": number } ], "MouthOpen": { "Confidence": number, "Value": boolean }, "Mustache": { "Confidence": number, "Value": boolean }, "Pose": { "Pitch": number, "Roll": number, "Yaw": number }, "Quality": { "Brightness": number, "Sharpness": number }, "Smile": { "Confidence": number, "Value": boolean }, "Sunglasses": { "Confidence": number, "Value": boolean } }, "Reasons": [ "string" ] } ] }

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.

FaceModelVersion

O número da versão do modelo de detecção de faces associado à coleção de entrada (CollectionId).

Type: String

FaceRecords

Uma matriz de faces detectadas e adicionadas à coleção. Para obter mais informações, consulte Gerenciar faces em uma coleção.

Type: Matriz deFaceRecordobjetos

OrientationCorrection

Se sua coleção estiver associada a um modelo de detecção de rosto posterior à versão 3.0, o valor deOrientationCorrectioné sempre nulo e nenhuma informação de orientação é retornada.

Se sua coleção estiver associada a um modelo de detecção de rosto que seja a versão 3.0 ou anterior, o seguinte se aplica:

  • Se a imagem de entrada estiver no formato.jpeg, ela pode conter metadados do 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 depois que as informações de orientação nos metadados Exif são usadas para corrigir a orientação da imagem. As imagens em formato .png não contêm metadados do Exif. O valor deOrientationCorrectioné nulo.

  • Se a imagem não contiver informações de orientação em seus metadados Exif, o Amazon Rekognition retornará uma orientação estimada (ROTATE_0, ROTATE_90, ROTATE_180, ROTATE_270). O Amazon Rekognition não executa correção de imagem para imagens. As coordenadas da caixa delimitadora não são traduzidas e representam os locais do objeto antes que a imagem seja girada.

As informações da caixa delimitadora são retornadas noFaceRecordsmatriz. Você pode obter a versão do modelo de detecção de faces chamandoDescribeCollection.

Type: String

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

UnindexedFaces

Uma matriz de faces que foram detectadas na imagem, mas não foram indexadas. Eles não foram indexados porque o filtro de qualidade os identificou como de baixa qualidade, ou oMaxFaceso parâmetro de solicitação os filtrou. Para usar o filtro de qualidade, você especifica oQualityFilterParâmetro de solicitação.

Type: Matriz deUnindexedFaceobjetos

Erros

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 você quiser aumentar esse limite, entre em contato com o Amazon Rekognition.

Código de status HTTP: 400

ResourceNotFoundException

O recurso especificado na solicitação não pode ser encontrado.

Código de status HTTP: 400

ServiceQuotaExceededException

O tamanho do recurso excede o limite permitido. Para obter mais informações, consulte Diretrizes e cotas no 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: