Mulai menggunakan Geospatial Creator di Unity

ARCore Geospatial Creator untuk Unity memungkinkan Anda melihat pratinjau konten Geospasial di Editor Unity dengan menampilkan data Google Maps dalam format petak 3D baru. Hal ini membantu Anda memvisualisasikan tempat konten akan ditempatkan di dunia nyata, saat Anda membangun aplikasi.

Geospatial Creator tersedia sebagai bagian dari ARCore Extensions untuk AR Foundation. Panduan Memulai ini akan menunjukkan cara menggunakan Geospatial Creator di Unity untuk menambahkan konten AR geospasial ke aplikasi contoh Geospatial ARCore.

Jika Anda memiliki aplikasi yang sudah ada dan ingin digunakan sebagai pengganti Geospatial Sample, Anda harus mengikuti panduan Developer Geospatial untuk Unity terlebih dahulu. Setelah aplikasi Anda dikonfigurasi untuk menggunakan Geospatial API, lewati langkah Tambahkan Dependensi yang Diperlukan di bawah dan lanjutkan dari sana.

Prasyarat

Ikuti "Mulai menggunakan ARCore Extensions for AR Foundation" untuk mengonfigurasi lingkungan Unity Anda guna membuat pengalaman AR.

Meskipun ARCore Extensions mendukung Unity versi yang lebih lama, Geospatial Creator memerlukan Unity 2021.3 atau yang lebih baru.

Otorisasi API

Anda harus menyiapkan akses API untuk menggunakan ARCore Geospatial API dan Google Map Tiles API.

Google Map Tiles API

Map Tiles API menyediakan representasi 3D fotorealistik dari lokasi yang didukung. Kita akan menggunakan petak ini di Unity Editor untuk melihat pratinjau area di sekitar adegan AR Anda.

Lihat halaman Map Tiles API untuk mengaktifkan API dan mempelajari Map Tiles lebih lanjut.

ARCore Geospatial API

ARCore Geospatial API digunakan oleh aplikasi Anda saat runtime untuk membuat dan berinteraksi dengan Anchor Geospatial.

Untuk mengaktifkan Geospatial API, siapkan ARCore API di aplikasi Anda. Anda dapat menggunakan metode otorisasi Tanpa Kunci (direkomendasikan) atau Kunci API.

Memperluas aplikasi Contoh Geospatial

Dalam panduan ini, kami akan menunjukkan cara menggunakan Geospatial Creator untuk menambahkan konten geospasial ke aplikasi Contoh Geospasial ARCore.

Mengonfigurasi Contoh Geospatial

Pertama, pelajari aplikasi contoh Geospatial ARCore. Di project Unity baru, buka Unity Package Manager dan pilih paket ARCore Extensions. Di panel detail Package Manager, luaskan Samples dan impor Geospatial Sample ke project Unity Anda.

Sebelum menjalankan aplikasi, Anda harus mengaktifkan fungsi ARCore dan Geospatial di project Anda. Gunakan Edit > Project Settings... > XR Plug-in Management. Centang kotak yang sesuai untuk mengaktifkan penyedia plugin ARCore untuk Android dan/atau penyedia plugin ARKit untuk iOS.

Kemudian, dari Edit > Project Settings... > XR Plug-in Management, buka panel ARCore Extensions. Pastikan "Geospatial" dicentang (Anda belum perlu mengaktifkan Geospatial Creator), lalu masukkan kredensial API Anda. Lihat dokumentasi "Mengaktifkan Geospatial Unity API" untuk Android dan iOS untuk mengetahui detail selengkapnya.

Ada beberapa setelan Player khusus platform lainnya yang diperlukan untuk aplikasi Unity yang menggunakan ARCore. Lihat bagian Mengonfigurasi Setelan Pemutar di dokumen kami untuk mengetahui perubahan yang diperlukan.

