دليل التعرف على الإيماءات في بايثون

تتيح لك مهمة MediaPipe Gesture Recognizer (معرّف إيماءات MediaPipe) التعرّف على إيماءات اليد في الوقت الفعلي، وprovides the recognized hand gesture results and hand landmarks of the detected hands (توفّر نتائج إيماءات اليد التي تم التعرّف عليها ومواقع اليد المميّزة لليدين التي تم رصدها). توضِّح لك هذه التعليمات كيفية استخدام معرّف الإيماءات مع تطبيقات Python.

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

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

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

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

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

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

الطرود

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

$ python -m pip install mediapipe

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

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

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

الطراز

تتطلّب مهمة MediaPipe Gesture Recognizer حِزمة نموذج مدرَّب متوافقة مع هذه المهمة. لمزيد من المعلومات عن النماذج المدربة المتاحة لميزة "التعرّف على الإيماءات"، اطّلِع على النظرة العامة على المهمة في قسم "النماذج".

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

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

حدِّد مسار النموذج ضمن مَعلمة "اسم النموذج"، كما هو موضّح أدناه:

base_options = BaseOptions(model_asset_path=model_path)

إنشاء المهمة

تستخدِم مهمة MediaPipe Gesture Recognizer الدالة create_from_options لإعداد المهمة. تقبل الدالة create_from_options قيمًا لإعدادات options التي يجب التعامل معها. لمزيد من المعلومات حول خيارات الضبط، يُرجى الاطّلاع على خيارات الضبط.

يوضّح الرمز البرمجي التالي كيفية إنشاء هذه المهمة وضبطها.

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

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the image mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.IMAGE)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the video mode:
options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.VIDEO)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector is initialized. Use it here.
  # ...
    

import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
GestureRecognizer = mp.tasks.vision.GestureRecognizer
GestureRecognizerOptions = mp.tasks.vision.GestureRecognizerOptions
GestureRecognizerResult = mp.tasks.vision.GestureRecognizerResult
VisionRunningMode = mp.tasks.vision.RunningMode

# Create a gesture recognizer instance with the live stream mode:
def print_result(result: GestureRecognizerResult, output_image: mp.Image, timestamp_ms: int):
    print('gesture recognition result: {}'.format(result))

options = GestureRecognizerOptions(
    base_options=BaseOptions(model_asset_path='/path/to/model.task'),
    running_mode=VisionRunningMode.LIVE_STREAM,
    result_callback=print_result)
with GestureRecognizer.create_from_options(options) as recognizer:
  # The detector 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)
    

تنفيذ المهمة

يستخدم معرّف الإيماءات الدوالّ recognize وrecognize_for_video وrecognize_async لبدء الاستنتاجات. بالنسبة إلى ميزة التعرّف على الإيماءات، يشمل ذلك المعالجة المُسبَقة لبيانات الإدخال، ورصد الأيدي في الصورة، ورصد نقاط إشارة اليد، والتعرّف على إيماءات اليد من نقاط الإشارة.

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

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the image mode.
gesture_recognition_result = recognizer.recognize(mp_image)
    

# Perform gesture recognition on the provided single image.
# The gesture recognizer must be created with the video mode.
gesture_recognition_result = recognizer.recognize_for_video(mp_image, frame_timestamp_ms)
    

# Send live image data to perform gesture recognition.
# The results are accessible via the `result_callback` provided in
# the `GestureRecognizerOptions` object.
# The gesture recognizer must be created with the live stream mode.
recognizer.recognize_async(mp_image, frame_timestamp_ms)
    

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

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

للحصول على مثال كامل على تشغيل معرّف الإيماءات على صورة، اطّلِع على مثال الرمز المبرمَج للحصول على التفاصيل.

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

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

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

يحتوي GestureRecognizerResult الناتج على أربعة مكوّنات، وكل مكوّن هو صفيف، حيث يحتوي كل عنصر على النتيجة التي تم رصدها ليد واحدة تم رصدها.

• استخدام إحدى اليدين

  يشير مقياس اليد المفضّلة إلى ما إذا كانت الأيدي التي تم رصدها هي اليد اليمنى أو اليسرى.

• الإيماءات

  فئات الإيماءات التي تم التعرّف عليها لليدين التي تم رصدها

• معالم

  هناك 21 معلمًا يخصّ اليد، ويتكون كلّ منها من إحداثيات x وy وz. يتم توحيد إحداثيات x وy لتكون [0.0, 1.0] حسب عرض الصورة وارتفاعها على التوالي. يمثّل الإحداثي z عمق المَعلم، مع كون العميق عند الرسغ هو الأصل. وكلما كانت القيمة أصغر، كان المَعلم أقرب إلى الكاميرا. يستخدم حجم z المقياس نفسه تقريبًا الذي يستخدمه x.

• معالم عالمية

  يتم أيضًا عرض 21 معلمًا يدويًا بالإحداثيات العالمية. يتألّف كل معلم من x وy وz، وهي تمثل إحداثيات ثلاثية الأبعاد في العالم الحقيقي بال مترات مع منشأ في المركز الهندسي لليد.

GestureRecognizerResult:
  Handedness:
    Categories #0:
      index        : 0
      score        : 0.98396
      categoryName : Left
  Gestures:
    Categories #0:
      score        : 0.76893
      categoryName : Thumb_Up
  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)

تعرض الصور التالية عرضًا مرئيًا لمخرجات المهمة:

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