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

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

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

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

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

הפעלה של ARCore API

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

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

אחרי שמפעילים את הפונקציונליות של Cloud עוגנים באפליקציה, צריך להפעיל את היכולות של Cloud עוגנים בהגדרות הסשן ב-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);

אירוח עוגן בענן

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

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

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

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

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

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

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

סימון שהנושא טופל בעוגן שמתארח בעבר

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

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

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

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

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

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

ערך תיאור
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND הפתרון נכשל כי ARCore API לא הצליח למצוא את מזהה ה-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 לא ניתן היה לפתור את הבעיה בעוגן של Cloud כי גרסת ה-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 ופרויקט
בקשות לעיגון בעוגן 300 דקה כתובת IP ופרויקט

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

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

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

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

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

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

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

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