Teilen über

Aufrufen der Erkennungs-API

  • Artikel

Achtung

Der Zugriff auf den Gesichtserkennungsdienst ist auf der Grundlage von Berechtigungs- und Nutzungskriterien begrenzt, um unsere Prinzipien für verantwortungsvolle KI zu unterstützen. Der Gesichtserkennungsdienst ist nur für von Microsoft verwaltete Kunden und Partner verfügbar. Verwenden Sie das Aufnahmeformular für die Gesichtserkennung, um sich für den Zugriff zu bewerben. Weitere Informationen finden Sie auf der Seite Eingeschränkter Zugriff auf die Gesichtserkennung.

Achtung

Microsoft hat alle Gesichtserkennungsfunktionen zurückgezogen, mit denen sich emotionale Zustände und Identitätsattribute ableiten lassen, die bei missbräuchlicher Nutzung zu einer Stereotypisierung oder Diskriminierung von Personen oder zu einer unlauteren Verweigerung von Dienstleistungen führen können. Dazu gehören Funktionen, die Emotionen, Geschlecht, Alter, Lächeln, Gesichtsbehaarung, Haare und Make-up voraussagen können. Weitere Informationen zu dieser Entscheidung finden Sie hier.

In dieser Führungslinie wird veranschaulicht, wie Sie die Gesichtserkennungs-API verwenden, um Attribute aus einem bestimmten Bild zu extrahieren. Sie erfahren, welche verschiedenen Möglichkeiten Sie für die Konfiguration dieser API entsprechend Ihren Anforderungen haben.

Die Codeschnipsel in diesem Leitfaden wurden in C# mithilfe der Clientbibliothek der Azure KI-Gesichtserkennung geschrieben. Die gleiche Funktionalität ist auch über die REST-API verfügbar.

Einrichten

Für diesen Leitfaden wird vorausgesetzt, dass Sie bereits ein FaceClient-Objekt namens faceClient mit einem Schlüssel und einer Endpunkt-URL für die Gesichtserkennung erstellt haben. Anweisungen zum Einrichten dieses Feature finden Sie in den folgenden Schnellstarts.

Übermitteln von Daten an den Dienst

Rufen Sie die DetectAsync-Methode auf, um Gesichter zu finden und ihre Positionen in einem Bild abzurufen. Sie verwendet entweder eine URL-Zeichenfolge oder die unformatierte Bildbinärdatei als Eingabe.

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

Der Dienst gibt ein FaceDetectionResult-Objekt zurück, das Sie nach verschiedenen Arten von Informationen abfragen können, wie unten angegeben.

Weitere Informationen dazu, wie Sie die Position und die Dimensionen des Gesichts analysieren, finden Sie unter FaceRectangle. Normalerweise enthält dieses Rechteck Augen, Augenbrauen, Nase und Mund. Die Oberseite des Kopfs, die Ohren und das Kinn sind meist nicht enthalten. Um das Gesichtsrechteck zum Ausschneiden eines vollständigen Kopfs oder zum Produzieren eines Porträts in der Halbtotale zu verwenden, sollten Sie das Rechteck in alle Richtungen erweitern.

Festlegen, wie die Daten verarbeitet werden sollen

Das Hauptaugenmerk dieses Leitfadens liegt auf dem Detect-Aufruf, z. B. welche Argumente Sie übergeben und was Sie mit den zurückgegebenen Daten tun können. Wir empfehlen Ihnen, nur die Features abzufragen, die Sie benötigen. Jeder weitere Vorgang nimmt mehr Zeit in Anspruch.

Abrufen der Gesichts-ID

Wenn Sie den Parameter returnFaceId auf true (nur genehmigte Kunden) festlegen, können Sie die eindeutige ID für jedes Gesicht abrufen, die Sie in späteren Gesichtserkennungsaufgaben verwenden können.

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

Der optionale Parameter faceIdTimeToLive gibt an, wie lange (in Sekunden) die Gesichts-ID auf dem Server gespeichert werden soll. Nach Ablauf dieser Zeit wird die Gesichts-ID entfernt. Der Standardwert beträgt 86400 Sekunden (24 Stunden).

Abrufen von Gesichtsmerkmalpunkten

Gesichtsmerkmale bestehen aus mehreren einfach zu findenden Punkten im Gesicht. Beispiele hierfür sind die Pupillen oder die Nasenspitze. Um Daten zu Gesichtsmerkmalen abzurufen, legen Sie den Parameter detectionModel auf FaceDetectionModel.Detection03 und den Parameter returnFaceLandmarks auf true fest.

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

Abrufen von Gesichtsattributen

Zusätzlich zu Gesichtsrahmen und Gesichtsmerkmalpunkten kann die Gesichtserkennungs-API mehrere konzeptuelle Gesichtsattribute analysieren. Eine vollständige Liste finden Sie im Abschnitt Attribute, in dem die Konzepte beschrieben sind.

Um Gesichtsattribute zu analysieren, legen Sie den Parameter detectionModel auf FaceDetectionModel.Detection03 und den Parameter returnFaceAttributes auf eine Liste von FaceAttributeType Enum-Werten fest.

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;

Abrufen von Ergebnissen aus dem Dienst

Ergebnisse zu Gesichtsmerkmalen

Der folgende Code zeigt, wie Sie die Position von Nase und Pupillen abrufen können:

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;

Sie können die Punktdaten für Gesichtsmerkmale auch verwenden, um die Ausrichtung eines Gesichts exakt zu bestimmen. Beispielsweise können Sie die Ausrichtung des Gesichts als Vektor vom Mittelpunkt des Munds zum Mittelpunkt der Augen definieren. Dieser Vektor wird mit dem folgenden Code berechnet:

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

Wenn Ihnen die Ausrichtung des Gesichts bekannt ist, können Sie den rechteckigen Gesichtsrahmen drehen, um ihn noch besser am Gesicht auszurichten. Zum Ausschneiden von Gesichtern aus einem Bild können Sie Bilder programmgesteuert drehen, damit Gesichter immer senkrecht dargestellt werden.

Ergebnisse von Gesichtsattributen

Der folgende Code zeigt, wie Sie die Gesichtsattributdaten abrufen können, die Sie im ursprünglichen Aufruf angefordert haben.

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

Weitere Informationen zu den einzelnen Attributen finden Sie im Leitfaden Face detection and attributes (Gesichtserkennung und -attribute) zu den Konzepten.

Nächste Schritte

In diesem Leitfaden haben Sie erfahren, wie die verschiedenen Funktionen der Gesichtserkennung und -analyse verwendet werden. Als Nächstes integrieren Sie diese Features in eine App, um Gesichtserkennungsdaten von Benutzern hinzuzufügen.