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

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

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

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

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

إذا كنت بصدد تنفيذ ميزة "وضع علامات على أجزاء اليد" لأجهزة Raspberry Pi، يُرجى الرجوع إلى مثال تطبيق Raspberry Pi.

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

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

الطرود

تتطلّب مهمة MediaPipe Hand Landmarker حزمة mediapipe PyPI. يمكنك تثبيت هذه التبعيات واستيرادها باستخدام ما يلي:

$ python -m pip install mediapipe

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

استورِد الفئات التالية للوصول إلى دوال مهمة "وضع علامات على أجزاء اليد":

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

الطراز

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

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

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

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

إنشاء المهمة

تستخدِم مهمة MediaPipe Hand Landmarker الدالة 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.
  # ...
    

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

خيارات الضبط

تتضمّن هذه المهمة خيارات الضبط التالية لتطبيقات Python:

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

حضِّر الإدخال كملف صورة أو صفيف 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)
    

تنفيذ المهمة

يستخدم Hand Landmarker الدوالّ detect و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)

تعرض الصورة التالية عرضًا مرئيًا لمعدّل تكرار المهمة:

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