מדריך זיהוי של ציון דרך ל-iOS

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

בהוראות הבאות מוסבר איך להשתמש בתכונה Pose Landmarker באפליקציות ל-iOS. דוגמת הקוד שמתוארת בהוראות האלה זמינה ב-GitHub.

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

קוד לדוגמה

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

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

להורדת הקוד

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

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

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

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

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

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

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

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

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

• PoseLandmarkerService.swift: מאתחל את ה-placeholder, מטפל בבחירת המודל ומריץ הסקת מסקנות על נתוני הקלט.
• CameraViewController: הכלי שמטמיע את ממשק המשתמש של מצב הקלט של פיד המצלמה בשידור חי ומציג את ציוני הדרך באופן חזותי.
• MediaLibraryViewController.swift: הקוד הזה מטמיע את ממשק המשתמש של מצב הקלט של קובצי תמונות וסרטונים סטטיים, ומציג חזותית את ציוני הדרך.

הגדרה

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

יחסי תלות

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

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

מוסיפים את הרצף של MediaPipeTasksVision ב-Podfile באמצעות הקוד הבא:

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

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

דגם

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

משתמשים בסקריפט download_models.sh כדי להוריד את המודלים ולהוסיף אותם לספריית הפרויקט באמצעות Xcode. במאמר ניהול קבצים ותיקיות בפרויקט Xcode מוסבר איך מוסיפים קבצים לפרויקט Xcode.

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

יצירת המשימה

אפשר ליצור את המשימה Pose Landmarker על ידי קריאה לאחד מהמפעילים שלה. המאתחל PoseLandmarker(options:) מקבל ערכים של אפשרויות ההגדרה.

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

המשימה 'סימון מיקום של תנוחה' תומכת ב-3 סוגי נתוני קלט: תמונות סטילס, קובצי וידאו ושידורי וידאו חיים. כברירת מחדל, PoseLandmarker(modelPath:) מאתחלת משימה לתמונות סטילס. אם רוצים שהמשימה תאופס לעיבוד קובצי וידאו או סטרימינג של וידאו בשידור חי, צריך להשתמש ב-PoseLandmarker(options:) כדי לציין את מצב ההפעלה של הסרטון או השידור החי. כדי להשתמש במצב של שידור חי, צריך גם להגדיר את האפשרות הנוספת poseLandmarkerLiveStreamDelegate. האפשרות הזו מאפשרת ל-Pose Landmarker לשלוח את תוצאות זיהוי נקודות ציון של תנוחות לגוף לגורם המורשה באופן אסינכרוני.

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

Swift

import MediaPipeTasksVision

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .image
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .video
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

let poseLandmarker = try PoseLandmarker(options: options)
    

import MediaPipeTasksVision

// Class that conforms to the `PoseLandmarkerLiveStreamDelegate` protocol and
// implements the method that the pose landmarker calls once it finishes
// performing pose landmark detection in each input frame.
class PoseLandmarkerResultProcessor: NSObject, PoseLandmarkerLiveStreamDelegate {

  func poseLandmarker(
    _ poseLandmarker: PoseLandmarker,
    didFinishDetection result: PoseLandmarkerResult?,
    timestampInMilliseconds: Int,
    error: Error?) {

    // Process the pose landmarker result or errors here.

  }
}

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

let options = PoseLandmarkerOptions()
options.baseOptions.modelAssetPath = modelPath
options.runningMode = .liveStream
options.minPoseDetectionConfidence = minPoseDetectionConfidence
options.minPosePresenceConfidence = minPosePresenceConfidence
options.minTrackingConfidence = minTrackingConfidence
options.numPoses = numPoses

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

let poseLandmarker = try PoseLandmarker(options: options)
    

Objective-C

@import MediaPipeTasksVision;

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeImage;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeVideo;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

@import MediaPipeTasksVision;

// Class that conforms to the `MPPPoseLandmarkerLiveStreamDelegate` protocol
// and implements the method that the pose landmarker calls once it finishes
// performing pose landmarks= detection in each input frame.

@interface APPPoseLandmarkerResultProcessor : NSObject 

@end

@implementation APPPoseLandmarkerResultProcessor

-   (void)poseLandmarker:(MPPPoseLandmarker *)poseLandmarker
    didFinishDetectionWithResult:(MPPPoseLandmarkerResult *)poseLandmarkerResult
         timestampInMilliseconds:(NSInteger)timestampInMilliseconds
                           error:(NSError *)error {

    // Process the pose landmarker result or errors here.

}

@end

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

MPPPoseLandmarkerOptions *options = [[MPPPoseLandmarkerOptions alloc] init];
options.baseOptions.modelAssetPath = modelPath;
options.runningMode = MPPRunningModeLiveStream;
options.minPoseDetectionConfidence = minPoseDetectionConfidence;
options.minPosePresenceConfidence = minPosePresenceConfidence;
options.minTrackingConfidence = minTrackingConfidence;
options.numPoses = numPoses;

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

MPPPoseLandmarker *poseLandmarker =
  [[MPPPoseLandmarker alloc] initWithOptions:options error:nil];
    

