Membangun aplikasi augmented reality (AR) menggunakan ARCore Geospatial API yang baru

1. Ringkasan

ARCore adalah framework Google untuk membangun pengalaman Augmented Reality di smartphone. ARCore Geospatial API yang baru memberikan aspek baru untuk Augmented Reality, sehingga Anda dapat menempatkan titik jalan Augmented Reality khusus lokasi di sekitar tempat terkenal di dunia nyata.

Yang akan Anda build

Dalam codelab ini, Anda akan mulai menggunakan ARCore Geospatial API. Anda akan menemukan informasi yang dapat ditawarkan Geospatial API untuk pengalaman AR secara keseluruhan, dan bagaimana data ini dapat digunakan untuk mendukung pengalaman pemilihan AR yang sederhana.

Yang akan Anda pelajari

• Cara menyiapkan project ARCore yang menggunakan Geospatial API.
• Cara meminta data geografis dari Geospatial API dan menampilkannya menggunakan Google Maps.
• Cara menempatkan Anchor yang terpasang pada lokasi dunia nyata.

Yang Anda butuhkan

• Perangkat Android yang didukung ARCore, yang terhubung menggunakan kabel USB ke mesin pengembangan, dikonfigurasi dengan proses debug USB.
• Android Studio yang diinstal dan dikonfigurasi untuk membangun aplikasi Android.
• Layanan Google Play untuk AR versi 1.31 atau yang lebih baru, yang diinstal di perangkat pengembangan Android.

2. Menyiapkan lingkungan pengembangan

Menyiapkan Android Studio

Untuk membantu Anda mulai menggunakan Geospatial API, kami menyediakan project awal yang mencakup dasar-dasar project ARCore yang terintegrasi dengan Google Maps SDK. Langkah ini akan membantu Anda menggunakan Geospatial API.

1. Mulai Android Studio dan impor project dari VCS.
   • Jika sudah membuka project, gunakan File > Baru > Project dari Version Control....
   • Jika jendela Welcome to Android Studio ditampilkan, gunakan Get from VCS.
2. Pilih Git, dan gunakan URL https://github.com/google-ar/codelab-geospatial.git untuk mengimpor project.

Menyiapkan Project Google Cloud

Geospatial API menggunakan citra StreetView yang dikombinasikan dengan informasi sensor kamera dan magnetometer perangkat untuk meningkatkan nilai orientasi. Untuk menggunakan layanan ini, Anda perlu menyiapkan Project Google Cloud.

1. Buat project di Konsol Google Cloud:
   • Buka Membuat project di Google Cloud Platform.
     
   • Masukkan Project name yang sesuai (misalnya, "ARCore Geospatial API project"), lalu pilih lokasi mana pun.
   • Klik Buat.
2. Aktifkan API yang diperlukan:
   • Di sidebar, pilih API & Services, lalu Library.
   • Cari ARCore API.
   • Klik Aktifkan.
   • Kembali ke Koleksi.
   • Telusuri Maps SDK for Android.
   • Klik Aktifkan.
3. Membuat kredensial Kunci API:
   • Di bagian APIs & Layanan, pilih Credentials.
   • Di panel atas, klik Create Credentials, lalu pilih API Key.
   • Catat kunci yang dibuat sesuai kebutuhan Anda untuk langkah berikutnya. Kembali ke halaman Credentials jika Anda perlu mengambilnya.

Dengan langkah-langkah ini, Anda telah membuat Project Google Cloud dengan otorisasi kunci API, dan Anda siap menggunakan Geospatial API.

Mengintegrasikan kunci API dengan project Android Studio

Untuk mengaitkan kunci API dari Google Cloud dengan project Anda, buka project yang Anda buat di Android Studio dan ubah kunci API:

1. Buka app > src > AndroidManifest.xml aplikasi Anda.
2. Temukan entri meta-data berikut:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. Ganti PLACEHOLDER_API_KEY dengan kunci API yang Anda buat di project Google Cloud.

Nilai yang tersimpan di com.google.android.ar.API_KEY akan memberikan otorisasi kepada aplikasi ini untuk menggunakan Geospatial API, dan nilai yang tersimpan di com.google.android.geo.API_KEY mengizinkan aplikasi ini untuk menggunakan Google Maps SDK.

Memverifikasi project

Pastikan semua project Anda siap dijalankan. Di Android Studio, jalankan aplikasi Anda. Anda akan dapat melihat tampilan kamera, beserta peta yang berfungsi di bagian bawah layar.

3. Menentukan posisi pengguna

Pada langkah ini, Anda akan menambahkan kode ke project contoh untuk memulai Geospatial API.

Mengonfigurasi sesi ARCore untuk menggunakan Geospatial API

Untuk mendapatkan data Geospasial, Anda harus mengaktifkan Geospatial API. Ubah GeospatialMode dalam konfigurasi sesi Anda menjadi ENABLED dengan mengubah fungsi configureSession di HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

Meskipun mode Geospasial adalah ENABLED, aplikasi dapat memperoleh informasi Geospasial.

Meminta data dari Geospatial API

Di HelloGeoRenderer.kt, temukan baris berikut:

// TODO: Obtain Geospatial information and display it on the map.

