מדריך לזיהוי תנועות ל-iOS

המשימה MediaPipe Gesture Recognizer מאפשרת לזהות תנועות ידיים בזמן אמת, ומספקת את התוצאות של תנועות היד שזוהו ואת נקודות הציון של הידיים שזוהו. בהוראות הבאות מוסבר איך להשתמש בזיהוי התנועות באפליקציות ל-iOS.

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

קוד לדוגמה

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

אפשר להשתמש באפליקציה כנקודת התחלה לאפליקציית iOS משלכם, או להיעזר בה כשמשנים אפליקציה קיימת. קוד הדוגמה של Gesture Recognizer מתארח ב-GitHub.

מורידים את הקוד

בהוראות הבאות מוסבר איך ליצור עותק מקומי של קוד הדוגמה באמצעות כלי שורת הפקודה git.

כדי להוריד את הקוד לדוגמה:

1. משכפלים את מאגר git באמצעות הפקודה הבאה:

   git clone https://github.com/google-ai-edge/mediapipe-samples
   

2. אפשר גם להגדיר את מכונה של git כך שתשתמש ב-sparse checkout, כך שיישארו רק הקבצים של אפליקציית הדוגמה לזיהוי תנועות:

   cd mediapipe-samples
   git sparse-checkout init --cone
   git sparse-checkout set examples/gesture_recognizer/ios/
   

אחרי שיוצרים גרסה מקומית של קוד הדוגמה, אפשר להתקין את ספריית המשימות של MediaPipe, לפתוח את הפרויקט באמצעות Xcode ולהפעיל את האפליקציה. להוראות, אפשר לעיין במדריך ההגדרה ל-iOS.

רכיבים מרכזיים

הקבצים הבאים מכילים את הקוד החשוב לאפליקציית הדוגמה של Gesture Recognizer:

• GestureRecognizerService.swift: הפונקציה הזו מפעילה את ה-Gesture Recognizer, מטפלת בבחירת המודל ומריצה הסקת מסקנות על נתוני הקלט.
• CameraViewController.swift: הטמעת ממשק המשתמש של מצב הקלט של הפיד בשידור חי מהמצלמה, והצגת התוצאות באופן חזותי.
• MediaLibraryViewController.swift: הטמעת ממשק המשתמש למצב הקלט של קובצי תמונות סטילס וקובצי וידאו, והצגת התוצאות באופן חזותי.

הגדרה

בקטע הזה מתוארים השלבים העיקריים להגדרת סביבת הפיתוח ופרויקטי הקוד לשימוש ב-Gesture Recognizer. מידע כללי על הגדרת סביבת הפיתוח לשימוש במשימות של MediaPipe, כולל דרישות לגבי גרסת הפלטפורמה, זמין במדריך ההגדרה ל-iOS.

יחסי תלות

הספרייה MediaPipeTasksVision משמשת לזיהוי תנועות, וצריך להתקין אותה באמצעות CocoaPods. הספרייה תואמת לאפליקציות Swift וגם לאפליקציות Objective-C, ולא נדרשת הגדרה נוספת ספציפית לשפה.

הוראות להתקנת CocoaPods ב-macOS מפורטות במדריך להתקנת CocoaPods. הוראות ליצירת Podfile עם ה-pods הנדרשים לאפליקציה מפורטות במאמר שימוש ב-CocoaPods.

מוסיפים את ה-pod MediaPipeTasksVision ב-Podfile באמצעות הקוד הבא:

target 'MyGestureRecognizerApp' do
  use_frameworks!
  pod 'MediaPipeTasksVision'
end

אם האפליקציה כוללת יעדי בדיקת יחידה, תוכלו לעיין במדריך ההגדרה ל-iOS כדי לקבל מידע נוסף על הגדרת Podfile.

דגם

כדי לבצע את המשימה 'זיהוי תנועות' ב-MediaPipe, נדרש מודל מאומן שתואמת למשימה הזו. מידע נוסף על המודלים המאומנים הזמינים לזיהוי תנועות מפורט בקטע 'מודלים' שבסקירה הכללית של המשימה.

