検出 API を呼び出す

重要

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

重要

感情の状態やアイデンティティの属性の推測に使用できる顔認識機能は廃止されます。この機能は使い方を誤ると、ステレオタイプ化、差別、サービスの不当な拒否に人々をさらす可能性があります。 たとえば、感情、性別、年齢、笑顔、顔ひげ、髪、メイクを予測する機能が該当します。 これらの機能を既にご利用のお客様は、廃止前の 2023 年 6 月 30 日までに、使用を中止する必要があります。 この決定について詳しくは、こちらをご覧ください。

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

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

セットアップ

このガイドでは、Face キーとエンドポイント URL を使用して、faceClient という名前の FaceClient オブジェクトを既に作成していることを前提としています。 この機能を設定する方法については、クイックスタートのいずれかに従ってください。

サービスにデータを送信する

顔を検出し、画像内での位置を取得するには、DetectWithUrlAsync または DetectWithStreamAsync メソッドを呼び出します。 DetectWithUrlAsync は URL 文字列を入力として受け取り、DetectWithStreamAsync は画像の未加工のバイト ストリームを入力として受け取ります。

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

返された DetectedFace オブジェクトを照会して、そのオブジェクトの一意の ID と、顔のピクセル座標を示す四角形を取得できます。 これにより、どの顔 ID が元の画像のどの顔にマップされているかを知ることができます。

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

顔の位置と寸法を解析する方法については、「FaceRectangle」を参照してください。 通常、この四角形には、目、眉、鼻、口が含まれます。 頭の上部、耳、あごは必ずしも含まれません。 顔の四角形を使用して、頭部全体をトリミングしたり、上半身のポートレートを取得したりするには、四角形を各方向に拡張する必要があります。

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

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

顔のランドマークの取得

顔のランドマークとは、瞳孔、鼻の先など、顔の中の見つけやすいポイントのことです。 顔のランドマーク データを取得するには、detectionModel パラメーターを DetectionModel.Detection01 に、returnFaceLandmarks パラメーターを true に設定します。

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

顔の属性の取得

顔検出 API では、顔の四角形とランドマークに加えて、顔に関するいくつかの概念属性を分析できます。 完全な一覧については、顔の属性の概念に関するセクションを参照してください。

顔の属性を分析するには、detectionModel パラメーターを DetectionModel.Detection01 に、returnFaceAttributes パラメーターを FaceAttributeType Enum 値のリストに設定します。

var requiredFaceAttributes = new FaceAttributeType?[] {
    FaceAttributeType.Age,
    FaceAttributeType.Gender,
    FaceAttributeType.Smile,
    FaceAttributeType.FacialHair,
    FaceAttributeType.HeadPose,
    FaceAttributeType.Glasses,
    FaceAttributeType.Emotion,
    FaceAttributeType.QualityForRecognition
};
// Note DetectionModel.Detection02 cannot be used with returnFaceAttributes.
var faces3 = await faceClient.Face.DetectWithUrlAsync(url: imageUrl, returnFaceId: true, 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 age = attributes.Age;
    var gender = attributes.Gender;
    var smile = attributes.Smile;
    var facialHair = attributes.FacialHair;
    var headPose = attributes.HeadPose;
    var glasses = attributes.Glasses;
    var emotion = attributes.Emotion;
    var qualityForRecognition = attributes.QualityForRecognition;
}

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

次のステップ

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