הערה: אם אתם משתמשים במצב וידאו או במצב שידור חי, התכונה Pose Landmarker משתמשת במעקב כדי למנוע הפעלה של מודל זיהוי כף היד בכל פריים, וכך עוזרת לצמצם את זמן האחזור.

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

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

הגדרת שידור חי

כשמגדירים את מצב ההפעלה כשידור חי, צריך להגדיר את אפשרות ההגדרה הנוספת poseLandmarkerLiveStreamDelegate ב-Pose Landmarker כדי לאפשר ל-Pose Landmarker לספק תוצאות של זיהוי נקודות ציון של תנוחות באופן אסינכרוני. הנציג צריך להטמיע את השיטה poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:), שנקראת על ידי ה-Pose Landmarker אחרי עיבוד התוצאות של זיהוי ציוני הדרך של התנוחה בכל פריים.

הכנת נתונים

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

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

UIImage

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

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

CVPixelBuffer

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

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

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

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

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

// 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.

הרצת המשימה

כדי להריץ את ציון הדרך של Pose, משתמשים ב-method detect() הספציפית למצב הריצה שהוקצה:

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

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

Swift

let result = try poseLandmarker.detect(image: image)
    

let result = try poseLandmarker.detect(
  videoFrame: image,
  timestampInMilliseconds: timestamp)
    

try poseLandmarker.detectAsync(
  image: image,
  timestampInMilliseconds: timestamp)
    

Objective-C

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectImage:image error:nil];
    

MPPPoseLandmarkerResult *result =
  [poseLandmarker detectVideoFrame:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

BOOL success =
  [poseLandmarker detectAsyncImage:image
           timestampInMilliseconds:timestamp
                             error:nil];
    

בדוגמה לקוד של Pose Landmarker מפורטות בפירוט רב יותר ההטמעות של כל אחד מהמצבים האלה: detect(image:),‏ detect(videoFrame:timestampInMilliseconds:) ו-detectAsync(image:timestampInMilliseconds:). הקוד לדוגמה מאפשר למשתמש לעבור בין מצבי עיבוד, שיכול להיות שלא נדרשים לתרחיש לדוגמה.

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

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

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

• כשהיא פועלת במצב של שידור חי, המשימה Pose Landmarker מחזירה תשובה באופן מיידי ולא חוסמת את השרשור הנוכחי. הוא מפעיל את השיטה poseLandmarker(_:didFinishDetection:timestampInMilliseconds:error:) עם התוצאה של זיהי הנקודות של התנוחה אחרי עיבוד כל מסגרת קלט. ה-Pose Landmarker מפעיל את השיטה הזו באופן אסינכרוני בתור שליחה טורית ייעודי. כדי להציג את התוצאות בממשק המשתמש, שולחים את התוצאות לתור הראשי אחרי העיבוד שלהן. אם הפונקציה detectAsync נקראת בזמן שהמשימה Pose Landmarker עסוקה בעיבוד של פריים אחר, המערכת של Pose Landmarker תתעלם מפריים הקלט החדש.

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

לאחר הפעלת ההסקה, המשימה Pose Landmarker מחזירה PoseLandmarkerResult שמכיל את הקואורדינטות של כל ציון דרך של תנוחה.

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

PoseLandmarkerResult:
  Landmarks:
    Landmark #0:
      x            : 0.638852
      y            : 0.671197
      z            : 0.129959
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.634599
      y            : 0.536441
      z            : -0.06984
      visibility   : 0.999909
      presence     : 0.999958
    ... (33 landmarks per pose)
  WorldLandmarks:
    Landmark #0:
      x            : 0.067485
      y            : 0.031084
      z            : 0.055223
      visibility   : 0.9999997615814209
      presence     : 0.9999984502792358
    Landmark #1:
      x            : 0.063209
      y            : -0.00382
      z            : 0.020920
      visibility   : 0.999976
      presence     : 0.999998
    ... (33 world landmarks per pose)
  SegmentationMasks:
    ... (pictured below)

הפלט מכיל גם קואורדינטות רגילות (Landmarks) וגם קואורדינטות בעולם (WorldLandmarks) לכל ציון דרך.

הפלט מכיל את הקואורדינטות המנורמלות הבאות (Landmarks):

• x ו-y: קואורדינטות של ציון דרך שמותאמות לטווח שבין 0.0 ל-1.0 לפי רוחב התמונה (x) וגובה התמונה (y).

• z: עומק ציון הדרך, כאשר נקודת המוצא היא העומק בנקודת האמצע של הירכיים. ככל שהערך קטן יותר, כך ציון הדרך קרוב יותר למצלמה. הערך של z משתמש בערך באותו סולם כמו x.

• visibility: הסבירות שהציון הגיאוגרפי יהיה גלוי בתמונה.

הפלט מכיל את קואורדינטות העולם הבאות (WorldLandmarks):

• x, y ו-z: קואורדינטות תלת-ממדיות בעולם האמיתי במטרים, כשנקודת האמצע של הירכיים היא המקור.

• visibility: הסבירות שהציון הגיאוגרפי יהיה גלוי בתמונה.

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

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

הקוד לדוגמה של Pose Landmarker מראה איך להציג את התוצאות של Pose Landmarker.