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 ke Augmented Reality, yang memungkinkan Anda menempatkan titik jalan Augmented Reality spesifik per lokasi di sekitar tempat terkenal di dunia nyata.

Yang akan Anda bangun

Dalam codelab ini, Anda akan mulai menggunakan ARCore Geospatial API. Anda akan menemukan informasi yang dapat ditawarkan Geospatial API untuk keseluruhan pengalaman AR Anda, dan bagaimana data ini dapat digunakan untuk mendukung pengalaman pencarian arah 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 terhubung ke lokasi dunia nyata.

Yang akan Anda butuhkan

• Perangkat Android yang didukung ARCore, yang terhubung menggunakan kabel USB ke mesin pengembangan Anda, yang 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. Ini akan memberi Anda awal cepat dengan Geospatial API.

1. Mulai Android Studio dan impor project dari VCS.
   • Jika Anda 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 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 bagian Membuat project di Google Cloud Platform.
     
   • Masukkan Project name yang sesuai (misalnya, "ARCore Geospatial API project"), lalu pilih sebuah lokasi.
   • Klik Create.
2. Aktifkan API yang diperlukan:
   • Di sidebar, pilih API & Layanan, lalu Library.
   • Telusuri ARCore API.
   • Klik Enable.
   • Kembali ke Koleksi.
   • Telusuri Maps SDK for Android.
   • Klik Enable.
3. Membuat kredensial Kunci API:
   • Di bagian APIs & Services, pilih Credentials.
   • Di panel atas, klik Create Credentials, lalu pilih API Key.
   • Catat kunci yang telah 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 Anda siap untuk 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 disimpan di com.google.android.geo.API_KEY akan memberikan otorisasi kepada aplikasi ini untuk menggunakan Google Maps SDK.

Memverifikasi project

Pastikan project Anda sudah siap. Di Android Studio, jalankan aplikasi. 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, pastikan 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 memberi Anda GeospatialPose yang berisi informasi berikut:

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

Menampilkan informasi pemosisian di peta

Anda dapat menggunakan GeospatialPose yang disimpan di cameraGeospatialPose untuk memindahkan penanda di peta yang menunjukkan lokasi pengguna. Lanjutkan dari tempat terakhir yang Anda tinggalkan dan tambahkan hal 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. Tanda panah juga harus menunjuk ke arah yang benar: bila Anda secara fisik menghadap ke Utara, tanda panah juga mengarah ke Utara.

4. Menempatkan anchor menggunakan koordinat Earth

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

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

Menetapkan tindakan saat peta diketuk

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

Memastikan objek Earth dapat digunakan

Sebelum membuat anchor di Earth, pastikan bahwa TrackingState objek Earth adalah TRACKING, yang berarti posisi Bumi telah diketahui. Pastikan juga EarthState-nya adalah ENABLED, yang berarti tidak ada masalah yang ditemukan 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 memastikan bahwa objek Earth sedang dilacak, lepaskan earthAnchor sebelumnya, jika ada. Anda mengganti earthAnchor dengan anchor baru di langkah berikutnya:

earthAnchor?.detach()

Kemudian, gunakan cameraGeospatialPose untuk menentukan ketinggian anchor baru. Gunakan pasangan koordinat dengan 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 geodesi dengan rotasi tertentu. Jangkar ini berusaha tetap stabil dan tetap sesuai koordinat dan ketinggian yang ditentukan.

Variabel [qx, qy, qz, qw] menentukan rotasi anchor yang dinyatakan dalam kuarternion, dalam sistem koordinat East-Up-South (EUS). Anda menggunakan nilai yang berbeda untuk memutar anchor, tetapi dalam contoh ini, gunakan angka empat unit untuk rotasi default. Rotasi angka empat unit memiliki jangkar yang berorientasi pada 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 penanda ditempatkan:

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

Cobalah

Di Android Studio, klik Play. Pegang perangkat Anda, lalu 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 bersifat tetap ke lokasi dunia nyata. Coba tempatkan anchor di dekat lokasi saat ini sehingga Anda dapat melihatnya dalam tampilan AR. Aplikasi tersebut harus tetap stabil saat Anda menjelajahi 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 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