מדריך למפתחים של Cloud anchors ל-Android NDK (C)

רוצים לדעת איך משתמשים במודעות עוגן בענן באפליקציות שלכם?

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

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

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

הפעלת ARCore API

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

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

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

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

אירוח של Cloud עוגן

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

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

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

  1. קוראים לפונקציה ArSession_hostCloudAnchorAsync().
  2. להמתין לקריאה החוזרת (callback), או להמשיך לבדוק את המצב העתידי עד שהיא תסתיים.
  3. יש לבדוק את מצב התוצאה כדי לראות אם הפעולה הצליחה, או לפרש את קוד השגיאה אם היא נכשלה.
  4. אפשר לשתף את מזהה ה-Cloud anchor של התוצאה עם לקוחות אחרים, ולהשתמש בו כדי לתקן את ה-Cloud anchor באמצעות ArSession_resolveCloudAnchorAsync().

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

ArFeatureMapQuality מציין את האיכות של נקודות מהתכונות שנצפו על ידי ARCore בשניות הקודמות מתנוחה נתונה במצלמה. בדרך כלל, תגובות עוגן בענן שמתארחות בתכונות באיכות גבוהה יותר יטופלו בצורה מדויקת יותר. באמצעות ArSession_estimateFeatureMapQualityForHosting() ניתן לקבל הערכה לגבי איכות מפת התכונות בתנוחת מצלמה נתונה.

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

תיקון עוגן שמתארח בעבר

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

אפשר ליזום ברצף מספר הגדרות של עוגנים בענן. יכולות להתקיים עד 40 פעולות בו-זמניות של Cloud עוגן.

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

אפשר להתקשר אל ArFuture_cancel() כדי לבטל פעולה בהמתנה של Cloud anchor. אפשר להפעיל את ArAnchor_detach() כדי להפסיק את המעקב ולשכוח מ-Cloud anchor שכבר טופל. יש לבטל בנפרד הפניות לעוגן על ידי קריאה ל-ArAnchor_release().

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

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

Value תיאור
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND פתרון הבעיה נכשל כי ממשק ה-API של ARCore לא מצא את מזהה ה-Cloud עוגן שסופק.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED האירוח נכשל כי השרת לא הצליח לעבד את מערך הנתונים עבור העוגן הנתון. יש לנסות שוב אחרי שהמכשיר יאסוף עוד נתונים מהסביבה.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE לא ניתן היה לגשת ל-ARCore API. מספר סיבות עלולות לגרום לבעיה. ייתכן שהמכשיר במצב טיסה או שאין לו חיבור פעיל לאינטרנט. ייתכן שתם הזמן הקצוב לתפוגה של הבקשה שנשלחה לשרת ולא התקבלה תגובה. יכול להיות שיש חיבור רשת בעייתי, חוסר זמינות ב-DNS, בעיות בחומת האש או כל דבר אחר שעלול להשפיע על היכולת של המכשיר להתחבר ל-ARCore API.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL משימת אירוח או פתרון של עוגן זה הסתיימה עם שגיאה פנימית. האפליקציה לא אמורה לנסות לשחזר את השגיאה.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED כדאי לעיין בפתרון בעיות בהרשאה של ARCore API.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW לא ניתן היה לפתור את הבעיה ב'עוגן בענן' כי גרסת ה-SDK שמשמשת לפתרון של העוגן היא חדשה יותר ולא תואמת לגרסה ששימשה לאירוח העוגן.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD לא ניתן היה לפתור את הבעיה ב'עוגן בענן' כי גרסת ה-SDK שמשמשת לפתרון של העוגן היא ישנה יותר ולא תואמת לגרסה ששימשה לאירוח העוגן.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED האפליקציה מיצתה את מכסת הבקשות שהוקצתה לפרויקט Google Cloud שצוין. עליך לבקש מכסה נוספת ל-ARCore API לפרויקט שלך דרך Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS משימת אירוח או פתרון של עוגן זה הושלמה בהצלחה.

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

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

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

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

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

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

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

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

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

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