Pada tahap ini, tidak ada objek game dalam adegan Anda selain yang diperlukan untuk menjalankan Contoh Geospasial. Sekarang adalah saat yang tepat untuk membangun dan menjalankan aplikasi. Jika dikonfigurasi dengan benar, saat runtime, aplikasi akan menampilkan tampilan kamera perangkat Anda. Saat Anda bergerak, akurasi geospasial yang ditampilkan di bagian atas layar akan mulai meningkat. Dengan mengetuk layar, Anda akan membuat Anchor Geospatial yang akan tetap berada di lokasi aslinya saat Anda bergerak.

Selanjutnya, kita akan menunjukkan cara menggunakan Geospatial Creator untuk membuat dan memvisualisasikan konten AR canggih dari dalam Editor Unity. Konten ini akan muncul di aplikasi Anda di lokasi lintang / bujur tertentu di dunia.

Menambahkan dependensi yang diperlukan

Geospatial Creator menggunakan paket Unity pihak ketiga yang disebut Cesium untuk merender Petak Peta Google di jendela Scene Unity Editor. Sebelum mengaktifkan fitur Geospatial Creator, mari tambahkan paket Cesium ke project Anda.

Sebaiknya instal versi terbaru paket Cesium for Unity dari halaman GitHub Cesium:

1. Download versi terbaru .tgz Cesium yang telah dikompilasi sebelumnya untuk Unity dari halaman Rilis GitHub mereka. Versi paket Cesium for Unity yang direkomendasikan saat ini adalah 1.1.0.
2. Buka Unity Package Manager dengan mengklik menu "Window" Unity, lalu pilih "Package Manager".
3. Klik ikon "+", lalu pilih "Add package from tarball".
4. Pilih file .tgz Cesium for Unity yang didownload di Langkah 1.
5. Anda mungkin diminta untuk menginstal dependensi tambahan, seperti Text Mesh Pro.

Mengaktifkan Geospatial Creator

Sekarang Anda siap mengaktifkan Geospatial Creator:

1. Dari dialog Build Settings, pastikan platform yang Anda pilih adalah "Android" atau "iOS". Fitur Geospatial Creator saat ini tidak tersedia untuk platform lain.
2. Buka Project Settings > XR Plug-in Management > ARCore Extensions.
3. Jika Anda tidak menetapkan kunci API Android dan/atau iOS ARCore di langkah sebelumnya, pastikan untuk melakukannya sekarang.
4. Aktifkan tombol "Geospatial" dan "Geospatial Creator". Setelah mengklik untuk mengaktifkan tombol Geospatial Creator, wizard non-modal akan ditampilkan untuk mengonfirmasi bahwa project Anda kompatibel dengan Geospatial Creator.
5. Klik "Selesai" di wizard.

Setelah menyelesaikan wizard, Unity akan memicu kompilasi skrip Anda. Tunggu hingga rekompilasi selesai sebelum melanjutkan. (Jika platform yang Anda pilih bukan "Android" atau "iOS", beralihlah ke salah satu platform tersebut sekarang.)

Menambahkan Asal Geospatial Creator dengan Petak Peta

Adegan Anda memerlukan tepat satu objek "Asal Pembuat Geospatial". Objek ini digunakan sebagai titik referensi untuk mengonversi nilai garis lintang, garis bujur, dan ketinggian dunia nyata ke koordinat game Unity.

Untuk menambahkan Geospatial Creator Origin ke adegan Anda, pilih Game Object > XR > Geospatial Creator Origin. Objek yang baru dibuat memerlukan georeferensi, yang menghubungkan lintang, bujur, dan ketinggian tertentu ke posisi asal dalam koordinat game. Dari panel Inspector Geospatial Creator Origin, tambahkan georeferensi dengan mengklik tombol Add Cesium Georeference Component.

Catatan: Jika menu GameObject > XR tidak menyertakan Geospatial Creator Origin, pastikan Anda membangun untuk Android atau iOS, dan Anda telah mengaktifkan tombol Geospatial dan Geospatial Creator di panel Project Settings > XR Plug-in Management > ARCore Extensions.

