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 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
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);
Der Dienst gibt ein DetectedFace-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 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.