Di bawahnya, periksa apakah objek Earth tersedia untuk digunakan. Saat itulah trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

Di bawah TODO, minta informasi Geospasial dari ARCore. Tambahkan baris ini:

val cameraGeospatialPose = earth.cameraGeospatialPose

Tindakan ini akan memberi Anda GeospatialPose yang berisi informasi berikut:

• Lokasi, dinyatakan dalam lintang dan bujur. Perkiraan akurasi lokasi juga disediakan.
• Elevasi, dan perkiraan akurasi elevasi.
• Arah, perkiraan arah hadap perangkat, dan perkiraan akurasi arah.

Tampilkan informasi pemosisian di peta

Anda dapat menggunakan GeospatialPose yang disimpan di cameraGeospatialPose untuk memindahkan penanda pada peta yang menunjukkan lokasi pengguna. Lanjutkan dari halaman terakhir yang Anda buka dan tambahkan hal berikut:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

Hal ini akan terus memperbarui posisi peta menggunakan nilai yang diperoleh dari Geospatial API.

Cobalah

Di Android Studio, klik Play. Pegang perangkat Anda dan gerakkan untuk membantu ARCore membuat pelacakan. Setelah beberapa saat, Anda akan melihat penanda hijau muncul di peta. Penanda ini berputar saat Anda melihat sekeliling Anda. Rute juga harus menunjuk ke arah yang benar: jika Anda menghadap secara fisik ke Utara, panah juga mengarah ke Utara.

4. Menempatkan jangkar menggunakan koordinat Earth

Geospatial API dapat menempatkan Anchor pada pasangan koordinat dan rotasi apa pun di dunia nyata. Hal ini memungkinkan pengguna Anda melihat konten anchor saat lokasi tertentu dikunjungi.

Pada langkah ini, Anda menambahkan cara untuk menempatkan Anchor dengan mengetuk peta.

Tetapkan tindakan saat peta diketuk

Project ini dilengkapi dengan fungsi onMapClick, yang dipanggil dengan lintang dan bujur saat fragmen peta diklik. Temukan fungsi onMapClick di HelloGeoRenderer.kt.

Pastikan objek Earth dapat digunakan

Sebelum membuat anchor di Bumi, pastikan TrackingState objek Bumi adalah TRACKING, yang berarti posisi Bumi telah diketahui. Pastikan juga EarthState-nya adalah ENABLED, yang berarti tidak ada masalah yang terjadi dengan Geospatial API. Tambahkan baris berikut di dalam onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

Menentukan posisi Anchor baru

Setelah mengonfirmasi bahwa objek Earth sedang melacak, lepaskan earthAnchor sebelumnya, jika ada. Anda akan mengganti earthAnchor dengan anchor baru di langkah berikutnya:

earthAnchor?.detach()

Lalu, gunakan cameraGeospatialPose untuk menentukan ketinggian anchor baru. Gunakan pasangan koordinat dari mengetuk peta sebagai pemosisian anchor.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor membuat Anchor yang tetap ke koordinat geodesi dengan rotasi tertentu. Anchor ini berupaya untuk tetap stabil dan tetap sesuai koordinat dan ketinggian yang ditentukan.

Variabel [qx, qy, qz, qw] menentukan rotasi yang dinyatakan dalam kuaternion anchor, di sistem koordinat Timur-Up-Selatan (EUS). Anda menggunakan nilai yang berbeda untuk memutar anchor, tetapi dalam contoh ini, gunakan kuaternion unit untuk rotasi default. Rotasi unit kuarternion memiliki jangkar berorientasi sedemikian rupa sehingga X+ menunjuk ke timur, Y+ menunjuk ke atas dari pusat bumi, dan Z+ menunjuk ke selatan.

Menampilkan penanda yang ditempatkan di peta

Terakhir, pindahkan penanda baru yang menunjukkan lokasi penempatan penanda:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

Cobalah

Di Android Studio, klik Play. Pegang perangkat Anda, dan gerakkan untuk membantu ARCore membuat pelacakan. Setelah beberapa saat, Anda akan melihat penanda hijau muncul di peta yang menunjukkan posisi Anda saat ini.

Mengetuk peta akan menggunakan Geospatial API untuk menempatkan anchor, yang telah ditetapkan ke lokasi dunia nyata. Coba tempatkan anchor di dekat lokasi Anda saat ini sehingga Anda dapat melihatnya dalam tampilan AR. Kode ini harus tetap stabil saat Anda menavigasi lingkungan.

5. Kesimpulan

Dalam codelab ini, Anda telah mempelajari cara menggunakan Geospatial API untuk membuat pengalaman AR sederhana yang terikat dengan dunia nyata.

Yang telah kita bahas

• Cara menyiapkan project Google Cloud dengan Geospatial API.
• Cara mendapatkan informasi Geospasial dalam project ARCore dan menampilkannya di peta.
• Cara menempatkan anchor yang diposisikan di dunia nyata menggunakan posisi geografis.

Referensi lainnya

Untuk detail selengkapnya tentang konsep geografis dan SDK yang digunakan dalam codelab ini, lihat referensi tambahan berikut:

• Dokumentasi ARCore Geospatial API
• Sistem Geodetik Dunia (WGS)
• Google Maps SDK for Android