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

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

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

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

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

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

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

حزم JavaScript

يتوفّر رمز "محدِّد اليد" من خلال @mediapipe/tasks-vision MediaPipe. حزمة 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 بتخصيص معلم يدوي مع خيارات الإعداد. لمزيد من المعلومات عن الإعدادات يمكنك الاطّلاع على خيارات الإعداد.

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

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 الحد الأدنى لدرجة الثقة للحصول على نتيجة الحضور باليد نموذج اكتشاف المعالم. في وضع الفيديو ووضع البث المباشر إذا كانت نتيجة الثقة للتواجد على اليد من نموذج المعالم الرئيسية على اليد أقل من هذا الحد، يشغّل "مؤشر اليد" نموذج اكتشاف راحة اليد. بخلاف ذلك، تحدد خوارزمية التتبع الخفيف لليد موقع اليد(الأيدي) لعمليات الكشف اللاحقة للمعالم. 0.0 - 1.0 0.5
minTrackingConfidence يشير ذلك المصطلح إلى الحد الأدنى لدرجة الثقة التي يجب أن يراعيها تتبُّع اليد. وناجح. هذا هو الحد الأدنى لحجم صندوق الإحاطة بين اليدين في الإطار الحالي والإطار الأخير. في وضع الفيديو ووضع البث في معلم اليد، إذا فشل التتبع، يقوم مؤشر اليد باليد الرصد. في الحالات الأخرى، يتخطّى الجهاز ميزة "رصد اليد". 0.0 - 1.0 0.5

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

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

تنفيذ المهمة

يستخدم "مؤشر اليد" 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();
  });
}

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

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

أداة معلم اليد تنشئ كائن نتيجة معلم يد لكل عملية اكتشاف الجري. يحتوي عنصر النتيجة على معالم يد في إحداثيات الصورة، يد المعالِم في إحداثيات العالم ومدى استخدام اليد(اليد اليسرى أو اليمنى) للشخص الذي تم رصده يَدَان

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

تحتوي إخراج 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)

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

يوضح رمز مثال أداة معلم اليد طريقة عرض التي تم إرجاعها من المهمة، يمكنك الاطلاع على مثال على الرمز البرمجي