通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

调用检测 API

  • 项目

注意

为了支持我们负责任的 AI 原则，基于资格和使用标准对人脸服务访问进行限制。 人脸服务仅适用于 Microsoft 托管客户和合作伙伴。 使用人脸识别引入表单来申请访问。 有关详细信息，请参阅人脸受限访问页面。

注意

Microsoft 已停用或限制面部识别功能，这些功能可用于尝试推断情感状态和标识属性，如果滥用，可能会使人们遭受刻板印象、歧视或受到不公平的拒绝服务攻击。 已停用的功能包括情感和性别识别。 受限的功能包括年龄、微笑、面部毛发、头发和化妆识别。 如果在某个负责任用例中，使用任何受限功能对你有益，请向 Azure 人脸 API 部门发送电子邮件。 在此处阅读有关此决定的更多信息。

本指南演示如何使用人脸检测 API 从给定图像中提取属性。 你将了解配置此 API 的行为以满足你的需求的不同方法。

本指南中的代码片段是使用 Azure AI 人脸客户端库以 C# 编写的。 同样的功能通过 REST API 提供。

设置

本指南假设你已使用人脸密钥和终结点 URL 构造了名为 faceClient 的 FaceClient 对象。 有关如何设置此功能的说明，请按照其中一个快速入门操作。

提交服务数据

若要查找人脸并获取其在图像中的位置，请调用 DetectAsync。 它采用 URL 字符串或原始图像二进制文件作为输入。

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

该服务将返回 FaceDetectionResult 对象，该对象可用于查询下面指定的不同类型的信息。

有关如何分析人脸位置和维度的信息，请参阅 FaceRectangle。 通常情况下，此矩形包含眼睛、眉毛、鼻子和嘴巴， 不一定包括头顶、耳朵和下巴。 若要使用人脸矩形来裁剪整个头部或获取中景肖像，应朝每个方向拉伸矩形。

确定如何处理数据

本指南重点介绍有关检测调用的具体信息，例如，可以传递哪些参数，以及可对返回的数据执行哪些操作。 建议仅查询所需功能。 每个操作需要更多时间才能完成。

获取人脸 ID

如果你将 returnFaceId 参数设置为 true（仅限已批准的客户），则你可以获取每张人脸的唯一 ID，你可以在稍后的人脸识别任务中使用该 ID。

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

可选的 faceIdTimeToLive 参数指定人脸 ID 在服务器上应存储的时长（以秒为单位）。 此时间到期后，将删除人脸 ID。 默认值为 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;
}

若要详细了解每个属性，请参阅人脸检测和属性概念指南。

后续步骤

本指南介绍了如何使用人脸检测和分析的各项功能。 接下来，将这些功能集成到应用中，以添加用户的人脸数据。