בוחרים מודל ומורידים אותו, ומוסיפים אותו לספריית הפרויקט באמצעות Xcode. הוראות להוספת קבצים לפרויקט ב-Xcode מפורטות במאמר ניהול קבצים ותיקיות בפרויקט ב-Xcode.

משתמשים במאפיין BaseOptions.modelAssetPath כדי לציין את הנתיב למודל בקובץ האפליקציה. דוגמה לקוד מופיעה בקטע הבא.

יצירת המשימה

אפשר ליצור את המשימה Gesture Recognizer על ידי קריאה לאחת מהפונקציות להפעלה שלה. ה-initializer של GestureRecognizer(options:) מקבל ערכים לאפשרויות ההגדרה.

אם אתם לא צריכים לזהות תנועות שתואמת לאפשרויות ההגדרה בהתאמה אישית, תוכלו להשתמש ב-GestureRecognizer(modelPath:) initializer כדי ליצור לזהות תנועות עם אפשרויות ברירת המחדל. מידע נוסף על אפשרויות ההגדרה זמין במאמר סקירה כללית על הגדרות.

המשימה 'זיהוי תנועות' תומכת ב-3 סוגי נתוני קלט: תמונות סטילס, קובצי וידאו ושידורי וידאו חיים. כברירת מחדל, GestureRecognizer(modelPath:) מאתחלת משימה לתמונות סטילס. אם רוצים שהמשימה תאופס לעיבוד קובצי וידאו או סטרימינג של וידאו בשידור חי, צריך להשתמש ב-GestureRecognizer(options:) כדי לציין את מצב ההפעלה של הסרטון או השידור החי. כדי להשתמש במצב של שידור חי, צריך גם להגדיר את האפשרות הנוספת gestureRecognizerLiveStreamDelegate, שמאפשרת ל-Gesture Recognizer לשלוח את תוצאות זיהוי התנועות למשתמש המורשה באופן אסינכרוני.

בוחרים את הכרטיסייה שמתאימה למצב ההפעלה כדי לראות איך יוצרים את המשימה ומפעילים את ההסקה.

Swift

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "gesture_recognizer",
                                      ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

