Android XR SDK telah mencapai Pratinjau Developer 3, dan kami ingin mendengar masukan Anda. Coba fitur-fitur yang ada, dan buka halaman dukungan kami untuk menghubungi kami.

Menggunakan pose geospasial dengan ARCore untuk Jetpack XR

Perangkat XR yang kompatibel

Panduan ini membantu Anda membangun pengalaman untuk jenis perangkat XR ini.

Mempelajari jenis perangkat XR →

Kacamata AI

Mempelajari jenis perangkat XR →

Dengan Geospatial API di ARCore untuk Jetpack XR, aplikasi Anda dapat melampirkan konten dari jarak jauh ke area mana pun yang dicakup oleh Google Street View dan membuat pengalaman AR dalam skala global. Geospatial API menggunakan data sensor perangkat dan GPS untuk mendeteksi lingkungan perangkat, lalu mencocokkan bagian lingkungan yang dapat dikenali dengan model pelokalan yang disediakan oleh Sistem Pemosisi Visual (VPS) Google untuk menentukan lokasi perangkat pengguna yang akurat. API ini juga menangani penggabungan koordinat lokal pengguna dengan koordinat geografis dari VPS sehingga Anda dapat bekerja dalam satu sistem koordinat.

Mengaktifkan ARCore API

Sebelum menggunakan Sistem Pemosisi Visual (VPS) di aplikasi, Anda harus mengaktifkan ARCore API terlebih dahulu di project Google Cloud baru atau yang sudah ada. Layanan ini bertanggung jawab untuk menghosting, menyimpan, dan menyelesaikan anchor Geospasial.

Menambahkan dependensi library tambahan

Penggunaan Geospatial API memerlukan beberapa dependensi library tambahan. Tambahkan dependensi ini ke file build.gradle.kts aplikasi Anda:

Groovy

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

Kotlin

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

Meminta izin yang diperlukan

Untuk menggunakan Geospatial API di ARCore dengan Jetpack XR, aplikasi Anda perlu meminta izin runtime berikut:

ACCESS_INTERNET: Diperlukan untuk menghubungi layanan cloud ARCore Geospatial API.
ACCESS_COARSE_LOCATION: Diperlukan untuk menentukan perkiraan lokasi pengguna.
ACCESS_FINE_LOCATION: Diperlukan untuk menentukan lokasi pengguna yang akurat.

Mendeklarasikan izin aplikasi

Sebelum dapat meminta izin ini saat runtime, Anda harus mendeklarasikan nya dalam manifes aplikasi:

<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>

Meminta izin

Setelah mendeklarasikan izin yang diperlukan, aplikasi Anda harus memintanya saat runtime. Pastikan untuk menjelaskan alasan aplikasi Anda memerlukan izin tersebut.

Geospatial API tidak dapat berfungsi kecuali jika dapat menentukan lokasi pengguna yang akurat. Oleh karena itu, ikuti panduan untuk meminta izin lokasi saat runtime agar aplikasi Anda dapat diberikan izin ACCESS_FINE_LOCATION dan ACCESS_COARSE_LOCATION.

Mengakses sesi

Akses informasi geospasial melalui Session Jetpack XR Runtime, yang harus dibuat oleh aplikasi Anda.

Mengonfigurasi sesi

Informasi pose perangkat tidak diaktifkan secara default pada sesi XR. Untuk mengaktifkan aplikasi Anda agar dapat mengambil informasi pose perangkat, konfigurasikan sesi dan tetapkan mode GeospatialMode.VPS_AND_GPS dan DeviceTrackingMode.LAST_KNOWNmodes:

// 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

Mode GeospatialMode.VPS_AND_GPS memanfaatkan data Sistem Pemosisi Visual (VPS) dan Sistem Pemosisi Global (GPS) untuk menentukan posisi geospasial perangkat secara akurat.

Tidak semua perangkat XR mendukung mode GeospatialMode.VPS_AND_GPS dan DeviceTrackingMode.LAST_KNOWN. Jika Session.configure() berhasil, perangkat akan mendukung mode ini.

Meminta pengguna untuk mengizinkan penggunaan data perangkat

Aplikasi yang menggunakan Geospatial API dengan ARCore untuk Jetpack XR harus menampilkan perintah kepada pengguna untuk mengakui dan mengizinkan penggunaan data dari perangkat mereka. Lihat persyaratan privasi pengguna untuk mengetahui informasi selengkapnya.

Mendapatkan objek Geospasial

Setelah sesi dikonfigurasi, dapatkan objek Geospatial menggunakan Geospatial.getInstance(session):

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

Objek Geospatial hanya boleh digunakan saat statusnya adalah State.RUNNING. Anda dapat memantau status menggunakan Geospatial.state StateFlow<Geospatial.State>.

Memeriksa ketersediaan VPS

Karena Geospatial API menggunakan kombinasi VPS dan GPS untuk menentukan pose Geospasial, API ini tersedia setiap kali perangkat dapat menentukan lokasinya. Di area dengan akurasi GPS rendah, seperti ruang dalam ruangan dan lingkungan perkotaan yang padat, API mengandalkan cakupan VPS untuk menghasilkan pose dengan akurasi tinggi.

Dalam kondisi normal, Anda dapat mengharapkan VPS memberikan akurasi posisi sekitar 5 meter dan akurasi rotasi 5 derajat. Anda dapat memeriksa apakah suatu lokasi memiliki cakupan VPS menggunakan fungsi penangguhan Geospatial.checkVpsAvailability(latitude, longitude). Panggilan ini adalah operasi asinkron dan tidak mengharuskan sesi dikonfigurasi dengan mode GeospatialMode.VPS_AND_GPS.

Kode berikut menunjukkan cara memeriksa ketersediaan VPS dari lintang dan bujur yang ditentukan:

// 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

Aplikasi Anda harus disiapkan dengan benar untuk berkomunikasi dengan ARCore API di Google Cloud; jika tidak, aplikasi Anda akan menerima hasil VpsAvailabilityNotAuthorized.

Mengonversi pose perangkat menjadi pose geospasial

Anda dapat mengonversi pose perangkat menjadi pose geospasial untuk memungkinkan kacamata AI berinteraksi dengan dan menghasilkan data yang mengetahui lokasi. Pipeline ini menerjemahkan posisi dan orientasi perangkat saat ini dalam sistem koordinat lokalnya (pose perangkat) menjadi koordinat yang diakui secara global.

Hal ini dapat membantu Anda:

Membuat konten AR persisten, tempat objek virtual yang ditempatkan pengguna ditambatkan secara akurat ke lokasi global untuk pengambilan nanti.
Memicu pengalaman berbasis lokasi dengan terus memperbarui posisi pengguna di peta untuk mengaktifkan navigasi real-time atau gameplay dengan batas geografis.
Menentukan konteks dunia nyata pengguna yang akurat untuk memicu logika aplikasi yang relevan dengan lokasi.

Untuk mengonversi pose perangkat menjadi pose geospasial menggunakan 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

Mengonversi pose geospasial menjadi pose perangkat

Anda dapat mengonversi pose geospasial menjadi pose perangkat untuk membantu memberikan pengalaman kontekstual yang mengetahui lokasi pada kacamata AI. Transformasi ini mengambil informasi yang ditentukan oleh koordinat dunia nyata—seperti lokasi landmark, jalur navigasi, atau konten AR persisten—dan mengonversinya menjadi ruang visual yang akurat dari kacamata pengguna.

Untuk mengonversi pose geospasial menjadi pose perangkat menggunakan 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