検出 API を呼び出す

  • [アーティクル]

注意事項

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

注意

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

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

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

セットアップ

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

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

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

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

このサービスからは DetectedFace オブジェクトが返されます。これを使用すると、以下に指定されたさまざまな種類の情報を照会できます。

顔の位置と寸法を解析する方法については、「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 パラメーターを 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;
}

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

次のステップ

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