עבודה עם מיקומים גיאו-מרחביים באמצעות 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 = session.config.copy(
  // Set the GeospatialMode to VPS_AND_GPS.
  geospatial = Config.GeospatialMode.VPS_AND_GPS
  // Set the DeviceTrackingMode to LAST_KNOWN.
  deviceTracking = Config.DeviceTrackingMode.LAST_KNOWN
)

// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureGooglePlayServicesLocationLibraryNotLinked -> {
            // This case generally indicates a missing library dependency.
        }
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }
        else -> {
            // Catch-all for other configuration errors returned using the result class.
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure. For example, if the specific mode is not supported on the current device or API version.
}

במצב 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
var geospatial = Geospatial.getInstance(session)

אפשר להשתמש באובייקט 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 and check if it has VPS
val latitude = getLatitudeFromGPS()
val longitude = getLongitudeFromGPS()

// Must be called from a coroutine.
val result = geospatial.checkVpsAvailability(latitude, longitude)
if (result is VpsAvailabilityAvailable) {
  // VPS is available
} else if (result is VpsAvailabilityUnavailable) {
  // VPS is not available
}

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

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

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

כך תוכלו:

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

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

// Get the current device Pose from the AR Session's state
// This is the device's position and orientation relative to the AR tracking origin.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose
when (val geospatialPoseResult = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val currentGeospatialPose = geospatialPoseResult.pose
        val horizontalAccuracy = geospatialPoseResult.horizontalAccuracy
        // ... use pose and accuracy
     val latitude = currentGeospatialPose.latitude
     val longitude = currentGeospatialPose.longitude
    // The orientation is stored as a Quaternion in the EUS (East-Up-South) system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south. True North is aligned with the -Z axis.
     val eusQuaternion = currentGeospatialPose.eastUpSouthQuaternion

    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}

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

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

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

when (val poseResult = geospatial.createPoseFromGeospatialPose(geospatialPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose = poseResult.pose
    // devicePose is now ready to be used
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}