De Detect-API aanroepen

  • Artikel

Let op

Toegang tot face-services is beperkt op basis van geschiktheids- en gebruikscriteria om onze verantwoorde AI-principes te ondersteunen. Face-service is alleen beschikbaar voor door Microsoft beheerde klanten en partners. Gebruik het intakeformulier voor gezichtsherkenning om toegang aan te vragen. Zie de pagina beperkte toegang van Face voor meer informatie.

Let op

Microsoft heeft mogelijkheden voor gezichtsherkenning buiten gebruik gesteld die kunnen worden gebruikt om emotionele toestanden en identiteitskenmerken af te stellen die, indien misbruikt, personen kunnen onderwerpen aan stereotypische, discriminatie of oneerlijke ontkenning van services. Deze omvatten mogelijkheden die emotie, geslacht, leeftijd, glimlach, gezichtshaar, haar en make-up voorspellen. Lees hier meer over deze beslissing.

In deze handleiding wordt gedemonstreerd hoe u de API voor gezichtsdetectie gebruikt om kenmerken uit een bepaalde afbeelding te extraheren. U leert de verschillende manieren om het gedrag van deze API te configureren om aan uw behoeften te voldoen.

De codefragmenten in deze handleiding zijn geschreven in C# met behulp van de Azure AI Face-clientbibliotheek. Dezelfde functionaliteit is beschikbaar via de REST API.

Instellingen

In deze handleiding wordt ervan uitgegaan dat u al een FaceClient-object met de naam faceClienthebt gemaakt met behulp van een Face-sleutel en eindpunt-URL. Volg een van de quickstarts voor instructies over het instellen van deze functie.

Gegevens verzenden naar de service

Als u gezichten wilt zoeken en hun locaties in een afbeelding wilt ophalen, roept u de methode DetectWithUrlAsync of DetectWithStreamAsync aan. DetectWithUrlAsync neemt een URL-tekenreeks als invoer en DetectWithStreamAsync neemt de onbewerkte bytestroom van een afbeelding als invoer.

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

De service retourneert een DetectedFace-object , dat u kunt opvragen voor verschillende soorten informatie, die hieronder is opgegeven.

Zie FaceRectangle voor informatie over het parseren van de locatie en afmetingen van het gezicht. Meestal bevat deze rechthoek de ogen, wenkbrauwen, neus en mond. De bovenkant van het hoofd, de oren en de kin zijn niet noodzakelijkerwijs inbegrepen. Als u de rechthoek met het gezicht wilt gebruiken om een volledig hoofd bij te snijden of een middenschotportret te krijgen, moet u de rechthoek in elke richting uitvouwen.

Bepalen hoe de gegevens moeten worden verwerkt

Deze handleiding richt zich op de specifieke kenmerken van de aanroep Detecteren, zoals welke argumenten u kunt doorgeven en wat u kunt doen met de geretourneerde gegevens. U wordt aangeraden alleen query's uit te voeren op de functies die u nodig hebt. Het duurt langer om elke bewerking te voltooien.

Gezichts-id ophalen

Als u de parameter returnFaceId instelt op true (alleen goedgekeurde klanten), kunt u de unieke id voor elk gezicht ophalen, die u in latere gezichtsherkenningstaken kunt gebruiken.

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

De optionele faceIdTimeToLive-parameter geeft aan hoe lang (in seconden) de face-id moet worden opgeslagen op de server. Nadat deze tijd is verlopen, wordt de face-id verwijderd. De standaardwaarde is 86400 (24 uur).

Gezichtsoriëntatiepunten ophalen

Gezichtsoriëntatiepunten zijn een set gemakkelijk te vinden punten op een gezicht, zoals de pupillen of de punt van de neus. Als u gezichtsoriëntatiepunten wilt ophalen, stelt u de parameter detectionModel in op en de parameter returnFaceLandmarks op trueDetectionModel.Detection01 .

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

Gezichtskenmerken ophalen

Naast gezichtsrechthoeken en oriëntatiepunten kan de API voor gezichtsdetectie verschillende conceptuele kenmerken van een gezicht analyseren. Zie de conceptuele sectie gezichtskenmerken voor een volledige lijst.

Als u gezichtskenmerken wilt analyseren, stelt u de parameter detectionModel in op en de parameter returnFaceAttributes op een lijst met FaceAttributeType Enum-waardenDetectionModel.Detection01.

var requiredFaceAttributes = new FaceAttributeType[] {
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: false, returnFaceAttributes: requiredFaceAttributes, detectionModel: DetectionModel.Detection01, recognitionModel: RecognitionModel.Recognition04);

Resultaten ophalen van de service

Resultaten van gezichtsoriëntatiepunten

De volgende code laat zien hoe u de locaties van de neus en pupillen kunt ophalen:

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;

U kunt ook gezichtsoriëntatiepunten gebruiken om de richting van het gezicht nauwkeurig te berekenen. U kunt bijvoorbeeld de draaiing van het gezicht definiëren als een vector van het midden van de mond naar het midden van de ogen. Met de volgende code wordt deze vector berekend:

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

Wanneer u de richting van het gezicht kent, kunt u het rechthoekige gezichtsframe draaien om het beter uit te lijnen. Als u gezichten in een afbeelding wilt bijsnijden, kunt u de afbeelding programmatisch draaien, zodat de gezichten altijd rechtop worden weergegeven.

Resultaten van gezichtskenmerk

De volgende code laat zien hoe u de gegevens van het gezichtskenmerk kunt ophalen die u in de oorspronkelijke aanroep hebt aangevraagd.

foreach (var face in faces3)
{
    var attributes = face.FaceAttributes;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var qualityForRecognition = attributes.QualityForRecognition;
}

Zie de conceptuele handleiding gezichtsdetectie en - kenmerken voor meer informatie over elk van de kenmerken.

Volgende stappen

In deze handleiding hebt u geleerd hoe u de verschillende functies van gezichtsdetectie en -analyse kunt gebruiken. Integreer vervolgens deze functies in een app om gezichtsgegevens van gebruikers toe te voegen.