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 Street View Google dan membuat pengalaman AR dalam skala global. Geospatial API menggunakan data GPS dan sensor perangkat untuk mendeteksi lingkungan perangkat, lalu mencocokkan bagian-bagian yang dapat dikenali dari lingkungan tersebut dengan model pelokalan yang disediakan oleh Sistem Pemosisi Visual (VPS) Google untuk menentukan lokasi akurat perangkat pengguna. 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 kode 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:

Mendeklarasikan izin aplikasi

Sebelum dapat meminta izin ini saat runtime, Anda harus mendeklarasikannya 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 Jetpack XR Runtime Session, 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, konfigurasi sesi dan tetapkan mode GeospatialMode.VPS_AND_GPS dan 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

Mode GeospatialMode.VPS_AND_GPS memanfaatkan data Visual Positioning System (VPS) dan Global Positioning System (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 mendukung mode ini.

Minta pengguna untuk mengizinkan penggunaan data perangkat

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

Mendapatkan objek Geospatial

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

Periksa ketersediaan VPS

Karena Geospatial API menggunakan kombinasi VPS dan GPS untuk menentukan pose Geospatial, 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 memerlukan konfigurasi sesi 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 membuat data yang mengetahui lokasi. Pipeline ini menerjemahkan posisi dan orientasi perangkat saat ini dalam sistem koordinat lokalnya (pose perangkat) ke dalam koordinat yang diakui secara global.

Cara ini dapat membantu Anda:

  • Membuat konten AR persisten, di mana objek virtual yang ditempatkan pengguna ditambatkan secara akurat ke lokasi global untuk pengambilan nanti.
  • Aktifkan pengalaman berbasis lokasi dengan terus memperbarui posisi pengguna di peta untuk mengaktifkan navigasi real-time atau gameplay berpagar 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 postur geospatial menjadi postur perangkat untuk membantu memberikan pengalaman yang kontekstual dan sadar lokasi di 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 presisi 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