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

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

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

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

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

הפעלת ה-API של ARCore

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

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

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

אירוח של Cloud Anchor

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

אפשר גם להאריך את משך החיים של עוגן מתארח באמצעות ARCore Cloud GCM 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 ברצף. אפשר להריץ בו-זמנית עד 40 פעולות של Cloud Anchor.

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

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

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

אפשר להשתמש ב-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 כי החבילה של תוספי ARCore ששימשה לפענוח העוגן של Cloud היא גרסה ישנה יותר ולא תואמת לגרסה שבה היא מתארחת.
ErrorResourceExhausted האפליקציה מיצה את מכסת הבקשות שהוקצתה לפרויקט הנתון ב-Google Cloud. צריך לבקש מכסה נוספת ל-ARCore API בפרויקט שלכם מ-Google Developers Console.
Success משימה של אירוח או פתרון של ציר ה-anchor הזה הושלמה בהצלחה.

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

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

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

שיטות מומלצות לחוויית משתמש טובה

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

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

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

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

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

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

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