Aufrufen der Erkennungs-API

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 wird alle Gesichtserkennungsfunktionen außer Betrieb nehmen, 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. Bestandskunden haben bis 30. Juni 2023 Zeit, die Nutzung dieser Funktionen zu beenden, bevor sie eingestellt werden. Weitere Informationen zu dieser Entscheidung finden Sie hier.

In diesem Leitfaden wird gezeigt, wie mithilfe der Gesichtserkennungs-API aus einem bestimmten Bild Attribute wie Alter, Emotionen oder Kopfhaltung extrahiert werden können. Sie erfahren, welche verschiedenen Möglichkeiten Sie für die Konfiguration dieser API entsprechend Ihren Anforderungen haben.

Die Codeausschnitte in diesem Leitfaden wurden in C# unter Verwendung der Clientbibliothek für die Gesichtserkennung von Azure Cognitive Services 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

Um Gesichter zu suchen und ihre Positionen auf einem Bild abzurufen, rufen Sie die Methoden DetectWithUrlAsync oder DetectWithStreamAsync auf. DetectWithUrlAsync akzeptiert eine URL-Zeichenfolge als Eingabe, und DetectWithStreamAsync akzeptiert den unformatierten Bytestream eines Bilds als Eingabe.

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

Sie können die zurückgegebenen DetectedFace-Objekte nach den Rechtecken abfragen, mit denen die Pixelkoordinaten des jeweiligen Gesichts angegeben werden. Wenn Sie 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;
}

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 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 DetectionModel.Detection01 und den Parameter returnFaceLandmarks auf true fest.

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

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 DetectionModel.Detection01 und den Parameter returnFaceAttributes auf eine Liste von FaceAttributeType Enum-Werten fest.

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

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

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 headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    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.