עבודה עם מיקומים גיאו-מרחביים באמצעות ARCore for Jetpack XR

מכשירי XR שמתאימים לשימוש

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

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

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

באמצעות Geospatial API ב-ARCore for Jetpack XR, האפליקציה יכולה לצרף מרחוק תוכן לכל אזור שמכוסה על ידי Street View של Google וליצור חוויות AR בקנה מידה גלובלי. ‫Geospatial API משתמש בנתוני חיישנים ובנתוני GPS של המכשיר כדי לזהות את הסביבה של המכשיר, ואז מתאים את החלקים שניתנים לזיהוי בסביבה הזו למודל לוקליזציה שסופק על ידי מערכת מיקום חזותי (VPS) של Google, כדי לקבוע את המיקום המדויק של המכשיר של המשתמש. בנוסף, ה-API דואג למיזוג של הקואורדינטות המקומיות של המשתמש עם הקואורדינטות הגאוגרפיות מ-VPS, כך שתוכלו לעבוד עם מערכת קואורדינטות אחת.

הפעלת ARCore API

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

הוספת תלות של הפרויקט בספריות נוספות

כדי להשתמש ב-Geospatial API, צריך להוסיף כמה תלויות בספרייה. מוסיפים את השורות הבאות לקובץ build.gradle.kts של האפליקציה:

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation "com.google.android.gms:play-services-location:21.3.0"
}

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation("com.google.android.gms:play-services-location:21.3.0")
}

שליחת בקשה להרשאות הנדרשות

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

• ‫ACCESS_INTERNET: נדרש כדי ליצור קשר עם שירות הענן של ARCore Geospatial API.
• ‫ACCESS_COARSE_LOCATION: נדרשת כדי לקבוע את המיקום המשוער של המשתמש.
• ‫ACCESS_FINE_LOCATION: נדרש כדי לקבוע את המיקום המדויק של המשתמש.

הצהרה על הרשאות הניתנות לאפליקציות

לפני שתוכלו לבקש את ההרשאות האלה בזמן ריצה, תצטרכו להצהיר עליהן במניפסט של האפליקציה:

<manifest ... >
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

שליחת בקשה להרשאות

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

ממשק Geospatial API לא יכול לפעול אם הוא לא יכול לקבוע את המיקום המדויק של המשתמש. לכן, חשוב לפעול לפי ההנחיות בנושא בקשת הרשאות מיקום בזמן ריצה כדי שהאפליקציה תוכל לקבל את ההרשאות ACCESS_FINE_LOCATION ו-ACCESS_COARSE_LOCATION.

גישה לסשן

גישה למידע גיאו-מרחבי דרך Jetpack XR Runtime Session, שהאפליקציה צריכה ליצור.

הגדרת הסשן

המידע על תנוחת המכשיר לא מופעל כברירת מחדל בסשנים של XR. כדי לאפשר לאפליקציה לאחזר מידע על תנוחת המכשיר, צריך להגדיר את הסשן ולבחור את המצבים GeospatialMode.VPS_AND_GPS ו-DeviceTrackingMode.LAST_KNOWN:

// Define the configuration object to enable Geospatial features.
val newConfig = Config(
    // Set the GeospatialMode to VPS_AND_GPS.
    geospatial = GeospatialMode.VPS_AND_GPS,
    // Set the DeviceTrackingMode to LAST_KNOWN.
    deviceTracking = DeviceTrackingMode.LAST_KNOWN
)
// 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.
}
Geospatial.kt

במצב GeospatialMode.VPS_AND_GPS נעשה שימוש בנתונים של מערכת מיקום חזותי (VPS) ושל מערכת מיקום גלובלית (GPS) כדי לקבוע בצורה מדויקת את המיקום הגיאוגרפי של המכשיר.

לא כל מכשירי ה-XR תומכים במצבי GeospatialMode.VPS_AND_GPS ו-DeviceTrackingMode.LAST_KNOWN. אם הפקודה Session.configure() מצליחה, המכשיר תומך במצבים האלה.

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

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

