מדריך לזיהוי תנועות ל-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 למכונת ה-Git כך שיעשה שימוש בקופה מצומצם, כך שיהיו לכם רק את הקבצים של האפליקציה לדוגמה של זיהוי התנועות:

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

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

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

הקבצים הבאים מכילים את הקוד החיוני לאפליקציה לדוגמה של הכלי לזיהוי תנועות:

• GestureRecognizerService.swift: הפעלת הכלי לזיהוי תנועות, טיפול בבחירת המודל והסקת מסקנות על נתוני הקלט.
• 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:)

דוגמאות הקוד הבאות מראות דוגמאות בסיסיות להרצה של הכלי לזיהוי תנועות במצבי הריצה השונים:

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

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