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

تتيح لك مهمة أداة التعرّف على إيماءة 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, 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)

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

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