Memanggil API Deteksi

Artikel
02/16/2024

Perhatian

Akses layanan Face dibatasi berdasarkan kelayakan dan kriteria penggunaan untuk mendukung prinsip AI kami yang Bertanggung Jawab. Layanan Face hanya tersedia untuk pelanggan dan mitra terkelola Microsoft. Gunakan formulir pengambilan Pengenalan Wajah untuk mengajukan akses. Untuk informasi selengkapnya, lihat halaman Akses terbatas Wajah.

Perhatian

Microsoft memiliki kemampuan pengenalan wajah yang dihentikan yang dapat digunakan untuk mencoba menyimpulkan status emosional dan atribut identitas yang, jika disalahgunakan, dapat menyebabkan orang-orang melakukan stereotip, diskriminasi, atau penolakan layanan yang tidak wajar. Ini termasuk kemampuan yang memprediksi emosi, jenis kelamin, usia, senyum, rambut wajah, rambut, dan riasan. Baca selengkapnya tentang keputusan ini di sini.

Panduan ini menunjukkan cara menggunakan API deteksi wajah untuk mengekstrak atribut dari gambar tertentu. Anda akan mempelajari berbagai cara untuk mengonfigurasi perilaku API ini untuk memenuhi kebutuhan Anda.

Cuplikan kode dalam panduan ini ditulis dalam C# dengan menggunakan pustaka klien Azure AI Face. Fungsionalitas yang sama tersedia melalui REST API.

Penyiapan

Panduan ini mengasumsikan bahwa Anda sudah membuat objek FaceClient , bernama faceClient, menggunakan kunci Wajah dan URL titik akhir. Untuk petunjuk tentang cara menyiapkan fitur ini, ikuti salah satu mulai cepat.

Kirimkan data ke layanan

Untuk menemukan wajah dan mendapatkan lokasi mereka dalam gambar, panggil metode DetectWithUrlAsync atau DetectWithStreamAsync. DetectWithUrlAsync mengambil untai (karakter) URL sebagai input dan DetectWithStreamAsync mengambil aliran byte mentah dari gambar sebagai input.

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

Layanan mengembalikan objek DetectedFace , yang dapat Anda kueri untuk berbagai jenis informasi, yang ditentukan di bawah ini.

Untuk informasi tentang cara mengurai lokasi dan dimensi wajah, lihat FaceRectangle. Biasanya, persegi panjang ini berisi mata, alis, hidung, dan mulut. Bagian atas kepala, telinga, dan dagu belum tentu disertakan. Untuk menggunakan persegi wajah untuk memangkas kepala keseluruhan atau mendapatkan potret bidikan tengah, Anda dapat memperluas persegi ke setiap arah.

Tentukan cara memproses data

Panduan ini berfokus pada spesifikasi panggilan Deteksi, seperti argumen apa yang bisa Anda lewati dan apa yang bisa Anda lakukan dengan data yang dikembalikan. Sebaiknya Anda mengkueri hanya fitur yang Anda butuhkan. Setiap operasi membutuhkan waktu lebih panjang untuk selesai.

Dapatkan ID wajah

Jika Anda mengatur parameter returnFaceId ke true (hanya pelanggan yang disetujui), Anda bisa mendapatkan ID unik untuk setiap wajah, yang dapat Anda gunakan dalam tugas pengenalan wajah nanti.

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

Parameter faceIdTimeToLive opsional menentukan berapa lama (dalam detik) ID wajah harus disimpan di server. Setelah waktu ini kedaluwarsa, ID wajah dihapus. Nilai defaultnya adalah 86400 (24 jam).

Mendapatkan tengara wajah

Tengara wajah adalah satu set titik yang mudah ditemukan di wajah, seperti pupil atau ujung hidung. Untuk mendapatkan data penanda wajah, atur parameter detectionModel ke DetectionModel.Detection01 dan parameter returnFaceLandmarks ke 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);

Dapatkan atribut wajah

Selain persegi panjang dan tengara wajah, API deteksi wajah dapat menganalisis beberapa atribut konseptual wajah. Untuk daftar lengkap, lihat bagian konseptual Atribut wajah.

Untuk menganalisis atribut wajah, atur parameter detectionModel ke DetectionModel.Detection01 dan parameter returnFaceAttributes ke daftar nilai 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);

Dapatkan hasil dari layanan

Hasil penanda wajah

Kode berikut menunjukkan bagaimana Anda dapat mengambil lokasi hidung dan pupil:

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;

Anda juga dapat menggunakan data penanda wajah untuk mengalkulasi arah wajah secara akurat. Misalnya, Anda dapat menentukan rotasi wajah sebagai vektor dari tengah mulut ke tengah mata. Kode berikut mengalkulasi vektor ini:

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

Ketika Anda mengetahui arah wajah, Anda dapat memutar bingkai persegi panjang wajah untuk menyelaraskannya dengan lebih baik. Untuk memangkas wajah dalam gambar, Anda dapat memutar gambar secara terprogram sehingga wajah selalu tampak tegak.

Hasil atribut wajah

Kode berikut menunjukkan cara Anda dapat mengambil data atribut wajah yang Anda minta dalam panggilan asli.

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

Untuk mempelajari lebih lanjut tentang masing-masing atribut, lihat panduan konseptual Deteksi wajah dan atribut.

Langkah berikutnya

Dalam panduan ini, Anda mempelajari cara menggunakan berbagai fungsionalitas pendeteksi wajah dan analisis. Selanjutnya, integrasikan fitur ini ke dalam aplikasi untuk menambahkan data wajah dari pengguna.

Tutorial: Tambahkan pengguna ke layanan Face