Panduan developer Cloud Anchors untuk Android NDK (C)

Pelajari cara menggunakan Cloud Anchor di aplikasi Anda sendiri.

Prasyarat

Pastikan Anda memahami konsep dasar AR dan cara mengonfigurasi sesi ARCore sebelum melanjutkan.

Jika Anda baru menggunakan Cloud Anchor, pastikan Anda memahami cara kerja anchor dan Cloud Anchor.

Mengaktifkan ARCore API

Sebelum menggunakan Cloud Anchors di aplikasi, Anda harus mengaktifkan ARCore API terlebih dahulu di aplikasi Anda.

Mengaktifkan kemampuan Cloud Anchor dalam konfigurasi sesi

Setelah fungsi Cloud Anchors diaktifkan di aplikasi Anda, aktifkan kemampuan Cloud Anchors di konfigurasi sesi AR aplikasi Anda agar dapat berkomunikasi dengan ARCore API:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Menghosting Cloud Anchor

Hosting dimulai dengan panggilan ke ArSession_hostCloudAnchorAsync(). ARCore akan mengupload data visual, pose perangkat, dan pose anchor ke ARCore API. API kemudian memproses informasi ini untuk membuat peta fitur 3D, yang pada akhirnya menampilkan ID Cloud Anchor unik untuk anchor ke perangkat.

Anda juga dapat memperpanjang masa pakai anchor yang dihosting menggunakan ARCore Cloud Anchor Management API.

Aplikasi Anda harus mengikuti langkah-langkah berikut untuk menyelesaikan hosting Cloud Anchor:

  1. Panggil ArSession_hostCloudAnchorAsync().
  2. Tunggu callback, atau terus periksa status Future hingga selesai.
  3. Memeriksa status hasil untuk menentukan apakah operasi berhasil, atau menginterpretasikan kode kesalahan jika gagal.
  4. Bagikan hasil ID Cloud Anchor kepada klien lain, lalu gunakan untuk me-resolve Cloud Anchor dengan ArSession_resolveCloudAnchorAsync()

Memeriksa kualitas pemetaan titik fitur

ArFeatureMapQuality menunjukkan kualitas titik fitur yang dilihat oleh ARCore dalam beberapa detik sebelumnya dari pose kamera tertentu. Cloud Anchors yang dihosting menggunakan fitur berkualitas lebih tinggi umumnya dapat diselesaikan dengan lebih akurat. Gunakan ArSession_estimateFeatureMapQualityForHosting() untuk mendapatkan estimasi kualitas peta fitur untuk pose kamera tertentu.

Nilai Deskripsi
INSUFFICIENT Kualitas titik fitur yang diidentifikasi dari pose dalam beberapa detik sebelumnya termasuk rendah. Status ini menunjukkan bahwa ARCore kemungkinan akan lebih sulit me-resolve Cloud Anchor. Dorong pengguna untuk memindahkan perangkat agar posisi Cloud Anchor yang ingin dihosting dapat dilihat dari berbagai sudut.
SUFFICIENT Kualitas titik fitur yang diidentifikasi dari pose dalam beberapa detik sebelumnya kemungkinan cukup bagi ARCore untuk berhasil me-resolve Cloud Anchor, meskipun akurasi pose yang di-resolve kemungkinan akan berkurang. Dorong pengguna untuk memindahkan perangkat agar posisi Cloud Anchor yang ingin dihosting dapat dilihat dari berbagai sudut.
GOOD Kualitas titik fitur yang diidentifikasi dari pose dalam beberapa detik sebelumnya kemungkinan cukup bagi ARCore untuk berhasil me-resolve Cloud Anchor dengan tingkat akurasi yang tinggi.

Menyelesaikan anchor yang dihosting sebelumnya

Panggil ArSession_resolveCloudAnchorAsync() untuk me-resolve Cloud Anchor yang dihosting. ARCore API secara berkala membandingkan fitur visual dari adegan terhadap peta fitur 3D anchor untuk menunjukkan posisi dan orientasi pengguna terkait anchor. Jika menemukan kecocokan, API akan menampilkan pose Cloud Anchor yang dihosting.

Anda dapat memulai penyelesaian untuk beberapa Cloud Anchor secara berurutan. Hingga 40 operasi Cloud Anchor serentak dapat dilakukan dalam satu waktu.

