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

Внимание

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

Внимание

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

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

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

Настройка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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