راهنمای تشخیص ژست برای پایتون

وظیفه MediaPipe Gesture Recognizer به شما امکان می دهد حرکات دست را در زمان واقعی تشخیص دهید و نتایج تشخیص دست و نشانه های دست را در دست های شناسایی شده ارائه می دهد. این دستورالعمل به شما نشان می دهد که چگونه از Gesture Recognizer با برنامه های پایتون استفاده کنید.

می‌توانید با مشاهده نسخه نمایشی وب، این کار را در عمل مشاهده کنید. برای اطلاعات بیشتر در مورد قابلیت‌ها، مدل‌ها و گزینه‌های پیکربندی این کار، به نمای کلی مراجعه کنید.

نمونه کد

کد مثال برای Gesture Recognizer پیاده سازی کامل این کار را در پایتون برای مرجع شما فراهم می کند. این کد به شما کمک می کند تا این کار را آزمایش کنید و شروع به ساختن تشخیص دهنده ژست دست خود کنید. می‌توانید کد نمونه Gesture Recognizer را فقط با استفاده از مرورگر وب خود مشاهده، اجرا و ویرایش کنید.

اگر از Gesture Recognizer برای Raspberry Pi استفاده می کنید، به برنامه نمونه Raspberry Pi مراجعه کنید.

راه اندازی

این بخش مراحل کلیدی را برای راه اندازی محیط توسعه و پروژه های کد مخصوصاً برای استفاده از Gesture Recognizer توضیح می دهد. برای اطلاعات کلی در مورد تنظیم محیط توسعه خود برای استفاده از وظایف MediaPipe، از جمله الزامات نسخه پلت فرم، به راهنمای راه اندازی برای 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 به یک بسته مدل آموزش دیده نیاز دارد که با این کار سازگار باشد. برای اطلاعات بیشتر در مورد مدل‌های آموزش‌دیده موجود برای Gesture Recognizer، بخش مدل‌های نمای کلی کار را ببینید.

مدل را انتخاب و دانلود کنید و سپس آن را در یک فهرست محلی ذخیره کنید:

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

مسیر مدل را در پارامتر Model Name مانند شکل زیر مشخص کنید:

base_options = BaseOptions(model_asset_path=model_path)

کار را ایجاد کنید

وظیفه MediaPipe Gesture Recognizer از تابع create_from_options برای تنظیم کار استفاده می کند. تابع create_from_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.
  # ...
    

گزینه های پیکربندی

این کار دارای گزینه های پیکربندی زیر برای برنامه های پایتون است:

نام گزینه توضیحات محدوده ارزش مقدار پیش فرض
running_mode حالت اجرا را برای کار تنظیم می کند. سه حالت وجود دارد:

IMAGE: حالت برای ورودی های تک تصویر.

VIDEO: حالت برای فریم های رمزگشایی شده یک ویدیو.

LIVE_STREAM: حالت پخش زنده داده های ورودی، مانند دوربین. در این حالت، resultListener باید فراخوانی شود تا شنونده ای را برای دریافت نتایج به صورت ناهمزمان تنظیم کند.
{ IMAGE, VIDEO, LIVE_STREAM } IMAGE
num_hands حداکثر تعداد دست ها را می توان توسط GestureRecognizer شناسایی کرد. Any integer > 0 1
min_hand_detection_confidence حداقل امتیاز اطمینان برای تشخیص دست برای موفقیت در مدل تشخیص کف دست. 0.0 - 1.0 0.5
min_hand_presence_confidence حداقل امتیاز اطمینان امتیاز حضور دست در مدل تشخیص نقطه عطف دست. در حالت ویدیو و حالت پخش زنده Gesture Recognizer، اگر امتیاز مطمئن حضور دست از مدل نقطه عطف دست کمتر از این آستانه باشد، مدل تشخیص کف دست را فعال می‌کند. در غیر این صورت، یک الگوریتم ردیابی دست سبک وزن برای تعیین محل دست(ها) برای تشخیص نقطه عطف بعدی استفاده می شود. 0.0 - 1.0 0.5
min_tracking_confidence حداقل امتیاز اطمینان برای ردیابی دست که موفقیت آمیز در نظر گرفته شود. این آستانه جعبه محدود کننده IoU بین دست ها در فریم فعلی و آخرین فریم است. در حالت ویدیو و حالت جریان تشخیص حرکت، اگر ردیابی ناموفق باشد، تشخیص حرکت تشخیص دست را فعال می‌کند. در غیر این صورت، تشخیص دست نادیده گرفته می شود. 0.0 - 1.0 0.5
canned_gestures_classifier_options گزینه هایی برای پیکربندی رفتار طبقه بندی کننده حرکات کنسرو شده. حرکات کنسرو شده عبارتند از ["None", "Closed_Fist", "Open_Palm", "Pointing_Up", "Thumb_Down", "Thumb_Up", "Victory", "ILoveYou"]
  • محل نام‌های نمایشی: محلی برای استفاده برای نام‌های نمایشی مشخص شده از طریق فراداده مدل TFLite، در صورت وجود.
  • حداکثر نتایج: حداکثر تعداد نتایج طبقه بندی با امتیاز بالا برای بازگشت. اگر < 0 باشد، تمام نتایج موجود برگردانده خواهند شد.
  • آستانه امتیاز: امتیازی که زیر آن نتایج رد می شود. اگر روی 0 تنظیم شود، همه نتایج موجود برگردانده خواهند شد.
  • فهرست مجاز دسته ها: لیست مجاز نام دسته ها. اگر خالی نباشد، نتایج طبقه‌بندی که دسته آنها در این مجموعه نیست فیلتر می‌شوند. انحصاری متقابل با denylist.
  • Category denylist: فهرست انکار نام دسته ها. در صورت خالی نبودن، نتایج طبقه بندی که دسته آنها در این مجموعه است فیلتر می شود. متقابل منحصر به فرد با لیست مجاز.
    • محل نمایش نام: any string
    • حداکثر نتایج: any integer
    • آستانه امتیاز: 0.0-1.0
    • لیست مجاز دسته: vector of strings
    • Category denylist: vector of strings
    • محل نام های نمایشی: "en"
    • حداکثر نتایج: -1
    • آستانه امتیاز: 0
    • لیست مجاز دسته: خالی
    • فهرست رد رده: خالی
    custom_gestures_classifier_options گزینه هایی برای پیکربندی رفتار طبقه بندی کننده حرکات سفارشی.
  • محل نام‌های نمایشی: محلی برای استفاده برای نام‌های نمایشی مشخص شده از طریق فراداده مدل TFLite، در صورت وجود.
  • حداکثر نتایج: حداکثر تعداد نتایج طبقه بندی با امتیاز بالا برای بازگشت. اگر < 0 باشد، تمام نتایج موجود برگردانده خواهند شد.
  • آستانه امتیاز: امتیازی که زیر آن نتایج رد می شود. اگر روی 0 تنظیم شود، همه نتایج موجود برگردانده خواهند شد.
  • فهرست مجاز دسته ها: لیست مجاز نام دسته ها. اگر خالی نباشد، نتایج طبقه‌بندی که دسته آنها در این مجموعه نیست فیلتر می‌شوند. انحصاری متقابل با denylist.
  • Category denylist: فهرست انکار نام دسته ها. در صورت خالی نبودن، نتایج طبقه بندی که دسته آنها در این مجموعه است فیلتر می شود. متقابل منحصر به فرد با لیست مجاز.
    • محل نمایش نام: any string
    • حداکثر نتایج: any integer
    • آستانه امتیاز: 0.0-1.0
    • لیست مجاز دسته: vector of strings
    • Category denylist: vector of strings
    • محل نام های نمایشی: "en"
    • حداکثر نتایج: -1
    • آستانه امتیاز: 0
    • لیست مجاز دسته: خالی
    • فهرست رد رده: خالی
    result_callback شنونده نتیجه را طوری تنظیم می‌کند که وقتی تشخیص‌دهنده اشاره در حالت پخش زنده است، نتایج طبقه‌بندی را به‌صورت ناهمزمان دریافت کند. فقط زمانی قابل استفاده است که حالت اجرا روی LIVE_STREAM تنظیم شده باشد ResultListener N/A N/A

    داده ها را آماده کنید

    ورودی خود را به عنوان یک فایل تصویری یا یک آرایه numpy آماده کنید، سپس آن را به یک شی mediapipe.Image تبدیل کنید. اگر ورودی شما یک فایل ویدیویی یا پخش زنده از یک وب کم است، می توانید از یک کتابخانه خارجی مانند OpenCV برای بارگیری فریم های ورودی خود به عنوان آرایه های ناتوان استفاده کنید.

    تصویر

    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)
        

    وظیفه را اجرا کنید

    Gesture Recognizer از توابع شناسایی، شناسایی_برای_ویدئو و شناسائی_آسینک برای استنتاج استفاده می کند. برای تشخیص ژست، این شامل پیش پردازش داده‌های ورودی، تشخیص دست‌ها در تصویر، تشخیص نشانه‌های دست، و تشخیص حرکت دست از نشانه‌ها است.

    کد زیر نحوه اجرای پردازش با مدل وظیفه را نشان می دهد.

    تصویر

    # 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)
        

    به موارد زیر توجه کنید:

    • هنگام اجرا در حالت ویدیو یا حالت پخش زنده، باید به وظیفه تشخیص حرکت، مُهر زمانی قاب ورودی را نیز ارائه دهید.
    • هنگامی که در تصویر یا مدل ویدیو اجرا می شود، وظیفه تشخیص حرکت رشته فعلی را مسدود می کند تا زمانی که پردازش تصویر یا فریم ورودی به پایان برسد.
    • وقتی در حالت پخش زنده اجرا می‌شود، وظیفه تشخیص حرکت رشته فعلی را مسدود نمی‌کند اما بلافاصله برمی‌گردد. هر بار که پردازش یک فریم ورودی را تمام کند، شنونده نتیجه خود را با نتیجه تشخیص فراخوانی می کند. اگر زمانی که وظیفه تشخیص حرکت مشغول پردازش فریم دیگری است، تابع تشخیص فراخوانی شود، کار کادر ورودی جدید را نادیده می گیرد.

    برای مثال کامل اجرای Gesture Recognizer روی یک تصویر، برای جزئیات به مثال کد مراجعه کنید.

    کنترل و نمایش نتایج

    Gesture Recognizer یک شی نتیجه تشخیص ژست را برای هر اجرا تشخیص ایجاد می کند. شیء نتیجه شامل نشانه‌های دست در مختصات تصویر، نشانه‌های دست در مختصات جهان، دسته‌بندی دست (چپ/راست)، و حرکات دست در دست‌های شناسایی‌شده است.

    شکل زیر نمونه ای از داده های خروجی از این کار را نشان می دهد:

    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)
    

    تصاویر زیر تصویری از خروجی کار را نشان می دهد:

    کد مثال Gesture Recognizer نحوه نمایش نتایج تشخیص بازگشتی از کار را نشان می دهد، برای جزئیات به مثال کد مراجعه کنید.