Membatalkan operasi atau menghapus Cloud Anchor

Panggil ArFuture_cancel() untuk membatalkan operasi Cloud Anchor yang tertunda. Panggil ArAnchor_detach() untuk menghentikan pelacakan dan melupakan Cloud Anchor yang sudah diselesaikan. Referensi ke anchor harus dirilis secara terpisah dengan memanggil ArAnchor_release().

Memeriksa status hasil operasi Cloud Anchor

Gunakan ArCloudAnchorState untuk memeriksa status hasil dari hosting atau penyelesaian operasi, termasuk error.

Nilai Deskripsi
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND Penyelesaian gagal karena ARCore API tidak dapat menemukan ID Cloud Anchor yang diberikan.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Hosting gagal karena server tidak berhasil memproses set data untuk anchor tersebut. Coba lagi setelah perangkat mengumpulkan lebih banyak data dari lingkungan.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API tidak dapat dijangkau. Ini dapat terjadi karena beberapa alasan. Perangkat mungkin dalam mode pesawat atau tidak memiliki koneksi Internet yang berfungsi. Waktu permintaan yang dikirimkan ke server mungkin telah habis tanpa respons. Mungkin ada koneksi jaringan yang buruk, ketidaktersediaan DNS, masalah firewall, atau hal lainnya yang mungkin memengaruhi kemampuan perangkat untuk terhubung ke ARCore API.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Tugas hosting atau penyelesaian untuk anchor ini selesai dengan error internal. Aplikasi tidak boleh mencoba memulihkan dari error ini.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Lihat Memecahkan masalah terkait otorisasi ARCore API.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Cloud Anchor tidak dapat diselesaikan karena versi SDK yang digunakan untuk me-resolve anchor lebih baru dari, dan tidak kompatibel dengan, versi yang digunakan untuk menghostingnya.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Cloud Anchor tidak dapat diselesaikan karena versi SDK yang digunakan untuk me-resolve anchor lebih lama dari, dan tidak kompatibel dengan, versi yang digunakan untuk menghostingnya.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED Aplikasi telah menghabiskan kuota permintaan yang dialokasikan untuk project Google Cloud yang ditentukan. Anda sebaiknya meminta kuota tambahan ARCore API untuk project Anda dari Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS Tugas hosting atau penyelesaian untuk anchor ini berhasil diselesaikan.

Kuota API untuk permintaan host dan penyelesaian

ARCore API memiliki kuota berikut untuk bandwidth permintaan:

Jenis kuota Maksimum Durasi Berlaku untuk
Jumlah anchor tak terbatas T/A project
Permintaan host anchor 30 menit Alamat IP dan project
Anchor permintaan resolve 300 menit Alamat IP dan project

Praktik terbaik untuk pengalaman pengguna yang baik

Minta pengguna untuk melakukan hal berikut guna memastikan pengalaman pengguna yang baik di aplikasi Anda:

  • Tunggu beberapa detik setelah sesi dimulai sebelum mencoba menghosting anchor (dengan menempatkan objek, dll.). Hal ini memberi waktu pada pelacakan untuk stabil.
  • Saat memilih lokasi untuk menghosting anchor, coba temukan area dengan fitur visual yang mudah dibedakan satu sama lain. Untuk hasil terbaik, hindari permukaan reflektif atau permukaan yang tidak memiliki fitur visual, seperti dinding putih kosong.
  • Pastikan kamera tetap terlatih di pusat minat dan gerakkan perangkat pusat minat untuk memetakan lingkungan dari sudut yang berbeda, dengan mempertahankan jarak fisik yang kurang lebih sama. Hal ini akan membantu menangkap lebih banyak data visual dan membuat penyelesaian menjadi lebih andal.

  • Pastikan ada pencahayaan yang cukup di lingkungan nyata saat menghosting dan me-resolve Cloud Anchors.

Kebijakan penghentian layanan

  • Aplikasi yang dibangun dengan ARCore SDK 1.12.0 atau yang lebih tinggi tercakup dalam kebijakan penghentian penggunaan Cloud Anchor API.
  • Aplikasi yang di-build dengan ARCore SDK 1.11.0 atau yang lebih lama tidak dapat menghosting atau me-resolve Cloud Anchors karena SDK tersebut menggunakan ARCore API lama yang tidak digunakan lagi.

Langkah berikutnya