Вызов API распознавания

В этом руководстве показано, как использовать API обнаружения лиц для извлечения атрибутов из заданного изображения. Вы узнаете о различных способах настройки поведения этого API в соответствии с вашими потребностями.

Фрагменты кода в этом руководстве написаны на C# с помощью клиентской библиотеки Распознавания лиц Azure. Те же функции можно реализовать с помощью REST API.

Настройка

В этом руководстве предполагается, что вы уже создали объект FaceClient с именем faceClient, используя ключ лица и URL-адрес конечной точки. Инструкции по настройке этой функции приведены в одном из кратких руководств.

Отправка данных на устройство

Чтобы найти лица и получить их расположения в изображении, вызовите DetectAsync. Он принимает строку URL-адреса или двоичный двоичный файл необработанного изображения в качестве входных данных.

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

Служба возвращает объект FaceDetectionResult , который можно запрашивать для различных типов сведений, указанных ниже.

Сведения о том, как анализировать данные о расположении и размерах лица, см. в разделе FaceRectangle. Как правило, в этом прямоугольнике заключены глаза, брови, нос и рот. Верхняя часть головы, уши и подбородок не обязательно включаются в очерченную им область. Чтобы ограничить голову полностью или получить портрет среднего плана, можно раздвинуть этот прямоугольник в соответствующих направлениях.

Определение способа обработки данных

В этом разделе рассматриваются особенности вызова метода Detect, в том числе передаваемые аргументы и операции, которые можно выполнять с возвращаемыми данными. Рекомендуется запрашивать только необходимые функции. Для выполнения каждой операции требуется больше времени.

Получение идентификатора лица

Если задать параметр returnFaceId true (только утвержденным клиентам), вы можете получить уникальный идентификатор для каждого лица, который можно использовать в последующих задачах распознавания лиц.

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

Необязательный параметр faceIdTimeToLive указывает, сколько времени (в секундах) идентификатор лица должен храниться на сервере. После истечения срока действия идентификатор лица удаляется. Значение по умолчанию — 86400 (24 часа).

Получение ориентиров лица

Под ориентирами понимается ряд легко распознаваемых точек на лице, таких как зрачки или кончик носа. Чтобы получить данные ориентиров лица, установите для параметра detectionModel значение FaceDetectionModel.Detection03, а для параметра returnFaceLandmarks — значение true.

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

Получение атрибутов лиц

Помимо прямоугольников и ориентиров лица, API определения лиц может анализировать несколько концептуальных атрибутов лица. Полный их список см. в разделе Атрибуты лица концептуального руководства.

Чтобы анализировать атрибуты лиц, задайте для параметра detectionModel значение FaceDetectionModel.Detection03, а для параметра returnFaceAttributes — список значений FaceAttributeType Enum.

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;

Получение результатов из службы

Результаты ориентиров для лиц

В следующем коде показано, как можно получить сведения о расположении носа и зрачков:

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;

Данные ориентиров также можно использовать, чтобы точно определять, куда повернуто лицо. Например, можно определить угол поворота лица как вектор, направленный от центра рта к центру глаз. В следующем примере кода демонстрируется вычисление такого вектора:

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

Если известно направление лица, вы можете повернуть прямоугольную рамку для более точной ее подгонки. Для обрезки лиц на изображении можно программно повернуть изображение таким образом, чтобы они всегда располагались вертикально.

Результаты получения атрибутов лица

Следующий код показывает, как можно получить данные атрибутов лиц из исходного запроса.

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

Дополнительные сведения о каждом из этих атрибутов см. в концептуальном руководстве по определению лиц и их атрибутам.

Следующие шаги

Из этого руководства вы узнали, как использовать различные функции определения и анализа лиц. Далее вы можете интегрировать эти функции в приложение и добавить данные о лицах, полученные от пользователей.

• Руководство. Добавление пользователей в службу "Распознавание лиц"

Связанные статьи

• Справочная документация (REST)
• Справочная документация (.NET SDK)