מדריך למפתחים של Cloud anchors ל-Android (Kotlin/Java)

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

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

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

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

הפעלת ה-API של ARCore

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

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

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

JavaKotlin
Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);
 
val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

אירוח של Cloud Anchor

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

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

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

  1. קוראים לפונקציה hostCloudAnchorAsync().
  2. צריך להמתין לשיחה החוזרת או לבדוק באופן קבוע את המצב העתידי עד שהפעולה תסתיים.
  3. בודקים את סטטוס התוצאה כדי לקבוע אם הפעולה הצליחה, או מפרשים את קוד השגיאה אם היא נכשלה.
  4. משתפים את מזהה Cloud Anchor שהתקבל עם לקוחות אחרים, ומשתמשים בו כדי לפתור את Cloud Anchor באמצעות resolveCloudAnchorAsync().

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

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

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

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

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

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

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

כדי לבטל פעולת Cloud Anchor בהמתנה, מתקשרים למספר cancel(). כדי להסיר מהאפליקציה Cloud Anchor שכבר נפתר, קוראים ל-detach().

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

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

ערך תיאור
ERROR_CLOUD_ID_NOT_FOUND הפתרון נכשל כי ARCore API לא הצליח למצוא את מזהה Cloud Anchor שצוין.
ERROR_HOSTING_DATASET_PROCESSING_FAILED האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים של הצ'אנק הנתון. נסו שוב אחרי שהמכשיר יאסוף נתונים נוספים מהסביבה.
ERROR_HOSTING_SERVICE_UNAVAILABLE לא ניתן היה לגשת ל-ARCore API. מספר סיבות עלולות לגרום לכך. יכול להיות שהמכשיר במצב טיסה או שאין לו חיבור תקין לאינטרנט. יכול להיות שתם הזמן הקצוב לתפוגה של הבקשה שנשלחה לשרת, בלי שהתקבלה תגובה. יכול להיות שיש חיבור רשת גרוע, DNS לא זמין, בעיות בחומת אש או כל דבר אחר שעלול להשפיע על היכולת של המכשיר להתחבר ל-ARCore API.
ERROR_INTERNAL משימה של אירוח או פתרון של הצ'אנק הזה הסתיימה עם שגיאה פנימית. האפליקציה לא צריכה לנסות לשחזר את השגיאה הזו.
ERROR_NOT_AUTHORIZED ההרשאה שסופקה על ידי האפליקציה לא תקפה. פתרון בעיות שקשורות להרשאה של ARCore API
ERROR_RESOLVING_SDK_VERSION_TOO_NEW לא ניתן היה לפתור את Cloud Anchor כי גרסת ה-SDK ששימשה לפתרון העוגן חדשה יותר מהגרסה ששימשה לאירוח שלו, והיא לא תואמת לה.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD לא ניתן היה לפתור את Cloud Anchor כי גרסת ה-SDK ששימשה לפתרון העוגן ישנה יותר מהגרסה ששימשה לאירוח שלו, והיא לא תואמת לה.
ERROR_RESOURCE_EXHAUSTED הבקשה חורגת ממכסת הבקשות שהוקצו לפרויקט 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 ישן יותר שהוצא משימוש.

מה השלב הבא?