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

1. Ringkasan

ARCore adalah framework Google untuk mem-build pengalaman Augmented Reality di smartphone. ARCore Geospatial API baru memberikan aspek baru ke Augmented Reality, yang memungkinkan Anda menempatkan titik jalan Augmented Reality khusus lokasi di sekitar penanda 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 cara data ini dapat digunakan untuk mendukung pengalaman navigasi 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 mendukung ARCore, terhubung menggunakan kabel USB ke mesin pengembangan, dikonfigurasi dengan proses debug USB.
• Android Studio yang diinstal dan dikonfigurasi untuk mem-build aplikasi Android.
• Layanan Google Play untuk AR 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. Hal ini akan membantu Anda memulai Geospatial API dengan cepat.

1. Mulai Android Studio dan impor project dari VCS.
   • Jika sudah membuka project, gunakan File > New > Project from 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 gambar StreetView yang dikombinasikan dengan informasi magnetometer dan sensor kamera 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 & Layanan, lalu Library.
   • Telusuri ARCore API.
   • Klik Aktifkan.
   • Kembali ke Koleksi.
   • Telusuri Maps SDK for Android.
   • Klik Aktifkan.
3. Membuat kredensial Kunci API:
   • Di bagian APIs & Services, pilih Credentials.
   • Di panel atas, klik Create Credentials, lalu pilih API Key.
   • Catat kunci yang dibuat karena Anda akan memerlukannya 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 sekarang 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.
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 project Anda sudah siap. 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 mulai menggunakan 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
    }
  )
}

Saat 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 akan muncul.

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

• Lokasi, dinyatakan dalam lintang dan bujur. Estimasi akurasi lokasi juga disediakan.
• Elevasi, dan estimasi akurasi elevasi.
• Arah, perkiraan arah yang dihadapi perangkat, dan estimasi akurasi arah.

Menampilkan informasi pemosisian di peta

Anda dapat menggunakan GeospatialPose yang disimpan di cameraGeospatialPose untuk memindahkan penanda pada peta yang menunjukkan lokasi pengguna. Lanjutkan dari tempat Anda berhenti dan tambahkan kode berikut:

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

Tindakan 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. Panah juga harus mengarah ke arah yang benar: saat Anda secara fisik menghadap ke Utara, panah juga akan mengarah ke Utara.

4. Menempatkan anchor menggunakan koordinat Bumi

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 akan menambahkan cara untuk menempatkan Anchor dengan mengetuk peta.

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

Memastikan objek Bumi dapat digunakan

Sebelum membuat anchor di Bumi, pastikan TrackingState objek Bumi adalah TRACKING, yang berarti posisi Bumi 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 Bumi 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 ditetapkan ke koordinat geodetik dengan rotasi tertentu. Anchor ini mencoba tetap stabil dan tetap pada koordinat dan ketinggian yang ditentukan.

Variabel [qx, qy, qz, qw] menentukan rotasi anchor yang dinyatakan dalam kuadrona, dalam sistem koordinat Timur-Atas-Selatan (EUS). Anda menggunakan nilai yang berbeda untuk memutar anchor, tetapi dalam contoh ini, gunakan kuadrat unit untuk rotasi default. Rotasi kuarternion unit memiliki orientasi anchor sehingga X+ mengarah ke timur, Y+ mengarah ke atas dari pusat bumi, dan Z+ mengarah ke selatan.

Menampilkan penanda yang ditempatkan di peta

Terakhir, pindahkan penanda baru yang menunjukkan tempat penanda ditempatkan:

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 menggunakan Geospatial API untuk menempatkan anchor, yang ditetapkan ke lokasi dunia nyata. Coba tempatkan anchor di dekat lokasi Anda saat ini sehingga Anda dapat melihatnya dalam tampilan AR. Kualitasnya akan tetap stabil saat Anda menjelajahi lingkungan.

5. Kesimpulan

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

Yang telah kita bahas

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

Referensi lainnya

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

• Dokumentasi ARCore Geospatial API
• World Geodetic System (WGS)
• Google Maps SDK for Android