מדריך לזיהוי יד של ציוני דרך באינטרנט

המשימה MediaPipe Hand Landmarker מאפשרת לזהות את נקודות הציון של הידיים בתמונה. בהוראות האלה נסביר איך להשתמש ב-Hand Landmarker באפליקציות אינטרנט ובאפליקציות JavaScript.

מידע נוסף על היכולות, המודלים ואפשרויות ההגדרה של המשימה הזו זמין במאמר סקירה כללית.

קוד לדוגמה

קוד לדוגמה של Hand Landmarker מספק הטמעה מלאה של המשימה הזו ב-JavaScript לעיונכם. הקוד הזה עוזר לכם לבדוק את המשימה הזו ולהתחיל ליצור אפליקציה משלכם לזיהוי נקודות ציון של הידיים. אתם יכולים להציג, להריץ ולערוך את הדוגמה של Hand Landmarker באמצעות דפדפן האינטרנט בלבד.

הגדרה

בקטע הזה מתוארים השלבים העיקריים להגדרת סביבת הפיתוח במיוחד לשימוש ב-Hand Landmarker. מידע כללי על הגדרת סביבת הפיתוח לאתרים ול-JavaScript, כולל דרישות לגבי גרסת הפלטפורמה, זמין במדריך ההגדרה לאתרים.

חבילות JavaScript

קוד ה-Hand Landmarker זמין דרך חבילת ה-@mediapipe/tasks-vision NPM של MediaPipe. אפשר למצוא ולהוריד את הספריות האלה לפי ההוראות במדריך ההגדרה של הפלטפורמה.

אפשר להתקין את החבילות הנדרשות דרך 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, צריך מודל מאומן שתואם למשימה הזו. מידע נוסף על מודלים מאומנים זמינים לזיהוי נקודות ציון ביד זמין בקטע 'מודלים' בסקירה הכללית של המשימה.

בוחרים מודל, מורידים אותו ושומרים אותו בספריית הפרויקט:

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

יצירת המשימה

משתמשים באחת מהפונקציות של Hand Landmarker createFrom...() כדי להכין את המשימה להפעלת מסקנות. משתמשים בפונקציה createFromModelPath() עם נתיב יחסי או מוחלט לקובץ המודל שעבר אימון. אם המודל כבר נטען לזיכרון, אפשר להשתמש בשיטה createFromModelBuffer().

בדוגמת הקוד הבאה מוצג שימוש בפונקציה createFromOptions() כדי להגדיר את המשימה. הפונקציה createFromOptions מאפשרת לכם להתאים אישית את Hand Landmarker באמצעות אפשרויות הגדרה. מידע נוסף על אפשרויות ההגדרה זמין במאמר אפשרויות הגדרה.

בדוגמת הקוד הבאה אפשר לראות איך יוצרים ומגדירים את המשימה עם אפשרויות מותאמות אישית:

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
    });

אפשרויות הגדרה

במשימה הזו יש את אפשרויות ההגדרה הבאות לאפליקציות אינטרנט ולאפליקציות JavaScript:

שם האפשרות תיאור טווח ערכים ערך ברירת מחדל
runningMode הגדרת מצב ההפעלה של המשימה. יש שני מצבים:

IMAGE: המצב לקלט של תמונה אחת.

‫VIDEO: המצב של פריים מפוענח של סרטון או של שידור חי של נתוני קלט, כמו ממצלמה.		 {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) כדי להפעיל הסקות. הנתונים עוברים עיבוד במשימה, המערכת מנסה לזהות נקודות ציון של הידיים ואז מדווחת על התוצאות.

הקריאות לשיטות Hand Landmarker‏ detect() ו-detectForVideo() מופעלות באופן סינכרוני וחוסמות את השרשור של ממשק המשתמש. אם מזהים נקודות ציון של הידיים בפריים של סרטון מהמצלמה של המכשיר, כל זיהוי חוסם את השרשור הראשי. כדי למנוע את זה, אפשר להטמיע web workers כדי להריץ את השיטות 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 מכיל שלושה רכיבים. כל רכיב הוא מערך, שכל אלמנט בו מכיל את התוצאות הבאות לגבי יד אחת שזוהתה:

  • יד דומיננטית

    היד הדומיננטית מייצגת אם הידיים שזוהו הן יד שמאל או יד ימין.

  • ציוני דרך

    יש 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)

בתמונה הבאה אפשר לראות הדמיה של פלט המשימה:

יד בתנועת אגודל למעלה עם מבנה השלד של היד

בדוגמה של קוד לזיהוי מיקום היד אפשר לראות איך להציג את התוצאות שמוחזרות מהמשימה. כאן אפשר לראות דוגמה.