הגדרת Geospatial API באפליקציה

מכשירי XR רלוונטיים

ההנחיות האלה יעזרו לכם ליצור חוויות למכשירי XR מהסוגים הבאים.

מידע ולמידה על סוגי מכשירי XR ←

מידע ולמידה על סוגי מכשירי XR ←

כדי להשתמש ב-Geospatial API באפליקציה, צריך להגדיר את האפליקציה כך שתהיה לה גישה ל-ARCore API ב-Google Cloud. ה-API הזה מכיל את שירות המיקום החזותי, שמספק מיקום מדויק באמצעות נתונים מ-Google Street View.

במדריך הזה נסביר איך להגדיר פרויקט בענן ב-Google Cloud עם ה-API הנכון ושיטות ההרשאה המתאימות לגישה ל-API.

הגדרת פרויקט ב-Google Cloud או שימוש בפרויקט קיים

אם יש לכם פרויקט קיים ב-Google Cloud, בחרו אותו.

כניסה לדף לבחירת הפרויקט

אם אין לכם פרויקט, אתם יכולים ליצור פרויקט חדש.

יצירת פרויקט חדש

הפעלת ARCore API

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

הפעלת ARCore API

הגדרת הרשאה ל-Google Cloud

אפליקציה ל-Android יכולה לתקשר עם ARCore API באמצעות שתי שיטות הרשאה שונות: הרשאה ללא מפתח (OAuth 2.0), שהיא השיטה המומלצת, והרשאה באמצעות מפתח API:

• הרשאה ללא מפתח משתמשת בשילוב של שם החבילה של האפליקציה וטביעת האצבע של מפתח החתימה כדי לאשר את האפליקציה.

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

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

בקשת ההרשאות הנדרשות

כדי להשתמש ב-Geospatial API ב-ARCore עם Jetpack XR, האפליקציה צריכה לבקש את ההרשאות הבאות בתחילת ההפעלה:

• ‫ACCESS_FINE_LOCATION: נדרשת כדי לקבוע את המיקום המדויק של המשתמש.

במכשירים ניידים, Geospatial API דורש גם את ההרשאות הבאות:

• android.permission.CAMERA: נדרשת כדי לגשת למצלמה של המכשיר.
• ‫android.permission.INTERNET: נדרש כדי לתקשר עם שירותי Google Cloud.

איך ניגשים לסשן

כדי לגשת למידע הגיאוגרפי, צריך להשתמש בסביבת זמן הריצה של Jetpack XR Session, שהאפליקציה צריכה ליצור.

הגדרת הסשן

‫Geospatial API לא מופעל כברירת מחדל בסשנים של XR. כדי להפעיל את התכונה באפליקציה, צריך להגדיר GeospatialMode ב-Session. אלה המצבים הזמינים:

• ‫GeospatialMode.SPATIAL: ה-Geospatial API מופעל. ‫Geospatial API משתמש במערכת מיקום חזותי (VPS), בנתוני מערכת איכון עולמית (GPS) ובחיישני התנועה של המכשיר כדי לקבוע את התנוחה הגיאו-מרחבית של המכשיר. המצב הזה לא זמין במשקפיים חכמים.
• ‫GeospatialMode.INERTIAL: Geospatial API מופעל במצב חיסכון בסוללה. ‫Geospatial API משתמש רק ב-GPS ובחיישני התנועה של המכשיר כדי לקבוע את התנוחה המרחבית של המכשיר. המצב הזה זמין רק במכשירים עם משקפיים חכמים.
• ‫GeospatialMode.DISABLED: Geospatial API מושבת. כשעוברים ממצב אחר למצב הזה, Geospatial API משחרר את כל המשאבים שנרכשו ומפסיק את המעקב.

לא כל המכשירים תומכים בכל המצבים של Geospatial. מידע נוסף זמין במאמר GeospatialMode. אפשר להשתמש ב-XrDevice.isGeospatialSupported כדי לבדוק אם יש תמיכה ב-GeospatialMode מסוים.

בדוגמת הקוד הבאה אפשר לראות איך מגדירים GeospatialMode באמצעות Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

הצגת בקשה למשתמש לאשר שימוש בנתוני המכשיר

באפליקציות שמשתמשות ב-Geospatial API עם ARCore ל-Jetpack XR, צריך להציג למשתמשים בקשה לאשר את השימוש בנתונים מהמכשיר שלהם. מידע נוסף זמין בדרישות בנושא פרטיות המשתמשים.

שימוש באובייקט Geospatial

אחרי שמגדירים את הסשן, מקבלים את האובייקט Geospatial באמצעות Geospatial.getInstance. צריך להשתמש באובייקט Geospatial רק כשהמצב שלו הוא GeospatialTrackingState.RUNNING.

בדוגמאות הקוד הבאות אפשר לראות איך לעקוב אחרי המצב הגיאוגרפי באמצעות Geospatial.state.

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

הסבר על ערכי הדיוק

כשה-Geospatial API מופעל, הוא מספק שלושה ערכי דיוק: דיוק אופקי, דיוק אנכי ודיוק בכיוון. ערכי הדיוק האלה מתעדכנים עם הזמן, וככל שמצטברים יותר נתונים, כך הם הופכים למדויקים יותר. ערכים גדולים יותר מציינים דיוק נמוך יותר, והם מוגדרים כרדיוס של רמת סמך של 68%. במילים אחרות, יש סיכוי של 68% שהערך האמיתי נמצא בטווח הרדיוס הנתון של הערך המשוער.

כדי לקבל את ערכי הדיוק הנוכחיים, משתמשים ב-Geospatial.State.horizontalAccuracy, ב-verticalAccuracy וב-orientationYawAccuracy.

יכול להיות שהאפליקציה שלכם צריכה רמת דיוק מסוימת כדי לפעול כמו שצריך. לדוגמה, יכול להיות שהאפליקציה תצטרך להמתין עד שהדיוק האופקי יהיה פחות מ-5 מטרים לפני שהיא תציג תוכן וירטואלי. כדי להגדיל את הסיכוי לקבל נתונים מדויקים יותר, האפליקציה צריכה להנחות את המשתמשים להסתכל סביבם, רצוי על מבנים או מאפיינים אחרים עם פרטים חזותיים רבים שמופיעים ב-Google Street View. משתמשים ב-Geospatial.checkVpsAvailability כדי לקבוע אם שירות VPS זמין במיקום הנתון.

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

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

• המרת תנוחות מקומיות במכשיר לתנוחות גיאו-מרחביות,
• עיבוד תוכן בתנוחות גיאו-מרחביות