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:
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 presisi pengguna.
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 = 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.
}
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
var geospatial = Geospatial.getInstance(session)
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 dapat digunakan selama 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 umum, 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 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
}
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
// 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
}
}
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():
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
}
}