let modelPath = Bundle.main.path(forResource: "gesture_recognizer",
                                      ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

let gestureRecognizer = try GestureRecognizer(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `GestureRecognizerLiveStreamDelegate` protocol and
// implements the method that the gesture recognizer calls once it finishes
// performing recognizing hand gestures in each input frame.
class GestureRecognizerResultProcessor: NSObject, GestureRecognizerLiveStreamDelegate {

  func gestureRecognizer(
    _ gestureRecognizer: GestureRecognizer,
    didFinishRecognition result: GestureRecognizerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the gesture recognizer result or errors here.

  }
}

let modelPath = Bundle.main.path(
  forResource: "gesture_recognizer",
  ofType: "task")

let options = GestureRecognizerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

// Assign an object of the class to the `gestureRecognizerLiveStreamDelegate`
// property.
let processor = GestureRecognizerResultProcessor()
options.gestureRecognizerLiveStreamDelegate = processor

let gestureRecognizer = try GestureRecognizer(options: options)
    

Objective-C

@import MediaPipeTasksVision;

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPGestureRecognizerLiveStreamDelegate` protocol
// and implements the method that the gesture recognizer calls once it finishes
// performing gesture recognition on each input frame.

@interface APPGestureRecognizerResultProcessor : NSObject 

@end

@implementation APPGestureRecognizerResultProcessor

-   (void)gestureRecognizer:(MPPGestureRecognizer *)gestureRecognizer
    didFinishRecognitionWithResult:(MPPGestureRecognizerResult *)gestureRecognizerResult
           timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                             error:(NSError *)error {

    // Process the gesture recognizer result or errors here.

}

@end

NSString *modelPath =
  [[NSBundle mainBundle] pathForResource:@"gesture_recognizer"
                                  ofType:@"task"];

MPPGestureRecognizerOptions *options =
  [[MPPGestureRecognizerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minHandDetectionConfidence = minHandDetectionConfidence
options.minHandPresenceConfidence = minHandPresenceConfidence
options.minTrackingConfidence = minHandTrackingConfidence
options.numHands = numHands

// Assign an object of the class to the `gestureRecognizerLiveStreamDelegate`
// property.
APPGestureRecognizerResultProcessor *processor =
  [APPGestureRecognizerResultProcessor new];
options.gestureRecognizerLiveStreamDelegate = processor;

MPPGestureRecognizer *gestureRecognizer =
      [[MPPGestureRecognizer alloc] initWithOptions:options error:nil];
    

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

למשימה הזו יש את אפשרויות התצורה הבאות לאפליקציות ל-iOS:

כשמגדירים את מצב ההפעלה לשידור חי, נדרש ל-Gesture Recognizer להגדיר את האפשרות הנוספת gestureRecognizerLiveStreamDelegate, שמאפשרת ל-Gesture Recognizer לספק תוצאות של זיהוי תנועות באופן אסינכרוני. הנציג צריך להטמיע את השיטה gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:), שנקראת על ידי Gesture Recognizer אחרי עיבוד התוצאות של זיהוי התנועות בכל פריים.

הכנת הנתונים

צריך להמיר את התמונה או את המסגרת של הקלט לאובייקט MPImage לפני שמעבירים אותו ל-Gesture Recognizer. MPImage תומך בסוגים שונים של פורמטים של תמונות ב-iOS, וניתן להשתמש בהם בכל מצב ריצה לצורך הסקת מסקנות. למידע נוסף על MPImage, אפשר לעיין במאמר MPImage API.

בוחרים את פורמט התמונה ל-iOS בהתאם לתרחיש לדוגמה ולמצב ההפעלה שנדרש לאפליקציה.MPImage תומך בפורמטים של תמונות ל-iOS‏ UIImage,‏ CVPixelBuffer ו-CMSampleBuffer.

UIImage

הפורמט UIImage מתאים במיוחד למצבי ההפעלה הבאים:

• תמונות: אפשר להמיר תמונות מחבילת אפליקציות, מגלריית משתמשים או ממערכת קבצים בפורמט UIImage לאובייקט MPImage.

• סרטונים: משתמשים ב-AVAssetImageGenerator כדי לחלץ פריימים של סרטונים לפורמט CGImage, ואז ממירים אותם לתמונות UIImage.

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(uiImage: image)
    

// Load an image on the user's device as an iOS `UIImage` object.

// Convert the `UIImage` object to a MediaPipe's Image object having the default
// orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

בדוגמה מתבצעת אתחול של MPImage עם כיוון ברירת המחדל UIImage.Orientation.Up. אפשר לאתחל את MPImage עם כל אחד מהערכים הנתמכים של UIImage.Orientation. מערכת זיהוי התנועות לא תומכת בכיוונים מוחזרים כמו .upMirrored,‏ .downMirrored, ‏ .leftMirrored, ‏ .rightMirrored.

מידע נוסף על UIImage זמין במסמכי התיעוד למפתחים של Apple בנושא UIImage.

CVPixelBuffer

הפורמט CVPixelBuffer מתאים לאפליקציות שיוצרות פריימים ומשתמשות במסגרת CoreImage של iOS לעיבוד.

הפורמט CVPixelBuffer מתאים במיוחד למצבי ההפעלה הבאים:

• תמונות: אפליקציות שיוצרות תמונות CVPixelBuffer אחרי עיבוד מסוים באמצעות מסגרת CoreImage של iOS יכולות לשלוח את התמונות לזיהוי התנועות במצב 'הפעלת תמונה'.

• סרטונים: אפשר להמיר את הפריימים של הסרטון לפורמט CVPixelBuffer לצורך עיבוד, ואז לשלוח אותם לזיהוי התנועות במצב וידאו.

• שידור חי: יכול להיות שאפליקציות שמשתמשות במצלמת iOS כדי ליצור פריימים יומרו לפורמט CVPixelBuffer לצורך עיבוד לפני שהן נשלחות לזיהוי התנועות במצב של שידור חי.

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(pixelBuffer: pixelBuffer)
    

// Obtain a CVPixelBuffer.

// Convert the `CVPixelBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithUIImage:image error:nil];
    

מידע נוסף על CVPixelBuffer זמין במסמכי התיעוד למפתחים של Apple בנושא CVPixelBuffer.

CMSampleBuffer

בפורמט CMSampleBuffer מאוחסנות דגימות מדיה מסוג מדיה אחיד, והוא מתאים במיוחד למצב ההפעלה של שידור חי. פריימים בשידור חי ממצלמות iOS מועברים באופן אסינכרוני בפורמט CMSampleBuffer על ידי AVCaptureVideoDataOutput של iOS.

// Obtain a CMSampleBuffer.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the default
// orientation `UIImage.Orientation.up`.
let image = try MPImage(sampleBuffer: sampleBuffer)
    

// Obtain a `CMSampleBuffer`.

// Convert the `CMSampleBuffer` object to a MediaPipe's Image object having the
// default orientation `UIImageOrientationUp`.
MPImage *image = [[MPPImage alloc] initWithSampleBuffer:sampleBuffer error:nil];
    

מידע נוסף על CMSampleBuffer זמין במסמכי העזרה למפתחים של Apple בנושא CMSampleBuffer.

הרצת המשימה

כדי להפעיל את ה-Gesture Recognizer, משתמשים בשיטה recognize() שספציפית למצב ההפעלה שהוקצה:

• תמונה סטטית: recognize(image:)
• סרטון: recognize(videoFrame:timestampInMilliseconds:)
• צפייה בשידור חי: recognizeAsync(image:timestampInMilliseconds:)

בדוגמאות הקוד הבאות מפורטות דוגמאות בסיסיות להפעלת Gesture Recognizer במצבי ההפעלה השונים:

Swift

let result = try gestureRecognizer.recognize(image: image)
    

let result = try gestureRecognizer.recognize(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try gestureRecognizer.recognizeAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

  MPPGestureRecognizerResult *result =
    [gestureRecognizer recognizeImage:mppImage
                                error:nil];
    

MPPGestureRecognizerResult *result =
  [gestureRecognizer recognizeVideoFrame:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

BOOL success =
  [gestureRecognizer recognizeAsyncImage:image
                 timestampInMilliseconds:timestamp
                                   error:nil];
    

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

שימו לב לנקודות הבאות:

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

• כשהיא פועלת במצב תמונה או סרטון, המשימה 'זיהוי תנועות' חוסמת את השרשור הנוכחי עד שהיא מסיימת לעבד את התמונה או את הפריים של הקלט. כדי למנוע חסימה של השרשור הנוכחי, צריך להריץ את העיבוד בשרשור רקע באמצעות מסגרות ה-iOS Dispatch או NSOperation.

• כשהיא פועלת במצב של שידור חי, המשימה של זיהוי התנועות חוזרת מיד ולא חוסמת את השרשור הנוכחי. הוא מפעיל את השיטה gestureRecognizer(_:didFinishRecognition:timestampInMilliseconds:error:) עם תוצאת זיהוי התנועות אחרי עיבוד כל פריים של הקלט. ה-Gesture Recognizer מפעיל את השיטה הזו באופן אסינכרוני בתור ייעודי לניתוב רצפי. כדי להציג את התוצאות בממשק המשתמש, צריך לשלוח את התוצאות לתור הראשי אחרי העיבוד שלהן. אם הפונקציה recognizeAsync נקראת בזמן שהמשימה של זיהוי התנועות עסוקה בעיבוד של פריים אחר, זיהוי התנועות מתעלם מפריים הקלט החדש.

טיפול בתוצאות והצגתן

לאחר הפעלת ההסקה, המשימה 'זיהוי תנועות' מחזירה את הערך GestureRecognizerResult שמכיל ציוני דרך של היד בקואורדינטות של התמונה, ציוני דרך של היד בקואורדינטות עולמיות, צד היד(יד ימין/יד שמאל) וקטגוריות של תנועות היד של הידיים שזוהו.

בהמשך מוצגת דוגמה לנתוני הפלט של המשימה הזו:

הערך שמתקבל ב-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)

בתמונות הבאות מוצגת תצוגה חזותית של הפלט של המשימה: