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

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

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

مثال کد

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

راه‌اندازی

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

بسته‌های جاوا اسکریپت

کد Gesture Recognizer از طریق بسته NPM مدیاپایپ @mediapipe/tasks-vision در دسترس است. می‌توانید با دنبال کردن دستورالعمل‌های موجود در راهنمای راه‌اندازی پلتفرم، این کتابخانه‌ها را پیدا و دانلود کنید.

شما می‌توانید بسته‌های مورد نیاز را از طریق NPM با استفاده از دستور زیر نصب کنید:

npm install @mediapipe/tasks-vision

اگر می‌خواهید کد وظیفه را از طریق سرویس شبکه تحویل محتوا (CDN) وارد کنید، کد زیر را در تگ <head> در فایل HTML خود اضافه کنید:

<!-- You can replace JSDeliver with another CDN if you prefer to -->
<head>
  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision/vision_bundle.mjs"
    crossorigin="anonymous"></script>
</head>

مدل

وظیفه‌ی تشخیص‌دهنده‌ی اشاره‌ی MediaPipe به یک مدل آموزش‌دیده نیاز دارد که با این وظیفه سازگار باشد. برای اطلاعات بیشتر در مورد مدل‌های آموزش‌دیده‌ی موجود برای تشخیص‌دهنده‌ی اشاره، به بخش مدل‌های نمای کلی وظیفه مراجعه کنید.

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

<dev-project-root>/app/shared/models/

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

از یکی از توابع createFrom...() ‎ مربوط به Gesture Recognizer برای آماده‌سازی وظیفه جهت اجرای استنتاج‌ها استفاده کنید. از تابع createFromModelPath() ‎ به همراه یک مسیر نسبی یا مطلق به فایل مدل آموزش‌دیده استفاده کنید. اگر مدل شما از قبل در حافظه بارگذاری شده است، می‌توانید از متد createFromModelBuffer() ‎ استفاده کنید.

مثال کد زیر استفاده از تابع createFromOptions() را برای تنظیم وظیفه نشان می‌دهد. تابع createFromOptions به شما امکان می‌دهد تا Gesture Recognizer را با گزینه‌های پیکربندی سفارشی کنید. برای اطلاعات بیشتر در مورد گزینه‌های پیکربندی، به Configuration options مراجعه کنید.

کد زیر نحوه ساخت و پیکربندی وظیفه با گزینه‌های سفارشی را نشان می‌دهد:

// Create task for image file processing:
const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm "
);
const gestureRecognizer = await GestureRecognizer.createFromOptions(vision, {
  baseOptions: {
    modelAssetPath: "https://storage.googleapis.com/mediapipe-tasks/gesture_recognizer/gesture_recognizer.task"
  },
  numHands: 2
});

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

این وظیفه گزینه‌های پیکربندی زیر را برای برنامه‌های وب دارد:

