Wywoływanie interfejsu API wykrywania

  • Artykuł

Uwaga

Dostęp do usługi rozpoznawania twarzy jest ograniczony na podstawie kryteriów kwalifikowalności i użycia w celu obsługi naszych zasad odpowiedzialnej sztucznej inteligencji. Usługa rozpoznawania twarzy jest dostępna tylko dla klientów i partnerów zarządzanych przez firmę Microsoft. Użyj formularza do wprowadzania rozpoznawania twarzy, aby ubiegać się o dostęp. Aby uzyskać więcej informacji, zobacz stronę Dostęp ograniczony do twarzy.

Uwaga

Firma Microsoft wycofała możliwości rozpoznawania twarzy, które mogą służyć do wnioskowania stanów emocjonalnych i atrybutów tożsamości, które, w przypadku nieprawidłowego użycia, mogą podlegać stereotypom, dyskryminacji lub niesprawiedliwej odmowy usług. Obejmują one możliwości, które przewidują emocje, płeć, wiek, uśmiech, zarost, włosy i makijaż. Przeczytaj więcej na temat tej decyzji tutaj.

W tym przewodniku pokazano, jak używać interfejsu API wykrywania twarzy do wyodrębniania atrybutów z danego obrazu. Poznasz różne sposoby konfigurowania zachowania tego interfejsu API w celu spełnienia Twoich potrzeb.

Fragmenty kodu w tym przewodniku są napisane w języku C# przy użyciu biblioteki klienta rozpoznawania twarzy usługi Azure AI. Ta sama funkcja jest dostępna za pośrednictwem interfejsu API REST.

Konfiguracja

W tym przewodniku założono, że utworzono już obiekt FaceClient o nazwie faceClient, używając klucza rozpoznawania twarzy i adresu URL punktu końcowego. Aby uzyskać instrukcje dotyczące konfigurowania tej funkcji, postępuj zgodnie z jednym z przewodników Szybki start.

Przesyłanie danych do usługi

Aby znaleźć twarze i uzyskać ich lokalizacje na obrazie, wywołaj metodę DetectWithUrlAsync lub DetectWithStreamAsync . DetectWithUrlAsync przyjmuje ciąg adresu URL jako dane wejściowe, a funkcja DetectWithStreamAsync pobiera nieprzetworzone strumienie bajtów obrazu jako dane wejściowe.

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

Usługa zwraca obiekt DetectedFace , który można wykonywać zapytania dotyczące różnych rodzajów informacji określonych poniżej.

Aby uzyskać informacje na temat analizowania lokalizacji i wymiarów twarzy, zobacz FaceRectangle. Zwykle ten prostokąt zawiera oczy, brwi, nos i usta. Górna część głowy, uszu i podbródka nie musi być dołączona. Aby użyć prostokąta twarzy, aby przycinać pełną głowę lub uzyskać portret w połowie strzału, należy rozwinąć prostokąt w każdym kierunku.

Określanie sposobu przetwarzania danych

Ten przewodnik koncentruje się na specyfikach wywołania Detect, takich jak argumenty, które można przekazać i co można zrobić z zwracanymi danymi. Zalecamy wykonywanie zapytań dotyczących tylko potrzebnych funkcji. Wykonanie każdej operacji zajmuje więcej czasu.

Uzyskiwanie identyfikatora twarzy

Jeśli ustawisz parametr returnFaceId na true (tylko zatwierdzonych klientów), możesz uzyskać unikatowy identyfikator dla każdej twarzy, której można użyć w kolejnych zadaniach rozpoznawania twarzy.

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

Opcjonalny parametr faceIdTimeToLive określa, jak długo (w sekundach) identyfikator twarzy powinien być przechowywany na serwerze. Po upływie tego czasu identyfikator twarzy zostanie usunięty. Wartość domyślna to 86400 (24 godziny).

Uzyskiwanie punktów orientacyjnych twarzy

Punkty orientacyjne twarzy to zestaw łatwych do znalezienia punktów na twarzy, takich jak źrenice lub wierzchołek nosa. Aby uzyskać dane punktów orientacyjnych twarzy, ustaw parametr detectionModel na DetectionModel.Detection01 i parametr returnFaceLandmarks na truewartość .

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

Pobieranie atrybutów twarzy

Oprócz prostokątów twarzy i punktów orientacyjnych interfejs API wykrywania twarzy może analizować kilka atrybutów koncepcyjnych twarzy. Aby uzyskać pełną listę, zobacz sekcję koncepcyjną Atrybuty twarzy.

Aby przeanalizować atrybuty twarzy, ustaw parametr detectionModel na DetectionModel.Detection01 i parametr returnFaceAttributes na listę wartości wyliczenia FaceAttributeType.

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

Pobieranie wyników z usługi

Wyniki punktów orientacyjnych twarzy

Poniższy kod pokazuje, jak można pobrać lokalizacje nosa i źrenice:

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;

Możesz również użyć danych charakterystycznych twarzy, aby dokładnie obliczyć kierunek twarzy. Można na przykład zdefiniować obrót twarzy jako wektor z środka ust do środka oczu. Poniższy kod oblicza ten wektor:

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

Gdy znasz kierunek twarzy, możesz obrócić prostokątną ramkę twarzy, aby wyrównać ją dokładniej. Aby przycinać twarze na obrazie, można programowo obracać obraz, aby twarze zawsze pojawiały się w pozycji pionowej.

Wyniki atrybutu twarzy

Poniższy kod pokazuje, jak można pobrać dane atrybutu twarzy żądane w oryginalnym wywołaniu.

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

Aby dowiedzieć się więcej na temat każdego z atrybutów, zobacz przewodnik koncepcyjny dotyczący wykrywania twarzy i atrybutów .

Następne kroki

W tym przewodniku przedstawiono sposób używania różnych funkcji wykrywania i analizy twarzy. Następnie zintegruj te funkcje z aplikacją, aby dodać dane twarzy od użytkowników.