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

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

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

مثال کد

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

راه‌اندازی

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

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

کد Hand Landmarker از طریق بسته 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 Hand Landmarker به یک مدل آموزش‌دیده نیاز دارد که با این وظیفه سازگار باشد. برای اطلاعات بیشتر در مورد مدل‌های آموزش‌دیده‌ی موجود برای Hand Landmarker، به بخش مدل‌های نمای کلی وظیفه مراجعه کنید.

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

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

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

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

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

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

const vision = await FilesetResolver.forVisionTasks(
  // path/to/wasm/root
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@latest/wasm"
);
const handLandmarker = await HandLandmarker.createFromOptions(
    vision,
    {
      baseOptions: {
        modelAssetPath: "hand_landmarker.task"
      },
      numHands: 2
    });

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

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

نام گزینه	توضیحات	محدوده ارزش	مقدار پیش‌فرض
`runningMode`	حالت اجرا را برای وظیفه تنظیم می‌کند. دو حالت وجود دارد: تصویر: حالت ورودی‌های تک تصویر. ویدئو: حالتی برای فریم‌های رمزگشایی‌شده‌ی یک ویدئو یا روی پخش زنده‌ی داده‌های ورودی، مثلاً از یک دوربین.	{ `IMAGE, VIDEO` }	`IMAGE`
`numHands`	حداکثر تعداد دست‌های شناسایی‌شده توسط آشکارساز نقطه عطف دست.	`Any integer > 0`	`1`
`minHandDetectionConfidence`	حداقل امتیاز اطمینان برای تشخیص دست که در مدل تشخیص کف دست موفق تلقی می‌شود.	`0.0 - 1.0`	`0.5`
`minHandPresenceConfidence`	حداقل امتیاز اطمینان برای امتیاز حضور دست در مدل تشخیص نشانه‌های دست. در حالت ویدیو و حالت پخش زنده، اگر امتیاز اطمینان حضور دست از مدل نشانه‌های دست کمتر از این آستانه باشد، Hand Landmarker مدل تشخیص کف دست را فعال می‌کند. در غیر این صورت، یک الگوریتم ردیابی دست سبک، مکان دست(ها) را برای تشخیص‌های بعدی نشانه‌های دست تعیین می‌کند.	`0.0 - 1.0`	`0.5`
`minTrackingConfidence`	حداقل امتیاز اطمینان برای اینکه ردیابی دست موفقیت‌آمیز تلقی شود. این آستانه IoU کادر مرزی بین دست‌ها در فریم فعلی و آخرین فریم است. در حالت ویدیو و حالت پخش زنده Hand Landmarker، اگر ردیابی ناموفق باشد، Hand Landmarker تشخیص دست را آغاز می‌کند. در غیر این صورت، از تشخیص دست صرف نظر می‌کند.	`0.0 - 1.0`	`0.5`

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

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

اجرای وظیفه

تابع Hand Landmarker از متدهای detect() (با حالت اجرای image ) و detectForVideo() (با حالت اجرای video ) برای ایجاد استنتاج استفاده می‌کند. این وظیفه داده‌ها را پردازش می‌کند، سعی در تشخیص نشانه‌های دست دارد و سپس نتایج را گزارش می‌دهد.

فراخوانی متدهای detect() و detectForVideo() از تابع Hand Landmarker به صورت همزمان اجرا می‌شوند و نخ رابط کاربری را مسدود می‌کنند. اگر شما نشانه‌های دست را در فریم‌های ویدیویی از دوربین یک دستگاه تشخیص دهید، هر تشخیص، نخ اصلی را مسدود می‌کند. می‌توانید با پیاده‌سازی web workerها برای اجرای متدهای detect() و detectForVideo() در نخ دیگر، از این امر جلوگیری کنید.

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

تصویر

const image = document.getElementById("image") as HTMLImageElement;
const handLandmarkerResult = handLandmarker.detect(image);

ویدئو

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

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

  if (video.currentTime !== lastVideoTime) {
    const detections = handLandmarker.detectForVideo(video);
    processResults(detections);
    lastVideoTime = video.currentTime;
  }

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

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

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

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

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

خروجی HandLandmarkerResult شامل سه جزء است. هر جزء یک آرایه است که هر عنصر شامل نتایج زیر برای یک دست شناسایی شده است:

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

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

دستی که شستش رو به بالاست و ساختار اسکلتی دست ترسیم شده است

کد مثال Hand Landmarker نحوه نمایش نتایج برگردانده شده از کار را نشان می‌دهد، به مثال مراجعه کنید.