קבלת האובייקט הגיאו-מרחבי

אחרי שמגדירים את הסשן, מקבלים את האובייקט Geospatial באמצעות Geospatial.getInstance(session):

// Get the Geospatial instance for the current session.
val geospatial = Geospatial.getInstance(session)
Geospatial.kt

אפשר להשתמש באובייקט Geospatial רק כשהמצב שלו הוא State.RUNNING. אפשר לעקוב אחרי הסטטוס באמצעות Geospatial.state StateFlow<Geospatial.State>.

בדיקת הזמינות של שרתים וירטואליים פרטיים

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

בתנאים אופייניים, אפשר לצפות ש-VPS יספק דיוק מיקום של כ-5 מטרים ודיוק סיבוב של 5 מעלות. אפשר לבדוק אם יש כיסוי של VPS במיקום מסוים באמצעות פונקציית ההשעיה Geospatial.checkVpsAvailability(latitude, longitude). הקריאה הזו היא פעולה אסינכרונית ולא נדרש להגדיר את הסשן במצב GeospatialMode.VPS_AND_GPS.

הקוד הבא מראה איך בודקים את הזמינות של VPS לפי קו רוחב וקו אורך שצוינו:

// You can query the GPS to get the current device's location.
val latitude = 37.422
val longitude = -122.084

// Use the geospatial instance to check VPS availability for a specific location.
val result = geospatial.checkVpsAvailability(latitude, longitude)
when (result) {
    is VpsAvailabilityAvailable -> {
        // VPS is available at this location.
    }
    is VpsAvailabilityErrorInternal -> {
        // VPS availability check failed with an internal error.
    }
    is VpsAvailabilityNetworkError -> {
        // VPS availability check failed due to a network error.
    }
    is VpsAvailabilityNotAuthorized -> {
        // VPS availability check failed due to an authorization error.
    }
    is VpsAvailabilityResourceExhausted -> {
        // VPS availability check failed due to resource exhaustion.
    }
    is VpsAvailabilityUnavailable -> {
        // VPS is not available at this location.
    }
}
Geospatial.kt

האפליקציה צריכה להיות מוגדרת בצורה נכונה כדי לתקשר עם ARCore API ב-Google Cloud. אחרת, האפליקציה תקבל תוצאה של VpsAvailabilityNotAuthorized.

המרת תנוחת מכשיר לתנוחה גיאו-מרחבית

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

כך תוכלו:

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

כדי להמיר תנוחת מכשיר לתנוחה גיאו-מרחבית באמצעות Geospatial.createGeospatialPoseFromPose():

// Get the current device Pose from the AR Session's state.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose.
when (val result = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val geoPose = result.pose
        val lat = geoPose.latitude
        val lon = geoPose.longitude
        val alt = geoPose.altitude
        // Orientation is in the EUS (East-Up-South) coordinate system.
        val orientation = geoPose.eastUpSouthQuaternion
    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt

המרת תנוחה גיאו-מרחבית לתנוחת מכשיר

אתם יכולים להמיר תנוחה גיאוספציאלית לתנוחת מכשיר כדי לספק חוויות הקשריות שמבוססות על מיקום במשקפי AI. הטרנספורמציה הזו לוקחת מידע שמוגדר על ידי קואורדינטות בעולם האמיתי – כמו המיקום של נקודת ציון, נתיב ניווט או תוכן AR קבוע – וממירה אותו למרחב הוויזואלי המדויק של המשקפיים של המשתמש.

כדי להמיר תנוחה גיאוספציאלית לתנוחת מכשיר באמצעות Geospatial.createPoseFromGeospatialPose():

// Convert a GeospatialPose (lat/long/alt) back to a device-space Pose.
when (val result = geospatial.createPoseFromGeospatialPose(geoPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose: Pose = result.pose
        // devicePose is now ready to be used relative to the tracking origin.
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt