Llamada a la API de detección

En esta guía se muestra cómo usar la API de detección de caras para extraer de una imagen determinada atributos como la edad, la emoción o la posición de la cabeza. Conocerá las distintas maneras de configurar el comportamiento de esta API para satisfacer sus necesidades.

Los fragmentos de código de esta guía están escritos en C# con la biblioteca cliente Face de Azure Cognitive Services. La misma funcionalidad está disponible mediante la API REST.

Configurar

En esta guía se da por supuesto que ya ha construido un objeto FaceClient llamado faceClient, con una clave de suscripción y una dirección URL de punto de conexión de Face. Para obtener instrucciones sobre cómo configurar esta característica, siga uno de los inicios rápidos.

Envío de datos al servicio

Para encontrar caras y obtener su ubicación en una imagen, llame a los métodos DetectWithUrlAsync o DetectWithStreamAsync. DetectWithUrlAsync toma una cadena de dirección URL como entrada, mientras que DetectWithStreamAsync toma la secuencia de bytes sin formato de una imagen.

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

Puede consultar los objetos DetectedFace devueltos para obtener sus identificadores únicos y un rectángulo que proporciona las coordenadas en píxeles de la cara. De este modo, puede saber qué Id. se asigna a cada cara de la imagen original.

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

Para obtener información sobre cómo analizar la ubicación y las dimensiones de la cara, consulte FaceRectangle. Normalmente, este rectángulo contiene los ojos, las cejas, la nariz y la boca. La parte superior de la cabeza, las orejas y la barbilla no están incluidas necesariamente. Para usar el rectángulo facial con el fin de recortar una cabeza completa u obtener un retrato intermedio, expanda el rectángulo en cada dirección.

Determinación de cómo procesar los datos

Esta guía se centra en los detalles de la llamada de detección, como los argumentos que se pueden pasar y lo que puede hacer con los datos devueltos. Se recomienda consultar solo las características que necesita. Cada operación tarda más tiempo en completarse.

Obtención de los puntos de referencia faciales

Los puntos de referencia faciales son un conjunto de puntos fáciles de encontrar en una cara como, por ejemplo, las pupilas o la punta de la nariz. Para obtener datos de los puntos de referencia faciales, establezca el parámetro detectionModel en DetectionModel.Detection01 y el parámetro returnFaceLandmarks en 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);

Obtención de los atributos de la cara

Además de los rectángulos y los puntos de referencia faciales, la API de detección de caras puede analizar varios atributos conceptuales de una cara. Para obtener una lista completa, consulte la sección conceptual Atributos de una cara.

Para analizar los atributos de una cara, establezca el parámetro detectionModel en DetectionModel.Detection01 y el parámetro returnFaceAttributes en una lista de valores 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);

Obtención de resultados a partir del servicio

Resultados de los puntos de referencia faciales

El código siguiente muestra cómo podría recuperar las ubicaciones de la nariz y las 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;

También puede usar los datos de los puntos de referencia faciales para calcular con precisión la dirección de la cara. Por ejemplo, se puede definir la rotación de la cara como un vector desde el centro de la boca hasta el centro de los ojos. El código siguiente calcula este vector:

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

Cuando conoce la dirección de la cara, puede girar el marco rectangular de la cara para alinearlo más correctamente. Para recortar caras de una imagen, puede girar mediante programación la imagen para que siempre aparezcan en vertical.

Resultados del atributo face

En el siguiente código se muestra cómo recuperar los datos del atributo face que solicitó en la llamada 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 más información acerca de cada uno de los atributos, consulte la guía conceptual Detección de caras y atributos.

Pasos siguientes

En esta guía ha obtenido información sobre cómo utilizar las diversas funcionalidades de la detección y el análisis de caras. A continuación, integre estas características en una aplicación para agregar datos faciales de los usuarios.