دليل التعرّف على الإيماءات للويب

تتيح لك مهمة التعرّف على الإيماءة MediaPipe التعرف على إيماءات اليد في الوقت الفعلي نتائج إيماءة اليد المعروفة ومعالم اليد الأيدي المرصودة. توضّح لك هذه التعليمات كيفية استخدام "أداة التعرّف على الإيماءة". لتطبيقات الويب وتطبيقات JavaScript.

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

مثال على الرمز البرمجي

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

ضبط إعدادات الجهاز

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

حزم JavaScript

يتوفّر رمز أداة التعرّف على الإيماءة من خلال MediaPipe @mediapipe/tasks-vision. حزمة NPM. يمكنك البحث عن هذه المكتبات وتنزيلها من خلال اتّباع التعليمات الواردة في النظام الأساسي دليل الإعداد.

يمكنك تثبيت الحزم المطلوبة من خلال NPM باستخدام الأمر التالي:

npm install @mediapipe/tasks-vision

إذا كنت ترغب في استيراد رمز المهمة عبر شبكة توصيل المحتوى (CDN) أضف الرمز التالي في العلامة <head> في ملف HTML لديك:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.js"
    crossorigin="anonymous"></script>
</head>

الطراز

تتطلب مهمة أداة التعرّف على الإيماءة MediaPipe نموذجًا مدرَّبًا متوافقًا مع هذه المهمة. لمزيد من المعلومات عن النماذج المدرَّبة المتاحة لميزة "التعرُّف على الإيماءة"، يُرجى الاطّلاع على نظرة عامة على المهمة قسم النماذج.

حدد النموذج ونزّله ثم خزّنه في دليل المشروع:

<dev-project-root>/app/shared/models/

إنشاء المهمة

يمكنك استخدام إحدى وظائف "أداة التعرّف على الإيماءة" createFrom...() من أجل وتجهز المهمة لتشغيل الاستنتاجات. استخدام createFromModelPath() مع مسار نسبي أو مطلق لملف النموذج المدرَّب. إذا تم تحميل نموذجك في الذاكرة من قبل، يمكنك استخدام طريقة createFromModelBuffer().

يوضح مثال الرمز البرمجي أدناه استخدام الدالة createFromOptions() من أجل لإعداد المهمة. تسمح لك الدالة createFromOptions بتخصيص أداة التعرّف على الإيماءة مع خيارات الإعداد. لمزيد من المعلومات عن الإعدادات يمكنك الاطّلاع على خيارات الإعداد.

يوضح الرمز التالي كيفية إنشاء المهمة وإعدادها باستخدام الخيارات:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

خيارات الإعداد

تتضمّن هذه المهمة خيارات الضبط التالية لتطبيقات الويب:

اسم الخيار الوصف نطاق القيمة القيمة الافتراضية
runningMode لضبط وضع التشغيل للمهمة. هناك خياران وسائل النقل:

IMAGE: وضع إدخالات الصورة الفردية

فيديو: وضع الإطارات التي تم فك ترميزها مقطع فيديو أو بث مباشر لبيانات المدخلات، مثل من الكاميرا.		 {IMAGE, VIDEO} IMAGE
num_hands يمكن اكتشاف الحد الأقصى لعدد الأيدي من خلال GestureRecognizer. Any integer > 0 1
min_hand_detection_confidence الحد الأدنى لنتيجة الثقة لرصد اليد تُعد ناجحة في نموذج اكتشاف راحة اليد. 0.0 - 1.0 0.5
min_hand_presence_confidence الحد الأدنى لدرجة الثقة في نتيجة التواجد باليد نموذج اكتشاف المعالم. في وضع "الفيديو" ووضع البث المباشر في "أداة التعرّف على الإيماءة"، إذا كانت نتيجة الثقة باليد من خلال نموذج المعالم على اليد أقل من هذا الحد، فإنها تؤدي إلى نموذج اكتشاف راحة اليد. بخلاف ذلك، استخدام خوارزمية تتبع اليد البسيطة لتحديد موقع اليد(الأيدي) لاكتشاف المعالم لاحقًا. 0.0 - 1.0 0.5
min_tracking_confidence يشير ذلك المصطلح إلى الحد الأدنى لدرجة الثقة التي يجب أن يراعيها تتبُّع اليد. وناجح. هذا هو الحد الأدنى لحجم صندوق الإحاطة بين اليدين في الإطار الحالي والإطار الأخير. في وضع الفيديو ووضع البث في أداة التعرّف على الإيماءة، إذا تعذَّر التتبُّع، تعمل ميزة التعرّف على الإيماءة على تشغيل اليد الرصد. وبخلاف ذلك، يتم تخطي اكتشاف اليد. 0.0 - 1.0 0.5
canned_gestures_classifier_options خيارات تهيئة سلوك مصنف الإيماءات الجاهزة. الإيماءات الجاهزة هي ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
  • لغة الأسماء المعروضة: اللغة المراد استخدامها للأسماء المعروضة المحددة من خلال البيانات الوصفية لنموذج TFLite، إن توفرت.
  • الحد الأقصى للنتائج: الحد الأقصى لعدد نتائج التصنيف الأعلى تقييمًا المطلوب عرضها. إذا كانت قيمة 0، سيتم عرض جميع النتائج المتاحة.
  • الحد الأدنى للنتيجة: النتيجة التي رُفضت النتائج التي تكون دونها. في حال ضبط هذه السياسة على 0، سيتم عرض جميع النتائج المتاحة.
  • القائمة المسموح بها للفئات: القائمة المسموح بها لأسماء الفئات. إذا كانت غير فارغة، فسيتم تصفية نتائج التصنيف التي لا توجد فئتها في هذه المجموعة. الأحداث المتنافية مع قائمة الحظر.
  • قائمة حظر الفئات: قائمة حظر أسماء الفئات إذا لم يكن الحقل فارغًا، فستتم فلترة نتائج التصنيف التي تحتوي على فئتها في هذه المجموعة. يمكن استخدام القائمة المسموح بها بشكل تبادلي.
    		•
    • لغة الأسماء المعروضة: any string
    • الحد الأقصى للنتائج: any integer
    • الحد الأدنى للنتيجة: 0.0-1.0
    • القائمة المسموح بها للفئات: vector of strings
    • قائمة حظر الفئات: vector of strings
    • لغة الأسماء المعروضة: "en"
    • الحد الأقصى للنتائج: -1
    • الحد الأدنى للنتيجة: 0
    • القائمة المسموح بها للفئات: فارغة
    • قائمة حظر الفئات: فارغة
    custom_gestures_classifier_options خيارات ضبط سلوك مصنِّف الإيماءات المخصّصة
  • لغة الأسماء المعروضة: اللغة المراد استخدامها للأسماء المعروضة المحددة من خلال البيانات الوصفية لنموذج TFLite، إن توفرت.
  • الحد الأقصى للنتائج: الحد الأقصى لعدد نتائج التصنيف الأعلى تقييمًا المطلوب عرضها. إذا كانت قيمة 0، سيتم عرض جميع النتائج المتاحة.
  • الحد الأدنى للنتيجة: النتيجة التي رُفضت النتائج التي تكون دونها. في حال ضبط هذه السياسة على 0، سيتم عرض جميع النتائج المتاحة.
  • القائمة المسموح بها للفئات: القائمة المسموح بها لأسماء الفئات. إذا كانت غير فارغة، فسيتم تصفية نتائج التصنيف التي لا توجد فئتها في هذه المجموعة. الأحداث المتنافية مع قائمة الحظر.
  • قائمة حظر الفئات: قائمة حظر أسماء الفئات إذا لم يكن الحقل فارغًا، فستتم فلترة نتائج التصنيف التي تحتوي على فئتها في هذه المجموعة. يمكن استخدام القائمة المسموح بها بشكل تبادلي.
    		•
    • لغة الأسماء المعروضة: any string
    • الحد الأقصى للنتائج: any integer
    • الحد الأدنى للنتيجة: 0.0-1.0
    • القائمة المسموح بها للفئات: vector of strings
    • قائمة حظر الفئات: vector of strings
    • لغة الأسماء المعروضة: "en"
    • الحد الأقصى للنتائج: -1
    • الحد الأدنى للنتيجة: 0
    • القائمة المسموح بها للفئات: فارغة
    • قائمة حظر الفئات: فارغة

    تجهيز البيانات

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

    تنفيذ المهمة

    تستخدم ميزة "التعرّف على الإيماءة" recognize() (مع وضع التشغيل 'image') طرق recognizeForVideo() (مع وضع التشغيل 'video') لتشغيلها والاستنتاجات. تقوم المهمة بمعالجة البيانات، وتحاول التعرف على اليد والإيماءات، ثم تقوم بالإبلاغ عن النتائج.

    يوضح الرمز البرمجي التالي كيفية تنفيذ المعالجة باستخدام نموذج المهمة:

    صورة

    const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

    فيديو

    await gestureRecognizer.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

    يتم تشغيل المكالمات الواردة إلى طريقة التعرّف على الإيماءة recognize() وrecognizeForVideo(). بشكل متزامن وحظر مؤشر ترابط واجهة المستخدم. إذا تعرفت على الإيماءات في إطارات الفيديو من كاميرا الجهاز، فإن كل طريقة التعرف ستحظر . ويمكنك منع ذلك من خلال تنفيذ عاملي الويب لتشغيل recognize() وrecognizeForVideo() طريقة في سلسلة محادثات أخرى

    للحصول على تنفيذ أكثر اكتمالاً لتنفيذ مهمة "تعرّف على الإيماءة"، راجع مثال الرمز البرمجي.

    التعامل مع العملاء وعرض النتائج

    تُنشئ أداة التعرّف على الإيماءة كائن نتيجة لاكتشاف الإيماءة لكل تشغيل التعرف. يحتوي كائن النتيجة على معالم يدوية في إحداثيات الصورة، معالم لليد في إحداثيات العالم واستخدام اليد(اليد اليسرى أو اليمنى) واليد وفئات الإيماءات للأيدي المرصودة.

    في ما يلي مثال على بيانات الإخراج من هذه المهمة:

    تحتوي GestureRecognizerResult الناتجة على أربعة مكوّنات، وكل مكوّن هو مصفوفة يحتوي كل عنصر فيها على النتيجة التي تم رصدها بيد واحدة.

    • استخدام إحدى اليدين

      ويشير مقياس "استخدام اليدين" إلى ما إذا كانت الأيدي اليسرى أو اليمنى.

    • الإيماءات

      فئات الإيماءات التي يتم التعرّف عليها للأيدي المرصودة.

    • المعالم

      هناك 21 مَعلمًا لليد، ويتألف كلّ منها من إحداثيات x وy وz. تشير رسالة الأشكال البيانية تتم تسوية إحداثيات x وy إلى [0.0، 1.0] حسب عرض الصورة الارتفاع، على التوالي. ويمثل الإحداثي z عمق المَعلم، مع العمق في المعصم هو المنشأ. كلما كانت القيمة أصغر، اقتربت هو أمام الكاميرا. يستخدم المقدار z تقريبًا نفس المقياس مثل x

    • معالم عالمية

      يتم أيضًا عرض المعالم البالغ عددها 21 يدًا في الإحداثيات العالمية. كل مَعلم تتكون من x وy وz، وتمثل الإحداثيات الثلاثية الأبعاد في العالم الحقيقي في مترًا مع نقطة الأصل في مركز اليد الهندسي.

    GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : -3.41E-7
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
    ... (21 landmarks for a hand)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
    ... (21 world landmarks for a hand)

    تُظهر الصور التالية تصورًا لنتج المهمة:

    للحصول على تنفيذ أكثر اكتمالاً لإنشاء مهمة أداة التعرّف على الإيماءة، راجع مثال الرمز البرمجي.