検出 API を呼び出す

注意事項

Microsoft の責任ある AI の原則をサポートするために、Face サービスの利用は、適格性と使用基準に基づいて制限されています。 Face サービスは、Microsoft が管理する顧客とパートナーのみが利用できます。 顔認識受付フォームを使用して利用申請を行ってください。 詳細については、「Face の制限付きアクセス」ページを参照してください。

注意事項

Microsoft は、感情の状態や ID 属性の推測に使用できる顔認識機能を廃止または制限しています。この機能が誤って使用されると、人々が固定観念的な見方、差別、不当なサービス拒否にさらされる恐れがあります。 廃止された機能は、感情と性別です。 制限付き機能は、年齢、スマイル、顔ひげ、髪、メイクです。 制限付き機能のいずれかの使用によってメリットが得られる責任あるユースケースがある場合は、Azure Face API をメールで送信してください。 この決定について詳しくは、こちらをご覧ください。

このガイドでは、顔検出 API を使用して、特定の画像から属性を抽出する方法を示します。 この API の動作をニーズに合わせて構成するさまざまな方法を学習します。

このガイドのコード スニペットは Azure AI Face クライアント ライブラリを使用して C# で記述されています。 同じ機能を REST API でも使用できます。

セットアップ

このガイドでは、Face キーとエンドポイント 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」を参照してください。 通常、この四角形には、目、眉、鼻、口が含まれます。 頭の上部、耳、あごは必ずしも含まれません。 顔の四角形を使用して、頭部全体をトリミングしたり、上半身のポートレートを取得したりするには、四角形を各方向に拡張する必要があります。

データの処理方法を定義する

このガイドでは、Detect 呼び出しの仕様、たとえば、渡すことができる引数や返されたデータで実行できることを中心に説明を進めます。 必要な機能だけを照会することをお勧めします。 操作が増えると、完了までの時間が長くなります。

顔 ID を取得する

returnFaceId パラメーターを true (承認された顧客のみ) に設定すると、各顔の一意の ID を取得でき、後の顔認識タスクでそれを使用できます。

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

省略可能な faceIdTimeToLive パラメーターでは、顔 ID をサーバーに格納する時間 (秒単位) を指定します。 この時間を過ぎると、顔 ID が削除されます。 既定値は 86,400 (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;
}

各属性の詳細については、「Face detection and attributes (顔の検出と属性)」概念ガイドを参照してください。

次のステップ

このガイドでは、顔検出と分析のさまざまな機能を使用する方法について説明しました。 次に、これらの機能をアプリに統合して、ユーザーの顔データを追加します。

• チュートリアル: Face サービスにユーザーを追加する

関連記事

• リファレンス ドキュメント (REST)
• リファレンス ドキュメント (.NET SDK)