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

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

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

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

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

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

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

الطرود

تتطلب مهمة MediaPipe Handmarker حزمة Media تطابق PyPI. يمكنك تثبيت هذه التبعيات واستيرادها باستخدام ما يلي:

$ python -m pip install mediapipe

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

قم باستيراد الفئات التالية للوصول إلى دوال مهمة Handmarker:

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

الطراز

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

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

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

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

إنشاء المهمة

تستخدم مهمة MediaPipe Handmarker الدالة 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)

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

يوضح رمز نموذج مؤشر اليد كيفية عرض النتائج التي تم إرجاعها من المهمة، راجع مثال الرمز البرمجي للحصول على التفاصيل.