Selain menjadi titik referensi untuk objek AR Anda, Cesium Georeference menambahkan objek Cesium 3D Tileset ke adegan. Objek ini akan merender Petak Peta Google di Tampilan Scene Editor, sehingga Anda dapat memvisualisasikan lokasi persis di mana konten AR Anda akan muncul. Ada kolom di pemeriksa Asal Geospatial Creator untuk menambahkan kunci API Map Tiles yang Anda siapkan sebelumnya. Setelah menetapkan kunci ini, Anda akan melihat petak peta dimuat di tampilan Scene.

Sekarang ubah kolom lintang, bujur, dan tinggi agar berlokasi di dekat tempat Anda ingin konten AR muncul di aplikasi Anda.

Tips: Anda dapat menemukan lintang dan bujur sebagian besar lokasi dengan menemukan lokasi tersebut di Google Maps dan mengklik kanan. Memilih lintang dan bujur dari menu konteks akan menyalin nilai ke papan klip Anda.

Tampilan Scene di Editor kini akan menampilkan kartu peta di lintang dan bujur asal yang ditentukan. Saat runtime, kami mengasumsikan aplikasi Anda akan menggunakan Kamera AR, sehingga Geospatial Creator telah mengonfigurasi objek Cesium 3D Map Tileset dengan tag "EditorOnly". Oleh karena itu, petak tidak akan didownload atau dirender saat runtime di game Anda. Hal ini dapat diubah dari pemeriksa objek Cesium3DTileset. Untuk mempelajari lebih lanjut Georeferensi Cesium dan GameObject Tileset 3D, lihat dokumentasi Cesium for Unity.

Tips: Konten Tampilan Scene Anda, termasuk petak peta, dapat terhalang oleh elemen UI aplikasi Anda. Anda dapat menyembunyikan lapisan UI di Scene View Editor, tanpa menonaktifkan UI saat runtime, menggunakan menu drop-down Layers di sudut kanan atas Unity Editor.

Menambahkan dan menempatkan Geospatial Creator Anchor

Sekarang Anda siap menempatkan konten AR di adegan Anda. Klik GameObject > XR > Geospatial Creator Anchor untuk menambahkan penanda ke hierarki adegan Anda. Dari pemeriksa Anchor, Anda dapat menentukan lintang, bujur, dan ketinggian yang tepat. Transformasi objek akan segera diperbarui ke posisi yang benar di adegan Anda, dan Anda dapat melihat dengan tepat di mana objek akan muncul di dunia.

Saat Anda menyesuaikan lintang dan bujur penanda, pilih tempat yang berada di dekatnya sehingga Anda dapat memvalidasi bahwa penanda berada di tempat yang benar saat runtime. Saat menetapkan ketinggian Anchor Geospatial Creator, Anda memiliki tiga opsi:

• Medan menempatkan anchor di permukaan tanah pada lintang dan bujur yang ditentukan. Tingkat permukaan ditentukan saat runtime oleh Sistem Pemosisian Visual. Jika Anda baru menggunakan Geospatial API ARCore, "Terrain" adalah pilihan yang tepat, karena penanda akan diselesaikan langsung di tanah dengan tingkat akurasi vertikal yang tinggi. Kolom "Offset Ketinggian" memungkinkan Anda memosisikan penanda di atas atau di bawah permukaan tanah dengan jumlah tetap, dalam meter. Misalnya, menentukan offset "1.0" akan menyebabkan anchor "mengambang" satu meter di atas medan.
• Atap menempatkan anchor relatif terhadap bagian atas struktur apa pun pada garis lintang dan bujur yang ditentukan. Seperti anchor medan, kolom "Offset Ketinggian" memungkinkan Anda memindahkan anchor ke atas atau ke bawah relatif terhadap posisi atap, dalam meter.
• WGS84 menempatkan penanda pada ketinggian absolut tertentu, dalam meter, berdasarkan sistem koordinat WGS84. Penempatan objek dengan cara ini mungkin memerlukan beberapa kali percobaan, karena ketinggian "0" di WSG84 tidak selalu menunjukkan permukaan laut rata-rata dan mungkin tidak sesuai dengan ketinggian GPS. Selain itu, meskipun garis lintang dan bujur petak 3D yang dirender sangat akurat, upaya untuk menempatkan objek di permukaan tanah menggunakan petak 3D sebagai referensi dapat menyebabkan error ketinggian hingga beberapa meter.

