נקודת הקצה הישנה ב-ARCore Cloud anchor API הוצאה משימוש ולא תהיה תמיכה בה אחרי 31 באוגוסט 2023. אם האפליקציה שלכם משתמשת ב-API הזה, תצטרכו לעדכן אותו כדי שייעשה שימוש בנקודת הקצה החדשה של הענן של ARCore API בהקדם האפשרי.

דף זה תורגם על ידי Cloud Translation API.

מדריך למפתחים של Cloud anchors ל-iOS

ה-SDK של ARCore ל-iOS מתחבר ל-ARKit כדי לספק יכולות של Cloud Anchor, ומאפשר לכם לשתף עוגנים בין מכשירים עם iOS ומכשירים עם Android באותה סביבה.

מידע על השימוש ב-ARCore Cloud Anchor API או ב-שירות ARCore Cloud Anchor באפליקציות שלכם.

דרישות מוקדמות

Xcode מגרסה 13.0 ואילך
Cocoapods מגרסה 1.4.0 ואילך, אם משתמשים ב-Cocoapods
מכשיר Apple תואם ARKit עם iOS מגרסה 12.0 ואילך (נדרש יעד פריסה עם iOS מגרסה 12.0 ואילך)

אם זו הפעם הראשונה שאתם משתמשים ב-Cloud Anchors:

חשוב להבין את התהליך שבו מארחים ומפנים לאובייקט Cloud Anchor.
כדאי לקרוא את מדריך למתחילים כדי לקבל מידע על דרישות המערכת, ההגדרה וההוראות להתקנה.
כדאי לעיין בדוגמאות ל-Cloud Anchor.

הפעלת Cloud Anchors באפליקציה

כדי להשתמש ב-API של Cloud Anchors, צריך ליצור GARSessionConfiguration ולהגדיר לו את המאפיין cloudAnchorMode, כפי שמתואר במאמר הגדרת סשן ARCore ב-iOS. משתמשים בפקודה setConfiguration:error: (GARSession) כדי להגדיר את ההגדרות.

צריך גם להפעיל את ARCore API באפליקציה.

אירוח ופתרונות של מודעות עוגן

אפשר לארח ולפתור עוגנים בענן באמצעות ARCore Cloud Anchor API. ה-API כולל שיטות קריאה חוזרת (callbacks) לפעולות שהושלמו, וכן אובייקטים מסוג Future שאפשר לדגום אותם.

אירוח עוגן

אירוח של ARAnchor מעביר את הצ'אנק למערכת קואורדינטות משותפת לכל מרחב פיזי נתון.

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

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];

  __weak ExampleViewController *weakSelf = self;
  self.hostFuture = [self.cloudAnchorManager
      hostCloudAnchor:self.arAnchor
           completion:^(NSString *anchorId, GARCloudAnchorState cloudState) {
             [weakSelf handleHostAnchor:anchorId cloudState:cloudState];
           }
                error:nil];
  [self enterState:HelloARStateHosting];
}

פתרון של עוגן

פתרון ARAnchor מאפשר למכשירי Android ו-iOS במרחב פיזי מסוים להוסיף אנקורים שהתארחו בעבר לסצנות חדשות.

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

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  GARResolveCloudAnchorFuture *garFuture =
      [self.gSession resolveCloudAnchorWithIdentifier:identifier
                                    completionHandler:completion
                                                error:&error];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be in the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

דפוס סקירה `GARSession` אופציונלי

אם אתם משתמשים ב-Metal או אם אתם צריכים אפשרות של סקרים, וגם האפליקציה שלכם פועלת במהירות של 30fps לפחות, תוכלו להשתמש בתבנית הבאה כדי להעביר ARFrames ל-GARSession:

-(void)myOwnPersonalUpdateMethod {
  ARFrame *arFrame = arSession.currentFrame;
  NSError *error = nil;
  GARFrame *garFrame = [garSession update:arFrame error:&error];
  // your update code here
}

מכסות ל-API

לממשק ARCore API יש את המכסות הבאות לרוחב הפס של הבקשות:

סוג המכסה	מקסימום	משך	חל על
מספר עוגנים	ללא הגבלה	לא רלוונטי	פרויקט
בקשות של מארחים של מודעות עוגן	30	דקה	כתובת IP ופרויקט
בקשות resolve של עוגנים	300	דקה	כתובת IP ופרויקט

בעיות ידועות ופתרונות עקיפים

יש כמה בעיות ידועות בעבודה עם ARCore SDK ל-iOS.

הגדרות ברירת המחדל של הסכימה גורמות לקריסה לסירוגין של האפליקציה

הגדרות התוכנית של צילום הפריימים ב-GPU ושל אימות Metal API מופעלות כברירת מחדל, ולפעמים הן עלולות לגרום לקריסת האפליקציה ב-SDK.

אבחון קריסה של אפליקציה

בכל פעם שאתם חושדים שהתרחשה קריסה, כדאי לבדוק את נתיב הסטאק. אם הערך MTLDebugComputeCommandEncoder מופיע ב-stack trace, סביר להניח שזה בגלל הגדרות ברירת המחדל של הסכימה.

פתרון אפשרי

לעבור אל Product > Scheme > Edit Scheme….
פותחים את הכרטיסייה Run.
לוחצים על Options כדי להציג את ההגדרות הנוכחיות.
מוודאים שגם GPU Frame Capture וגם Metal API Validation מושבתים.
יוצרים את האפליקציה ומריצים אותה.

בעיות מוכרות נוספות מפורטות ב-CHANGELOG של Cocoapods.

מגבלות

ה-SDK של ARCore ל-iOS לא תומך בקריאה לשיטה setWorldOrigin(relativeTransform:) של ARKit.

שיקולי ביצועים

השימוש בזיכרון גדל כשמפעילים את ARCore API. צריכת הסוללה של המכשיר צפויה לעלות עקב שימוש מוגבר ברשת ושימוש מוגבר במעבד.

השלבים הבאים

חומר עזר בנושא ARCore ל-iOS