Appeler l’API de détection

Ce guide décrit comment utiliser l’API de détection des visages pour extraire des attributs d’une image donnée. Vous découvrirez les différentes façons de configurer le comportement de cette API pour répondre à vos besoins.

Les extraits de code de ce guide sont écrits en C# à l’aide de la bibliothèque de client Azure AI Visage. La même fonctionnalité est disponible via l’API REST.

Programme d’installation

Ce guide suppose que vous avez déjà construit un objet FaceClient, nommé faceClient, en utilisant une clé Visage et une URL de point de terminaison. Pour obtenir des instructions sur la configuration de cette fonctionnalité, suivez un des guides de démarrage rapide.

Envoyer des données au service

Pour rechercher des visages et obtenir leurs emplacements dans une image, appelez le DetectAsync. Il prend une chaîne d’URL ou le fichier binaire d’image brut comme entrée.

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

Le service retourne un objet FaceDetectionResult, que vous pouvez interroger pour différents types d’informations, spécifiés ci-dessous.

Pour plus d’informations sur la façon d’analyser l’emplacement et les dimensions du visage, consultez FaceRectangle. En règle générale, ce rectangle contient les yeux, les sourcils, le nez et la bouche. Le sommet du crâne, les oreilles et le menton ne sont pas nécessairement inclus. Pour utiliser le rectangle du visage pour rogner une tête complète ou obtenir un portrait en plan moyen, vous devez étendre le rectangle dans chaque direction.

Déterminer le mode de traitement des données

Ce guide se concentre sur les spécificités de l’appel de détection, telles que les arguments que vous pouvez transmettre et ce que vous pouvez faire avec les données retournées. Nous vous recommandons d’interroger uniquement les fonctionnalités dont vous avez besoin. Chaque opération prend plus de temps.

Obtenir l’ID du visage

Si vous définissez le paramètre returnFaceId sur true (clients approuvés uniquement), vous pouvez obtenir l’ID unique de chaque visage, que vous pouvez utiliser dans des tâches de reconnaissance faciale ultérieures.

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

Le paramètre facultatif faceIdTimeToLive spécifie la durée (en secondes) pendant laquelle l’ID du visage doit être stocké sur le serveur. Une fois ce délai expiré, l’ID du visage est supprimé. La valeur par défaut est 86400 (24 heures).

Obtenir les points de repère du visage

Les points de repère de visage sont un ensemble de points faciles à trouver sur un visage, tels que les pupilles ou la pointe du nez. Pour obtenir les données des points de repère de visage, définissez le paramètre detectionModel sur FaceDetectionModel.Detection03 et le paramètre returnFaceLandmarks sur 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;

Obtenir les attributs du visage

Outre les points de repère et les rectangles des visages, l’API de détection des visages peut analyser plusieurs attributs conceptuels d’un visage. Pour obtenir la liste complète, consultez la section conceptuelle Attributs du visage.

Pour analyser les attributs d’un visage, définissez le paramètre detectionModel sur FaceDetectionModel.Detection03 et le paramètre returnFaceAttributes sur une liste de valeurs enum FaceAttributeType.

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;

Obtenir les résultats du service

Résultats des points de repère de visage

Le code suivant montre comment récupérer les emplacements du nez et des pupilles :

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;

Vous pouvez également utiliser les données des points de repère de visage pour calculer avec précision l’orientation du visage. Par exemple, vous pouvez définir la rotation du visage en tant que vecteur allant du centre de la bouche jusqu’au centre des yeux. Le code suivant calcule ce vecteur :

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

Lorsque vous connaissez l’orientation du visage, vous pouvez faire pivoter le cadre rectangulaire du visage pour mieux l’aligner. Pour rogner les visages dans une image, vous pouvez faire pivoter l’image par programmation afin que les visages apparaissent toujours verticaux.

Résultats des attributs du visage

Le code suivant montre comment vous pouvez récupérer les données d’attributs du visage que vous avez demandées dans l’appel d’origine.

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

Pour en savoir plus sur les différents attributs, consultez le guide conceptuel Détection et attributs de visage.

Étapes suivantes

Dans ce guide, vous avez appris à utiliser les différentes fonctionnalités de la détection et de l’analyse des visages. Ensuite, intégrez ces fonctionnalités à une application pour ajouter les données de visage associées aux utilisateurs.

• Tutoriel : Ajouter des utilisateurs à un service Visage

Articles connexes

• Documentation de référence (REST)
• Documentation de référence (kit SDK .NET)