Untuk mempelajari lebih lanjut berbagai jenis Anchor Geospasial ARCore, lihat Panduan Developer Geospasial.

Anchor medan dan atap memiliki kolom Ketinggian WGS84. Nilai ini hanya digunakan dalam mode Editor, untuk menetapkan tinggi objek dalam Tampilan Scene. Ketinggian medan dan atap ditentukan hanya saat runtime, sehingga kolom Ketinggian WGS84 memungkinkan Anda memvisualisasikan penanda pada ketinggian tertentu saat mengembangkan aplikasi. Kolom Ketinggian WGS84 diabaikan saat runtime untuk penanda medan dan atap.

Menambahkan Geometri ke anchor

Jika Anda membangun dan menjalankan aplikasi sekarang, Anda tidak akan melihat penanda di aplikasi yang mendukung AR. Hal ini karena tidak ada geometri yang dilampirkan padanya. Mari tambahkan primitif 3D sederhana ke penanda: Di hierarki adegan, klik kanan objek Penanda Geospatial Creator AR Anda. Dari menu konteks, pilih Objek 3D > Kubus. Anda akan melihat kubus abu-abu di tampilan adegan sebagai turunan dari penanda Anda. Jika Anda memutuskan untuk memindahkan posisi atau rotasi objek di Editor, sebaiknya pindahkan objek Anchor root, bukan primitif Cube turunan. Hal ini akan membantu mengurangi kesalahan dalam terjemahan dari garis lintang / bujur ke koordinat game.

Tentu saja, Anda juga dapat menambahkan geometri yang lebih rumit dan komponen serta turunan arbitrer ke anchor.

Membuat dan menjalankan aplikasi

Sekarang saatnya melihat penanda Anda di dunia nyata. Coba bangun dan jalankan aplikasi Anda, lalu pindah ke lokasi tempat Anda ingin melihat kubus. Apakah ada di sana? Selamat, Anda siap membuat pengalaman AR yang lebih kompleks dengan Geospatial Creator.

Jika Anda mengalami masalah, lihat Panduan Pemecahan Masalah.

Sekarang adalah saat yang tepat untuk menambahkan AR Geospatial Creator Anchor tambahan dengan geometri yang berbeda. Coba bereksperimen dengan beberapa anchor atap dan medan serta offsetnya. Tambahkan skrip untuk menganimasikan atau mengaktifkan interaksi dengan objek.

Memahami Anchor Geospatial Creator dan class ARGeospatialAnchor

Saat membuat pengalaman AR yang kompleks dan interaktif, akan sangat membantu jika Anda memahami hubungan antara Anchor Geospatial Creator dan class C# ARGeospatialAnchor ARCore:

ARGeospatialAnchor hanya dapat dibuat saat runtime dengan memanggil salah satu fungsi di ARAnchorManager, dan hanya dapat dibuat setelah sesi AR stabil. Anchor Geospatial Creator dapat dianggap sebagai placeholder yang ada di adegan Anda, menunggu sesi AR siap untuk menyelesaikan objek ARGeospatialAnchor. Setelah sesi siap, placeholder akan otomatis memanggil ARAnchorManager untuk membuat dan menyelesaikan ARGeospatialAnchor.

Segera setelah anchor runtime diselesaikan, Geospatial Creator Anchor dalam hierarki adegan Anda akan dilampirkan sebagai turunan ke GameObject baru. Artinya, setiap komponen atau turunan Anchor Geospatial Creator akan menjadi subkomponen atau cucu dari GameObject ARGeospatialAnchor yang baru. Misalnya, transform dari primitif geometri yang terlampir pada Geospatial Creator Anchor akan diwarisi dari transform ARGeospatialAnchor, dan oleh karena itu akan ditempatkan di lokasi yang diharapkan dalam sesi AR runtime.

