دليل اكتشاف المعالم يدويًا في Python

تتيح لك مهمة معارِض اليد في MediaPipe اكتشاف معالم الأيدي في الصورة. توضح لك هذه التعليمات كيفية استخدام "مَعلمة اليد" مع لغة Python. تشير رسالة الأشكال البيانية نموذج التعليمات البرمجية الموضح في هذه التعليمات GitHub.

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

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

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

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

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

الطرود

تتطلب مهمة مؤشر MediaPipe يدوية وجود حزمة Mediapi PyPI. يمكنك تثبيت هذه التبعيات واستيرادها باستخدام ما يلي:

$ python -m pip install mediapipe

عمليات الاستيراد

قم باستيراد الفئات التالية للوصول إلى وظائف "أداة معلم اليد":

import mediapipe as mp
from mediapipe.tasks import python
from mediapipe.tasks.python import vision

الطراز

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

اختَر النموذج ونزِّله ثم خزِّنه في دليل محلي:

model_path = '/absolute/path/to/gesture_recognizer.task'

استخدام مَعلمة model_asset_path للكائن BaseOptions لتحديد المسار للنموذج المراد استخدامه. للاطّلاع على مثال على الرمز البرمجي، يُرجى مراجعة القسم التالي.

إنشاء المهمة

تستخدم مهمة أداة تمييز اليد من MediaPipe الدالة create_from_options من أجل لإعداد المهمة. تقبل الدالة create_from_options القيم. لمعالجة خيارات التهيئة. لمزيد من المعلومات عن الإعدادات يمكنك الاطّلاع على خيارات الإعداد.

يوضح الرمز التالي كيفية إنشاء هذه المهمة وإعدادها.

تُظهر هذه العينات أيضًا صيغ إنشاء المهمة للصور، وملفات الفيديو والبث المباشر.

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the image mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the video mode:
options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
HandLandmarker = mp.tasks.vision.HandLandmarker
HandLandmarkerOptions = mp.tasks.vision.HandLandmarkerOptions
HandLandmarkerResult = mp.tasks.vision.HandLandmarkerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a hand landmarker instance with the live stream mode:
def print_result(result: HandLandmarkerResult, output_image: mp.Image, timestamp_ms: int):
    print('hand landmarker result: {}'.format(result))

options = HandLandmarkerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with HandLandmarker.create_from_options(options) as landmarker:
  # The landmarker is initialized. Use it here.
  # ...
    

للحصول على مثال كامل لإنشاء "معلَم يد" لاستخدامه مع صورة، راجع مثال الرمز البرمجي.

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

تشتمل هذه المهمة على خيارات الإعداد التالية لتطبيقات بايثون:

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

قم بإعداد الإدخال كملف صورة أو صفيفة numpy، ثم تحويله إلى كائن mediapipe.Image. إذا كان الإدخال هو ملف فيديو أو البث المباشر من كاميرا الويب، يمكنك استخدام مكتبة خارجية مثل OpenCV لتحميل إطارات الإدخال بتنسيق numpy الصفائف.

import mediapipe as mp

# Load the input image from an image file.
mp_image = mp.Image.create_from_file('/path/to/image')

# Load the input image from a numpy array.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_image)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to load the input video.

# Load the frame rate of the video using OpenCV’s CV_CAP_PROP_FPS
# You’ll need it to calculate the timestamp for each frame.

# Loop through each frame in the video using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

import mediapipe as mp

# Use OpenCV’s VideoCapture to start capturing from the webcam.

# Create a loop to read the latest frame from the camera using VideoCapture#read()

# Convert the frame received from OpenCV to a MediaPipe’s Image object.
mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=numpy_frame_from_opencv)
    

تنفيذ المهمة

يستخدِم "معلم اليد" أدوات الرصد وdetect_for_video وdetect_async. الدوال لإثارة الاستنتاجات. لرصد المعالم يدويًا، يتضمن ذلك المعالجة المسبقة لبيانات الإدخال، ورصد الأيدي في الصورة ورصد اليد المعالم.

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

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the image mode.
hand_landmarker_result = landmarker.detect(mp_image)
    

# Perform hand landmarks detection on the provided single image.
# The hand landmarker must be created with the video mode.
hand_landmarker_result = landmarker.detect_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform hand landmarks detection.
# The results are accessible via the `result_callback` provided in
# the `HandLandmarkerOptions` object.
# The hand landmarker must be created with the live stream mode.
landmarker.detect_async(mp_image, frame_timestamp_ms)
    

يُرجى ملاحظة ما يلي:

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

للاطلاع على مثال كامل لتشغيل "معلَم اليد" على صورة، راجع مثال على الرمز لمعرفة التفاصيل.

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

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

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

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

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

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