Compartilhar via

Chamar a API de Detecção

  • Artigo

Cuidado

O acesso ao serviço de Detecção Facial é limitado com base em critérios de qualificação e uso para dar suporte aos nossos princípios de IA responsável. O serviço de Detecção Facial só está disponível para clientes e parceiros gerenciados da Microsoft. Use o Formulário de admissão de reconhecimento facial para solicitar acesso. Para obter mais informações, consulte a página Acesso limitado facial.

Cuidado

A Microsoft desativou ou limitou as funcionalidades de reconhecimento do rosto que podem ser usadas para tentar inferir estados emocionais e atributos de identidade que, se mal utilizados, podem submeter as pessoas a estereótipos, discriminação ou recusa injusta de serviços. As funcionalidades desativadas são detecção de emoções e gênero. As funcionalidades limitadas são idade, sorriso, pelos faciais, cabelo e maquiagem. Envie um email para API de Detecção Facial do Azure se você tiver um caso de uso responsável que se beneficiaria do uso de qualquer uma das funcionalidades limitadas. Leia mais sobre essa decisão aqui.

Este guia demonstra como usar a API de detecção facial para extrair atributos de uma determinada imagem. Você aprenderá as diversas maneiras de configurar o comportamento dessa API para atender às suas necessidades.

Os códigos dos snippets deste guia foram escritos em C# com a biblioteca de clientes da Detecção Facial da IA do Azure. O mesmo recurso está disponível por meio da API REST.

Instalação

Este guia considera que você já tenha construído um objeto FaceClient chamado faceClient, usando uma chave de Detecção Facial e uma URL de ponto de extremidade. Para obter instruções sobre como configurar esse recurso, siga um dos guias de início rápido.

Enviar dados ao serviço

Para encontrar rostos e obter seus locais em uma imagem, chame o DetectAsync. Ele usa uma cadeia de caracteres de URL ou o binário de imagem bruta como entrada.

var response = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false);
IReadOnlyList<FaceDetectionResult> faces = response.Value;

O serviço retorna um objeto FaceDetectionResult, que você pode consultar para diferentes tipos de informações, especificado abaixo.

Para obter informações sobre como analisar a localização e as dimensões do rosto, confira FaceRectangle. Normalmente, esse retângulo contém os olhos, as sobrancelhas, o nariz e a boca. A parte superior da cabeça, os ouvidos e o queixo não estão necessariamente incluídos. Para usar o retângulo de rosto para recortar totalmente uma cabeça ou obter um retrato de média distância, expanda o retângulo em todas as direções.

Determinar como processar os dados

Este guia concentra-se nas especificidades da chamada da Detecção, como os argumentos que você pode passar e o que pode fazer com os dados retornados. Recomendamos que você consulte apenas os recursos necessários. Cada operação demora mais para ser concluída.

A ID da face

Caso você defina o parâmetro returnFaceId como true (somente clientes aprovados), poderá obter a ID exclusiva de cada rosto, que pode ser usada nas tarefas de reconhecimento facial posteriores.

foreach (var face in faces)
{
    string id = face.FaceId.ToString();
    FaceRectangle rect = face.FaceRectangle;
}

O parâmetro faceIdTimeToLive opcional especifica quanto tempo (em segundos) a ID da face deve ser armazenada no servidor. Depois que esse tempo expirar, a ID da face será removida. O valor padrão é 86400 (24 horas).

Obter pontos de referência facial

Os pontos de referência faciais são um conjunto de pontos fáceis de encontrar em um rosto, como as pupilas ou a ponta do nariz. Para obter dados de referência do rosto, defina o parâmetro detectionModel como FaceDetectionModel.Detection03 e o parâmetro returnFaceLandmarks como true.

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
var response2 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceLandmarks: true);
IReadOnlyList<FaceDetectionResult> faces2 = response2.Value;

Obter atributos faciais

Além dos retângulos e pontos de referência faciais, a API de Detecção Facial pode analisar vários atributos conceituais de um rosto. Para obter uma lista completa, confira a seção conceitual de Atributos de rosto.

Para analisar os atributos de rosto, defina o parâmetro detectionModel como FaceDetectionModel.Detection03 e o parâmetro returnFaceAttributes como uma lista de valores de FaceAttributeType Enum.

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.Detection03.Blur,
    FaceAttributeType.Detection03.HeadPose,
    FaceAttributeType.Detection03.Mask,
    FaceAttributeType.Recognition04.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var response3 = await faceClient.DetectAsync(new Uri(imageUrl), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes);
IReadOnlyList<FaceDetectionResult> faces3 = response3.Value;

Obter resultados do serviço

Resultados da referência do rosto

O seguinte código demonstra como você pode recuperar as localizações do nariz e das pupilas:

foreach (var face in faces2)
{
    var landmarks = face.FaceLandmarks;

    double noseX = landmarks.NoseTip.X;
    double noseY = landmarks.NoseTip.Y;

    double leftPupilX = landmarks.PupilLeft.X;
    double leftPupilY = landmarks.PupilLeft.Y;

    double rightPupilX = landmarks.PupilRight.X;
    double rightPupilY = landmarks.PupilRight.Y;

Você também pode usar dados de referência do rosto para calcular precisamente a direção do rosto. Por exemplo, você pode definir a rotação do rosto como um vetor partindo do centro da boca para o centro dos olhos. O seguinte código calcula esse vetor:

    var upperLipBottom = landmarks.UpperLipBottom;
    var underLipTop = landmarks.UnderLipTop;

    var centerOfMouth = new Point(
        (int)((upperLipBottom.X + underLipTop.X) / 2),
        (int)((upperLipBottom.Y + underLipTop.Y) / 2));

    var eyeLeftInner = landmarks.EyeLeftInner;
    var eyeRightInner = landmarks.EyeRightInner;

    var centerOfTwoEyes = new Point(
        (int)((eyeLeftInner.X + eyeRightInner.X) / 2),
        (int)((eyeLeftInner.Y + eyeRightInner.Y) / 2));

    var faceDirectionVectorX = centerOfTwoEyes.X - centerOfMouth.X;
    var faceDirectionVectorY = centerOfTwoEyes.Y - centerOfMouth.Y;
}

Quando você sabe a direção do rosto, pode girar o quadro de rosto retangular para alinhá-lo mais adequadamente. Para recortar rostos em uma imagem, você pode girar a imagem de maneira programática para que os rostos sempre apareçam na vertical.

Resultados de atributo do rosto

O código a seguir mostra como você pode recuperar os dados de atributo de rosto solicitados na chamada original.

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var blur = attributes.Blur;
    var headPose = attributes.HeadPose;
    var mask = attributes.Mask;
    var qualityForRecognition = attributes.QualityForRecognition;
}

Para saber mais sobre cada um dos atributos, confira o guia conceitual de Detecção e atributos de rosto.

Próximas etapas

Neste guia, você aprendeu a usar as várias funcionalidades da detecção e análise facial. Em seguida, integre esses recursos em um aplicativo para adicionar dados do rosto de usuários.