Jika Anda perlu mengidentifikasi GameObject ARGeospatialAnchor tertentu saat runtime, Anda dapat menelusuri adegan untuk mencari objek yang properti name-nya cocok dengan penanda yang dibuat menggunakan Geospatial Creator. Jika sesi AR diinisialisasi, parent objek tersebut akan menjadi objek ARGeospatialAnchor yang sesuai.

Pemecahan masalah

Mengapa penanda saya berpindah?

Anda mungkin melihat, terutama saat aplikasi pertama kali diluncurkan, bahwa penanda dapat tampak "bergeser" perlahan, atau bahkan melompat beberapa meter secara tiba-tiba. Hal ini terjadi saat sesi VPS masih menentukan dan menyempurnakan lokasi presisi kamera. Seiring peningkatan akurasi horizontal dan vertikal di beberapa frame, penanda akan digambar ulang di lokasi yang lebih akurat, sehingga memberikan ilusi gerakan. Anda mungkin ingin merender objek secara berbeda (atau tidak sama sekali) hingga akurasi lokasi mencapai nilai minimum tertentu. Untuk melakukannya, Anda dapat membuat kueri properti ARCoreEarthManager.CameraGeospatialPose untuk menentukan akurasi update frame saat ini.

Mengapa penanda saya muncul di ketinggian yang salah?

Saat menggunakan jenis ketinggian "Manual" untuk Anchor Geospatial Creator, ketinggian anchor akan ditetapkan (dalam meter) sesuai dengan WGS84. Di lokasi tertentu, mungkin ada perbedaan hingga beberapa meter antara permukaan tanah yang tampak dalam ubin peta dan permukaan tanah sebenarnya seperti yang dilaporkan oleh Sistem Pemosisian Visual (VPS) Google. Jika Anchor Geospatial tampak salah ditempatkan saat runtime, sebaiknya validasi ketinggian VPS secara langsung menggunakan overlay pen-debugan di aplikasi contoh. Kemudian, Anda dapat mengubah ketinggian di Unity Editor agar sesuai dengan ketinggian VPS yang diketahui di lokasi tersebut.

Petak peta tidak dirender dengan benar di Tampilan Scene Editor

Jika Cesium3DTileset tampak memuat petak, tetapi dirender dalam magenta solid di tampilan adegan, tambahkan paket Shader Graph Unity ke project Anda. Paket ini diperlukan oleh Cesium, meskipun project yang menggunakan renderer bawaan Unity tidak menyertakannya secara default.

Untuk menambahkan Shader Graph, buka Unity Package Manager (Window > Package Manager). Pastikan Anda menjelajahi paket yang tersedia di Unity Package Registry dengan memilih "Packages: Unity Registry" dari menu dropdown di bagian atas jendela Package Manager. Telusuri paket com.unity.shadergraph dan instal versi terbarunya. Setelah paket dimuat, petak 3D akan dimuat ulang dan dirender dengan benar di Tampilan Scene.

Aplikasi menampilkan layar hitam saat runtime, bukan tampilan kamera

Universal Rendering Pipeline (URP) Unity tidak dikonfigurasi untuk Kamera AR secara default. Jika Anda melihat layar hitam saat runtime, bukan output kamera, Anda perlu menambahkan AR Background Renderer Feature ke setiap Renderer URP di adegan Anda.

Untuk menambahkan fitur, telusuri "renderer" di project Anda. Untuk setiap objek URP Renderer, klik tombol "Add Renderer Feature" di Inspector dan tambahkan AR Background Renderer.

Mengapa Anchor yang ditempatkan jauh dari titik asal tampak ditempatkan dengan tidak benar?

Konversi dari koordinat WGS84 ke koordinat game Unity dapat mengalami error karena presisi aritmetika floating point, yang dapat diminimalkan dengan memastikan asal Anda berada di dekat anchor AR Anda. Jarak lebih dari 20 km dapat menyebabkan ketidakakuratan. Sebaiknya gunakan beberapa adegan, dengan penanda unik di setiap adegan, jika pengalaman AR Anda mencakup jarak yang jauh.