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 baru memberikan aspek baru pada Augmented Reality, yang memungkinkan Anda menempatkan titik jalan Augmented Reality khusus lokasi di sekitar bangunan 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 penunjuk 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 terpasang ke lokasi dunia nyata.

Yang Anda butuhkan

• Perangkat Android yang didukung ARCore, terhubung menggunakan kabel USB ke mesin pengembangan Anda, dikonfigurasi dengan proses debug USB.
• Android Studio yang diinstal dan dikonfigurasi untuk membangun aplikasi Android.
• Layanan Google Play untuk AR 1.31 atau yang lebih baru, 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 dengan cepat 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, lalu 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 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, "Project ARCore Geospatial API"), lalu pilih sebuah lokasi.
   • Klik Buat.
2. Aktifkan API yang diperlukan:
   • Di sidebar, pilih APIs & Services, lalu Library.
   • Telusuri ARCore API.
   • Klik Enable.
   • Kembali ke Koleksi.
   • Telusuri Maps SDK for Android.
   • Klik Enable.
3. Buat kredensial Kunci API:
   • Di bagian API & Layanan, pilih Kredensial.
   • 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 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 telah dibuat di project Google Cloud Anda.

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 akan memberikan otorisasi kepada aplikasi ini untuk menggunakan Google Maps SDK.

Memverifikasi project Anda

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

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

Menampilkan informasi penentuan posisi di peta

Anda dapat menggunakan GeospatialPose yang disimpan di cameraGeospatialPose untuk memindahkan penanda di 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
)

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

Cobalah

Di Android Studio, klik Play. Angkat perangkat Anda dan gerakkan untuk membantu ARCore menetapkan pelacakan. Setelah beberapa saat, Anda akan melihat penanda hijau muncul di peta. Penanda ini berputar saat Anda melihat lingkungan sekitar. Panah juga harus mengarah ke arah yang benar: saat Anda menghadap ke Utara, panah juga mengarah ke Utara.

4. Menempatkan penanda menggunakan koordinat Bumi

Geospatial API dapat menempatkan Anchor pada pasangan koordinat dan rotasi apa pun di dunia nyata. Dengan demikian, pengguna Anda dapat melihat konten yang ditambatkan saat mengunjungi lokasi tertentu.

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 garis 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 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 penanda baru pada langkah berikutnya:

earthAnchor?.detach()

Kemudian, gunakan cameraGeospatialPose untuk menentukan ketinggian untuk penanda 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 ditetapkan ke koordinat dan ketinggian yang ditentukan.

Variabel [qx, qy, qz, qw] menentukan rotasi penanda yang dinyatakan dalam quaternion, dalam sistem koordinat East-Up-South (EUS). Anda menggunakan nilai yang berbeda untuk memutar titik anchor, tetapi dalam contoh ini, gunakan quaternion unit untuk rotasi default. Rotasi quaternion unit memiliki anchor yang berorientasi sehingga X+ mengarah ke timur, Y+ mengarah ke atas menjauhi pusat bumi, dan Z+ mengarah ke selatan.

Menampilkan penanda yang ditempatkan di peta

Terakhir, pindahkan penanda baru yang menunjukkan tempat penanda diletakkan:

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

Cobalah

Di Android Studio, klik Play. Angkat perangkat Anda, dan gerakkan untuk membantu ARCore menetapkan 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 letakkan penanda di dekat lokasi Anda saat ini agar Anda dapat melihatnya di tampilan AR. Layar 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