نام گزینه	توضیحات	محدوده ارزش	مقدار پیش‌فرض
`runningMode`	حالت اجرا را برای وظیفه تنظیم می‌کند. دو حالت وجود دارد: تصویر: حالت ورودی‌های تک تصویر. ویدئو: حالتی برای فریم‌های رمزگشایی‌شده‌ی یک ویدئو یا روی پخش زنده‌ی داده‌های ورودی، مثلاً از یک دوربین.	{ `IMAGE, VIDEO` }	`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 باشد، تمام نتایج موجود برگردانده می‌شوند. آستانه امتیاز: امتیازی که نتایج پایین‌تر از آن رد می‌شوند. اگر روی ۰ تنظیم شود، تمام نتایج موجود بازگردانده می‌شوند. فهرست مجاز دسته‌بندی: فهرست مجاز نام‌های دسته‌بندی. اگر خالی نباشد، نتایج طبقه‌بندی که دسته‌بندی آنها در این مجموعه نباشد، فیلتر می‌شوند. با فهرست ممنوعه ناسازگار است. لیست رد دسته: لیست رد نام دسته‌ها. اگر خالی نباشد، نتایج طبقه‌بندی که دسته آنها در این مجموعه باشد، فیلتر می‌شوند. با لیست مجاز ناسازگار است.	نام‌های نمایشی، محلی: `any string` حداکثر نتایج: `any integer` آستانه امتیاز: `0.0-1.0` فهرست مجاز دسته‌بندی: `vector of strings` فهرست انکار رده: `vector of strings`	نام‌های نمایشی به زبان محلی: `"en"` حداکثر نتایج: `-1` آستانه امتیاز: `0` لیست مجاز دسته بندی: خالی لیست رد دسته بندی: خالی
`custom_gestures_classifier_options`	گزینه‌هایی برای پیکربندی رفتار طبقه‌بندی‌کننده‌ی حرکات سفارشی. زبان محلی نام‌های نمایشی: زبان محلی مورد استفاده برای نام‌های نمایشی که از طریق فراداده مدل TFLite مشخص شده‌اند، در صورت وجود. حداکثر نتایج: حداکثر تعداد نتایج طبقه‌بندی با بالاترین امتیاز برای برگرداندن. اگر < 0 باشد، تمام نتایج موجود برگردانده می‌شوند. آستانه امتیاز: امتیازی که نتایج پایین‌تر از آن رد می‌شوند. اگر روی ۰ تنظیم شود، تمام نتایج موجود بازگردانده می‌شوند. فهرست مجاز دسته‌بندی: فهرست مجاز نام‌های دسته‌بندی. اگر خالی نباشد، نتایج طبقه‌بندی که دسته‌بندی آنها در این مجموعه نباشد، فیلتر می‌شوند. با فهرست ممنوعه ناسازگار است. لیست رد دسته: لیست رد نام دسته‌ها. اگر خالی نباشد، نتایج طبقه‌بندی که دسته آنها در این مجموعه باشد، فیلتر می‌شوند. با لیست مجاز ناسازگار است.	نام‌های نمایشی، محلی: `any string` حداکثر نتایج: `any integer` آستانه امتیاز: `0.0-1.0` فهرست مجاز دسته‌بندی: `vector of strings` فهرست انکار رده: `vector of strings`	نام‌های نمایشی به زبان محلی: `"en"` حداکثر نتایج: `-1` آستانه امتیاز: `0` لیست مجاز دسته بندی: خالی لیست رد دسته بندی: خالی

آماده‌سازی داده‌ها

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

اجرای وظیفه

تشخیص‌دهنده‌ی حرکت (Gesture Recognizer) از متدهای recognize() (با حالت اجرای 'image' ) و recognizeForVideo() (با حالت اجرای 'video' ) برای ایجاد استنتاج استفاده می‌کند. این وظیفه داده‌ها را پردازش می‌کند، سعی در تشخیص حرکات دست دارد و سپس نتایج را گزارش می‌دهد.

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

تصویر

const image = document.getElementById("image") as HTMLImageElement;
const gestureRecognitionResult = gestureRecognizer.recognize(image);

ویدئو

await gestureRecognizer.setOptions({ runningMode: "video" });

let lastVideoTime = -1;
function renderLoop(): void {
  const video = document.getElementById("video");

  if (video.currentTime !== lastVideoTime) {
    const gestureRecognitionResult = gestureRecognizer.recognizeForVideo(video);
    processResult(gestureRecognitionResult);
    lastVideoTime = video.currentTime;
  }

  requestAnimationFrame(() => {
    renderLoop();
  });
}

فراخوانی متدهای recognize() و recognizeForVideo() از Gesture Recognizer به صورت همزمان اجرا می‌شوند و نخ رابط کاربری را مسدود می‌کنند. اگر شما حرکاتی را در فریم‌های ویدیویی از دوربین دستگاه تشخیص دهید، هر تشخیص، نخ اصلی را مسدود می‌کند. می‌توانید با پیاده‌سازی web workerها برای اجرای متدهای recognize() و recognizeForVideo() در نخ دیگر، از این امر جلوگیری کنید.

برای پیاده‌سازی کامل‌تر اجرای یک وظیفه‌ی Gesture Recognizer، به مثال مراجعه کنید.

مدیریت و نمایش نتایج

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

در زیر نمونه‌ای از داده‌های خروجی این وظیفه نشان داده شده است:

نتیجه‌ی GestureRecognizerResult شامل چهار مؤلفه است و هر مؤلفه یک آرایه است که در آن هر عنصر شامل نتیجه‌ی شناسایی‌شده‌ی یک دستِ شناسایی‌شده است.

چپ دستی
چپ‌دستی یا راست‌دستی نشان می‌دهد که دست‌های شناسایی‌شده، چپ‌دست هستند یا راست‌دست.
حرکات
دسته‌های ژست تشخیص داده شده از دست‌های شناسایی شده.
مکان‌های دیدنی
۲۱ نقطه عطف دست وجود دارد که هر کدام از مختصات x ، y و z تشکیل شده‌اند. مختصات x و y به ترتیب توسط عرض و ارتفاع تصویر به [۰.۰، ۱.۰] نرمال‌سازی شده‌اند. مختصات z نشان‌دهنده عمق نقطه عطف است که عمق در مچ دست مبدا آن است. هرچه مقدار کوچکتر باشد، نقطه عطف به دوربین نزدیکتر است. بزرگی z تقریباً از همان مقیاس x استفاده می‌کند.
مکان‌های دیدنی جهان
۲۱ نقطه عطف دست نیز در مختصات جهانی ارائه شده‌اند. هر نقطه عطف از 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)

تصاویر زیر، خروجی وظایف را به صورت بصری نشان می‌دهند:

دستی که شستش را به سمت بالا گرفته و ساختار اسکلتی دست نقشه برداری شده است

برای پیاده‌سازی کامل‌تر ایجاد یک وظیفه‌ی تشخیص حرکت، به مثال مراجعه کنید.