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

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

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

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

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

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

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

حِزم JavaScript

يتوفّر رمز Hand Markdowner من خلال حزمة 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 Handmarker نموذجًا مدرَّبًا متوافقًا مع هذه المهمة. لمزيد من المعلومات حول النماذج المدربة المتاحة من أجل أداة Handmarker، راجع نظرة عامة على المهمة في قسم النماذج.

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

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

إنشاء المهمة

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

يوضح مثال الرمز البرمجي أدناه استخدام الدالة createFromOptions() لإعداد المهمة. تتيح لك الدالة createFromOptions تخصيص Handanderer باستخدام خيارات التهيئة. لمزيد من المعلومات حول خيارات الضبط، راجِع خيارات الضبط.

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

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, VIDEO`}	`IMAGE`
`numHands`	الحد الأقصى لعدد الأيدي التي يتم رصدها بواسطة أداة رصد معلَمة اليد	`Any integer > 0`	`1`
`minHandDetectionConfidence`	تمثّل هذه السمة الحد الأدنى لدرجة الثقة ليتم اعتبار رصد اليد ناجحًا في نموذج اكتشاف راحة اليد.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	تمثّل هذه السمة الحد الأدنى لدرجة الثقة لنتيجة تواجد اليد في نموذج رصد معالِم اليد. في وضع الفيديو ووضع البث المباشر، إذا كانت نتيجة الثقة في تواجد اليد من نموذج علامات اليد أقل من هذا الحدّ، تشغّل أداة قياس راحة اليد نموذج رصد راحة اليد. وبخلاف ذلك، تحدّد خوارزمية تتبُّع بسيطة لليد موقع الأيدي من أجل رصد المعالم لاحقًا.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	تمثّل هذه السمة الحد الأدنى لدرجة الثقة ليتم اعتبار تتبُّع اليد ناجحًا. هذا هو الحدّ الأدنى لوحدات وحدات القياس بين الأيدي في الإطار الحالي والإطار الأخير. في وضع "الفيديو" ووضع "البث" في أداة قياس اليد، إذا تعذّر إتمام عملية التتبُّع، تشغّل أداة Handمجموعة ميزة "رصد اليد". وفي حال عدم تنفيذ هذا الإجراء، يتخطّى الجهاز ميزة رصد اليد.	`0.0 - 1.0`	`0.5`

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

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

تنفيذ المهمة

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

يتم تنفيذ الطلبات إلى طريقتَي محدّد أداة اليد detect() وdetectForVideo() بشكل متزامن ويتم حظر سلسلة محادثات واجهة المستخدم. إذا رصدت معالم اليد في إطارات الفيديو من كاميرا الجهاز، ستحجب كل عملية رصد سلسلة التعليمات الرئيسية. ويمكنك منع ذلك من خلال تنفيذ مشغّلي الويب لتشغيل الطريقتَين 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();
  });
}

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

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

تنشئ أداة قياس اليد كائن نتيجة مؤشر اليد لكل عملية اكتشاف. يحتوي كائن النتيجة على معالم لليد في إحداثيات الصور، ومعالم لليد في إحداثيات العالم، واليد(اليد اليسرى/اليمنى) لليدين المكتشفة.

ويوضح ما يلي مثالاً على بيانات المخرجات من هذه المهمة:

يحتوي ناتج 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)

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

يوضح رمز نموذج Handmarker كيفية عرض النتائج التي تم إرجاعها من المهمة، راجع مثال الرمز