המדריך למפתחים של Cloud anchors ל-Unity (AR Foundation)

איך משתמשים ב-Cloud Anchors באפליקציות שלכם

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

לפני שממשיכים, חשוב להבין את המושגים הבסיסיים של AR ואת האופן שבו מגדירים סשן ARCore.

אם אתם משתמשים חדשים ב-Cloud Anchors, חשוב להבין איך פועלים עוגנים וCloud Anchors.

הפעלת ה-API של ARCore

לפני שמשתמשים ב-Cloud Anchors באפליקציה, צריך להפעיל את ARCore API באפליקציה.

הפעלת היכולות של Cloud Anchor בהגדרות הסשן

אחרי שמפעילים את הפונקציונליות של Cloud Anchors באפליקציה, מפעילים את היכולות של Cloud Anchors בהגדרת סשן ה-AR של האפליקציה כדי שתהיה לה אפשרות לתקשר עם ARCore API:

אירוח של Cloud Anchor

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

אפשר גם להאריך את משך החיים של ציר מארחת באמצעות ARCore Cloud Anchor Management API.

כדי לארח Cloud Anchor, האפליקציה צריכה לפעול לפי השלבים הבאים:

  1. קוראים לפונקציה ARAnchorManager.HostCloudAnchorAsync().
  2. מפעילים פונקציית קורוטין כדי להמתין עד שה-Promise יניב תוצאה. מידע נוסף זמין במאמר פונקציות רפיטציה (Coroutines) ב-Unity.
  3. בודקים את סטטוס התוצאה כדי לקבוע אם הפעולה הצליחה, או מפרשים את קוד השגיאה אם היא נכשלה.
  4. משתפים את מזהה Cloud Anchor שהתקבל עם לקוחות אחרים, ומשתמשים בו כדי לפתור את Cloud Anchor באמצעות ARAnchorManagerExtensions.ResolveCloudAnchorAsync().

בדיקת איכות המיפוי של נקודות המאפיינים

הערך ARCoreExtensions.FeatureMapQuality מציין את האיכות של נקודות המאפיינים ש-ARCore זיהתה בשניות האחרונות מתנוחת מצלמה מסוימת. בדרך כלל, פתרון של Cloud Anchors שמתארחים באמצעות תכונות באיכות גבוהה יותר מדויק יותר. משתמשים ב-ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() כדי לקבל אומדן של איכות מפת המאפיינים לתנוחת מצלמה נתונה.

ערך תיאור
Insufficient האיכות של נקודות המאפיינים שזוהו מהתנוחה בשניות הקודמות נמוכה. המצב הזה מציין של-ARCore יהיה קשה יותר לפתור את Cloud Anchor. מומלץ לעודד את המשתמש להזיז את המכשיר כדי שאפשר יהיה לראות את המיקום הרצוי של ציר ה-Cloud Anchor שהוא רוצה לארח מזוויות שונות.
Sufficient סביר להניח שאיכות נקודות המאפיינים שזוהו מהתנוחה בשניות הקודמות מספיקה ל-ARCore כדי לפתור בהצלחה עוגן בענן, אם כי סביר להניח שהדיוק של תנוחת הפתרון יהיה נמוך יותר. מומלץ לעודד את המשתמש להזיז את המכשיר כדי שאפשר יהיה לראות את המיקום הרצוי של ציר ה-Cloud Anchor שהוא רוצה לארח מזוויות שונות.
Good סביר להניח שאיכות נקודות המאפיינים שזוהו מהתנוחה בשניות הקודמות מספיקה ל-ARCore כדי לפתור בהצלחה עוגן בענן ברמת דיוק גבוהה.

פתרון של עוגן שקודם לכן היה מארח

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

אפשר להתחיל פתרון של כמה Cloud Anchors ברצף. אפשר להריץ בו-זמנית עד 40 פעולות של Cloud Anchor.

ביטול פעולה או הסרה של Cloud Anchor

הפונקציה ARCloudAnchor.OnDestroy() נקראת באופן אוטומטי כשרכיב ARCloudAnchor מוסר מאובייקט המשחק שמכיל אותו. הפעולה הזו תנתק ותשחרר את האובייקט המקורי של Cloud Anchor.

בדיקת מצב התוצאה של פעולת Cloud Anchor

אפשר להשתמש ב-CloudAnchorState כדי לבדוק את סטטוס התוצאה של פעולת האירוח או הפתרון, כולל שגיאות.

ערך תיאור
ErrorResolvingCloudIdNotFound הפתרון נכשל כי ARCore API לא הצליח למצוא את מזהה Cloud Anchor שצוין.
ErrorHostingDatasetProcessingFailed האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים של הצ'אנק הנתון. נסו שוב אחרי שהמכשיר יאסוף נתונים נוספים מהסביבה.
ErrorHostingServiceUnavailable לא ניתן היה לגשת ל-ARCore API. מספר סיבות עלולות לגרום לכך. יכול להיות שהמכשיר במצב טיסה או שאין לו חיבור תקין לאינטרנט. יכול להיות שתם הזמן הקצוב לתפוגה של הבקשה שנשלחה לשרת, בלי שהתקבלה תגובה. יכול להיות שיש חיבור רשת גרוע, DNS לא זמין, בעיות בחומת אש או כל דבר אחר שעלול להשפיע על היכולת של המכשיר להתחבר ל-ARCore API.
ErrorInternal משימה של אירוח או פתרון של הצ'אנק הזה הסתיימה עם שגיאה פנימית. האפליקציה לא צריכה לנסות לשחזר את השגיאה הזו.
ErrorNotAuthorized האפליקציה לא יכולה לתקשר עם ARCore API בגלל הרשאה לא חוקית. בודקים את הגדרות הפרויקט > XR > ARCore Extensions כדי למצוא אסטרטגיית הרשאה תקפה.
ErrorResolvingPackageTooNew לא ניתן היה לפתור את Cloud Anchor כי חבילת התוספים של ARCore ששימשה לפתרון Cloud Anchor חדשה יותר מהגרסה שבה נעשה שימוש לאירוח שלה, והיא לא תואמת לה.
ErrorResolvingPackageTooOld לא ניתן היה לפתור את Cloud Anchor כי חבילת התוספים של ARCore ששימשה לפתרון Cloud Anchor ישנה יותר מהגרסה שבה נעשה שימוש לאירוח שלה, והיא לא תואמת לה.
ErrorResourceExhausted הבקשה חורגת ממכסת הבקשות שהוקצו לפרויקט Google Cloud הנתון. צריך לבקש מכסה נוספת ל-ARCore API בפרויקט שלכם מ-Google Developers Console.
Success משימה של אירוח או פתרון של ציר ה-anchor הזה הושלמה בהצלחה.

מכסות API לבקשות אירוח ופתרון

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

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

שיטות מומלצות לשיפור חוויית המשתמש

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

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

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

  • חשוב לוודא שיש מספיק תאורה בסביבה בעולם האמיתי בזמן אירוח ופתרון של Cloud Anchors.

מדיניות הוצאה משימוש

  • אפליקציות שנוצרו באמצעות ARCore SDK בגרסה 1.12.0 ואילך כפופות למדיניות ההוצאה משימוש של Cloud Anchor API.
  • אפליקציות שנוצרו באמצעות SDK 1.11.0 או גרסה ישנה יותר של ARCore לא יכולות לארח או לפתור עוגנים ב-Cloud בגלל שערכת ה-SDK משתמשת ב-ARCore API ישן יותר שהוצא משימוש.

המאמרים הבאים