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

تتيح لك مهمة "تحديد موضع اليد" في MediaPipe اكتشاف مواضع اليد في صورة. توضّح لك هذه التعليمات كيفية استخدام أداة Hand Landmarker لتطبيقات الويب وتطبيقات JavaScript.

لمزيد من المعلومات حول إمكانات هذه المهمة ونماذجها وخيارات إعداداتها، يُرجى الاطّلاع على نظرة عامة.

مثال على الرمز

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

الإعداد

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

حِزم JavaScript

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

يمكنك تثبيت الحِزم المطلوبة من خلال 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.mjs"
    crossorigin="anonymous"></script>
</head>

الطراز

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

اختَر نموذجًا ونزِّله، ثم خزِّنه في دليل مشروعك:

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

إنشاء المهمة

استخدِم إحدى دوال createFrom...() الخاصة بميزة Hand Landmarker لإعداد المهمة من أجل تنفيذ عمليات الاستدلال. استخدِم الدالة createFromModelPath() مع مسار نسبي أو مطلق إلى ملف النموذج المدرَّب. إذا كان النموذج محملًا في الذاكرة، يمكنك استخدام طريقة createFromModelBuffer().

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

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

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

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

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

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

IMAGE: الوضع المخصّص لإدخال صورة واحدة.

الفيديو: الوضع المخصّص للإطارات التي تم فك ترميزها من فيديو أو بث مباشر لبيانات الإدخال، مثل البيانات الواردة من كاميرا		 ‎{IMAGE, VIDEO} IMAGE
numHands الحد الأقصى لعدد الأيدي التي يرصدها أداة رصد معالم اليد Any integer > 0 1
minHandDetectionConfidence الحد الأدنى لنتيجة الثقة التي يجب تحقيقها حتى يُعتبَر رصد اليد ناجحًا في نموذج رصد راحة اليد. 0.0 - 1.0 0.5
minHandPresenceConfidence الحد الأدنى لنتيجة الثقة في نموذج رصد مواضع اليد. في وضع &quot;الفيديو&quot; ووضع &quot;البث المباشر&quot;، إذا كانت نتيجة الثقة في رصد اليد من نموذج &quot;نقاط بارزة في اليد&quot; أقل من هذه القيمة الحدّية، سيؤدي Hand Landmarker إلى تشغيل نموذج رصد راحة اليد. بخلاف ذلك، تحدّد خوارزمية بسيطة لتتبُّع حركة اليدين موقع اليدين لرصد المعالم اللاحقة. 0.0 - 1.0 0.5
minTrackingConfidence تمثّل هذه السمة الحدّ الأدنى لدرجة الثقة التي يجب تحقيقها لكي يُعدّ تتبُّع اليد ناجحًا. هذا هو الحد الأدنى لمؤشر IoU الخاص بالمربّع المحيط بين اليدين في الإطار الحالي والإطار الأخير. في "وضع الفيديو" و"وضع البث" في أداة Hand Landmarker، إذا تعذّر التتبُّع، ستفعّل أداة Hand Landmarker ميزة رصد اليد. وفي حال عدم توفّرها، يتم تخطّي عملية رصد اليد. 0.0 - 1.0 0.5

إعداد البيانات

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

تنفيذ المهمة

يستخدم Hand Landmarker الطريقتَين detect() (مع وضع التشغيل image) وdetectForVideo() (مع وضع التشغيل video) لتفعيل الاستنتاجات. تعالج المهمة البيانات وتحاول رصد مواضع اليد، ثم تعرض النتائج.

يتم تنفيذ طلبات البيانات من الطريقتَين detect() وdetectForVideo() في Hand Landmarker بشكل متزامن، ما يؤدي إلى حظر سلسلة التعليمات الخاصة بواجهة المستخدم. في حال رصد علامات مميزة للأيدي في لقطات الفيديو من كاميرا الجهاز، سيؤدي كل عملية رصد إلى حظر سلسلة التعليمات الرئيسية. يمكنك منع حدوث ذلك من خلال تنفيذ عاملي الويب لتشغيل طريقتَي detect() وdetectForVideo() في سلسلة محادثات أخرى.

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

صورة

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

فيديو

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

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

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

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

للحصول على تنفيذ أكثر اكتمالاً لمهمة Hand Landmarker، راجِع المثال.

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

تنشئ أداة Hand Landmarker عنصر نتيجة خاصًا بها لكل عملية رصد. يحتوي عنصر النتيجة على معالم اليد في إحداثيات الصورة، ومعالم اليد في إحداثيات العالم، واستخدام إحدى اليدين(اليد اليسرى/اليمنى) للأيدي التي تم رصدها.

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

تحتوي النتيجة HandLandmarkerResult على ثلاثة مكوّنات. كل مكوّن هو عبارة عن مصفوفة، حيث يحتوي كل عنصر على النتائج التالية ليد واحدة تم رصدها:

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

    يمثل استخدام إحدى اليدين ما إذا كانت الأيدي التي تم رصدها هي أيدي يمنى أو يسرى.

  • معالم

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

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

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

HandLandmarkerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  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)

تعرض الصورة التالية تمثيلاً مرئيًا لناتج المهمة:

يد ترفع الإبهام مع توضيح الهيكل العظمي لليد

يوضّح مثال الرمز البرمجي الخاص بأداة Hand Landmarker كيفية عرض النتائج التي تعرضها المهمة، يمكنك الاطّلاع على المثال.