استدعاء واجهة برمجة التطبيقات للكشف

  • مقالة

تنبيه

الوصول إلى خدمة Face محدود استنادا إلى معايير الأهلية والاستخدام من أجل دعم مبادئنا الذكاء الاصطناعي المسؤولة. تتوفر خدمة Face فقط للعملاء والشركاء المدارين من Microsoft. استخدم نموذج إدخال التعرف على الوجوه لتقديم طلب للوصول. لمزيد من المعلومات، راجع صفحة Face ذات الوصول المحدود.

تنبيه

قامت Microsoft بإيقاف قدرات التعرف على الوجه التي يمكن استخدامها لمحاولة استنتاج الحالات العاطفية وسمات الهوية التي، إذا تمت إساءة استخدامها، يمكن أن تخضع الأشخاص للقوالب النمطية أو التمييز أو الحرمان غير العادل من الخدمات. ويشمل ذلك القدرات التي تتنبأ بالعاطفة والجنس والعمر والابتسامة وشعر الوجه والشعر والمكياج. اقرأ المزيد حول هذا القرار هنا .

يوضح هذا الدليل كيفية استخدام واجهة برمجة تطبيقات الكشف عن الوجه لاستخراج السمات من صورة معينة. ستتعلم الطرق المختلفة التي يمكنك من خلالها تكوين سلوك «واجهة برمجة التطبيقات» لتلبية احتياجاتك.

تتم كتابة القصاصات البرمجية في هذا الدليل بلغة C# باستخدام مكتبة عميل Azure الذكاء الاصطناعي Face. تتوفر الوظيفة نفسها باستخدام واجهة برمجة تطبيقات RESTً.

الإعداد

يفترض هذا الدليل أنك قمت بالفعل بإنشاء كائن FaceClient ، المسمى faceClient، باستخدام مفتاح Face وعنوان URL لنقطة النهاية. للحصول على إرشادات حول كيفية إعداد هذه الميزة، اتبع إحدى عمليات التشغيل السريع.

إرسال البيانات إلى الخدمة

للعثور على الوجوه والحصول على مواقعها في صورة، استدع الأسلوب DetectWithUrlAsync أو DetectWithStreamAsync. يتخذDetectWithUrlAsync سلسلة URL كمدخلات، ويتخذ DetectWithStreamAsync دفق البايت الخام للصورة كمدخلات.

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

تقوم الخدمة بإرجاع كائن DetectedFace ، والذي يمكنك الاستعلام عنه للحصول على أنواع مختلفة من المعلومات، المحددة أدناه.

للحصول على معلومات حول كيفية تحليل موقع الوجه وأبعاده، راجع FaceRectangle. عادةً، يشتمل هذا المستطيل على العينين، والحاجبين، والأنف والفم. لا يتم تضمين الجزء العلوي من الرأس، والآذان، والذقن بالضرورة. لاستخدام مستطيل الوجه لاقتصاص الرأس كاملةً أو الحصول على لقطة وُسطى لصورة الشخصية، يجب توسيع المستطيل في جميع الاتجاهات.

تحديد كيفية معالجة البيانات

يركز هذا الدليل على تفاصيل استدعاء Detect، مثل الوسائط التي يمكنك تمريرها، وما يمكنك فعله بالبيانات التي تم إرجاعها. نوصي بالاستعلام عن الميزات التي تحتاج إليها فقط. تستغرق كل عملية مزيدًا من الوقت لاستكمالها.

الحصول على معرف الوجه

إذا قمت بتعيين المعلمة returnFaceId إلى true (العملاء المعتمدون فقط)، يمكنك الحصول على المعرف الفريد لكل وجه، والذي يمكنك استخدامه في مهام التعرف على الوجه اللاحقة.

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

تحدد المعلمة faceIdTimeToLive الاختيارية المدة (بالثوان) التي يجب تخزين معرف الوجه على الخادم. بعد انتهاء صلاحية هذا الوقت، تتم إزالة معرف الوجه. القيمة الافتراضية هي 86400 (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);

الحصول على سمات الوجه

إلى جانب مستطيلات الوجه والمعالم، يمكن لواجهة برمجة تطبيقات الكشف عن الوجه تحليل العديد من السمات المفاهيمية للوجه. للحصول على قائمة كاملة، راجع القسم المفاهيمي لسمات الوجه.

لتحليل سمات الوجه، قم بتعيين معلمة detectionModel إلى DetectionModel.Detection01 والمعلمة returnFaceAttributes إلى قائمة بقيم تعداد FaceAttributeType.

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

لمعرفة المزيد حول كل من السمات، راجع الدليل المفاهيمي للكشف عن الوجه والسمات.

الخطوات التالية

في هذا الدليل، لقد تعلمت عن كيفية استخدام الوظائف المختلفة للكشف عن الوجه وتحليله. بعد ذلك، قم بدمج هذه الميزات في التطبيق لإضافة بيانات الوجه من المستخدمين.