Chamar a API de detecção

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

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

Instalação

Este guia pressupõe que você já construiu um objeto FaceClient, chamado faceClient, com uma chave de assinatura da 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 suas localizações em uma imagem, chame o método DetectWithUrlAsync ou DetectWithStreamAsync. DetectWithUrlAsync usa uma cadeia de caracteres de URL como entrada, e DetectWithStreamAsync usa o fluxo de byte bruto de uma imagem como entrada.

IList<DetectedFace> faces = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: true, detectionModel: DetectionModel.Detection03);

Você pode consultar os objetos DetectedFace retornados quanto às IDs exclusivas e um retângulo que fornece as coordenadas de pixel do rosto. Assim, você pode saber qual ID de rosto é mapeada para qual rosto na imagem original.

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

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.

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 DetectionModel.Detection01 e o parâmetro returnFaceLandmarks como true.

// Note DetectionModel.Detection02 cannot be used with returnFaceLandmarks.
IList<DetectedFace> faces2 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: true, returnFaceLandmarks: true, detectionModel: DetectionModel.Detection01);

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 DetectionModel.Detection01 e o parâmetro returnFaceAttributes como uma lista de valores de FaceAttributeType Enum.

var requiredFaceAttributes = new FaceAttributeType?[] {
    FaceAttributeType.Age,
    FaceAttributeType.Gender,
    FaceAttributeType.Smile,
    FaceAttributeType.FacialHair,
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.Emotion
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: true, returnFaceAttributes: requiredFaceAttributes, detectionModel: DetectionModel.Detection01);

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(
        (upperLipBottom.X + underLipTop.X) / 2,
        (upperLipBottom.Y + underLipTop.Y) / 2);

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

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

    Vector faceDirection = new Vector(
        centerOfTwoEyes.X - centerOfMouth.X,
        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 age = attributes.Age;
    var gender = attributes.Gender;
    var smile = attributes.Smile;
    var facialHair = attributes.FacialHair;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var emotion = attributes.Emotion;
}

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.