Unity için Cloud Anchor geliştirici kılavuzu (AR Foundation)

Cloud Anchors'ı kendi uygulamalarınızda nasıl kullanacağınızı öğrenin.

Ön koşullar

Devam etmeden önce temel AR kavramlarını ve ARCore oturumunu nasıl yapılandıracağınızı anladığınızdan emin olun.

Cloud Anchors'ı kullanmaya yeni başladıysanız sabit noktaların ve Cloud Anchors'ın nasıl çalıştığını anladığınızdan emin olun.

ARCore API'yi etkinleştirme

Cloud Anchors'ı uygulamanızda kullanmadan önce uygulamanızda ARCore API'yi etkinleştirmeniz gerekir.

Oturum yapılandırmasında Cloud Anchor özelliklerini etkinleştirme

Uygulamanızda Cloud Anchors işlevi etkinleştirildikten sonra, ARCore API ile iletişim kurabilmesi için uygulamanızın AR oturumu yapılandırmasında Cloud Anchors özelliklerini etkinleştirin:

Cloud Anchor'u Barındırın

Barındırma, ARAnchorManager.HostCloudAnchorAsync() aramasıyla başlar. ARCore, görsel verileri, cihazın duruşunu ve ankraj duruşunu ARCore API'ye yükler. Ardından API, 3D özellik haritası oluşturmak için bu bilgileri işler ve sonuç olarak cihaza sabitleme için benzersiz bir Cloud Anchor kimliği döndürür.

ARCore Cloud Anchor Management API'yi kullanarak barındırılan bir ankrajın ömrünü de uzatabilirsiniz.

Uygulamanız, Cloud Anchor'ın barındırılmasını tamamlamak için aşağıdaki adımları uygulamalıdır:

  1. ARAnchorManager.HostCloudAnchorAsync() numaralı telefonu arayın.
  2. Promise bir sonuç verene kadar beklemek için bir coroutine başlatın. Daha fazla bilgi için Unity'de eşzamanlı olmayan rutinler başlıklı makaleyi inceleyin.
  3. İşlemin başarılı olup olmadığını belirlemek için sonuç durumunu kontrol edin veya başarısızsa hata kodunu yorumlayın.
  4. Elde edilen Cloud Anchor Kimliği'ni diğer istemcilerle paylaşın ve ARAnchorManagerExtensions.ResolveCloudAnchorAsync() ile Cloud Anchor sorununu çözmek için bu kimliği kullanın.

Özellik noktalarının eşleme kalitesini kontrol etme

ARCoreExtensions.FeatureMapQuality, ARCore'un belirli bir kamera pozundan önceki birkaç saniye içinde gördüğü özellik noktalarının kalitesini gösterir. Daha yüksek kaliteli özellikler kullanılarak barındırılan Cloud Anchor'lar, genellikle daha doğru şekilde çözümlenir. Belirli bir kamera pozu için özellik haritası kalitesinin tahminini almak üzere ARAnchorManagerExtensions.EstimateFeatureMapQualityForHosting() öğesini kullanın.

Değer Açıklama
Insufficient Önceki birkaç saniyedeki duruştan tanımlanan özellik noktalarının kalitesi düşük. Bu durum, ARCore'un Cloud Anchor'ı çözme konusunda daha fazla zorluk yaşayacağını gösterir. Kullanıcıyı, barındırmak istediği Cloud Anchor'ın istenen konumunun farklı açılardan görüntülenebilmesi için cihazı hareket ettirmeye teşvik edin.
Sufficient Önceki birkaç saniye içinde pozdan tanımlanan özellik noktalarının kalitesi, ARCore'un bir Cloud Anchor'ı başarıyla çözmesi için yeterli olabilir. Ancak çözülen pozun doğruluğu muhtemelen azalır. Kullanıcıyı, barındırmak istediği Cloud Anchor'ın istenen konumunun farklı açılardan görüntülenebilmesi için cihazı hareket ettirmeye teşvik edin.
Good Önceki birkaç saniye içinde pozdan tanımlanan özellik noktalarının kalitesi, ARCore'un bir Cloud Anchor'ı yüksek doğruluk derecesiyle başarıyla çözmesi için yeterli olabilir.

Daha önce barındırılan bir ankrajı çözme

Barındırılan bir Cloud Anchor'ı çözüme kavuşturmak için ARAnchorManagerExtensions.ResolveCloudAnchorAsync() numaralı telefonu arayın. ARCore API, kullanıcının ankraja göre konumunu ve yönünü belirlemek için sahnedeki görsel özellikleri ankrajın 3D özellik haritasıyla düzenli olarak karşılaştırır. API, eşleşme bulduğunda barındırılan Cloud Anchor'ın pozunu döndürür.

Sırayla birden fazla Cloud Anchor'ın çözülmesini başlatabilirsiniz. Aynı anda en fazla 40 eşzamanlı Cloud Anchor işlemi olabilir.

İşlemi iptal etme veya Cloud Anchor'ı kaldırma

ARCloudAnchor bileşeni, kendisini içeren oyun nesnesinden kaldırıldığında ARCloudAnchor.OnDestroy() otomatik olarak çağrılır. Bu işlem, temeldeki yerel Cloud Anchor nesnesini ayırır ve serbest bırakır.

Cloud Anchor işleminin sonuç durumunu kontrol etme

Barındırma veya çözümleme işleminin sonuç durumunu (hatalar dahil) kontrol etmek için CloudAnchorState'i kullanın.

Değer Açıklama
ErrorResolvingCloudIdNotFound ARCore API, sağlanan Cloud Anchor kimliğini bulamadığından çözüm başarısız oldu.
ErrorHostingDatasetProcessingFailed Sunucu, belirtilen ankrajın veri kümesini başarıyla işleyemediğinden barındırma işlemi başarısız oldu. Cihaz ortamdan daha fazla veri topladıktan sonra tekrar deneyin.
ErrorHostingServiceUnavailable ARCore API'ye erişilemiyor. Bu bir dizi nedenden kaynaklanabilir. Cihaz uçak modunda olabilir veya internet bağlantısı çalışmıyor olabilir. Sunucuya gönderilen istek zaman aşımına uğramış ve yanıt alınamamış olabilir. Kötü bir ağ bağlantısı, DNS'nin kullanılamaması, güvenlik duvarı sorunları veya cihazın ARCore API'ye bağlanma özelliğini etkileyebilecek başka bir şey olabilir.
ErrorInternal Bu bağlayıcı için barındırma veya çözümleme görevi dahili bir hatayla tamamlandı. Uygulamanın bu hatadan kurtulmaya çalışmaması gerekir.
ErrorNotAuthorized Uygulama, geçersiz yetkilendirme nedeniyle ARCore API ile iletişim kuramıyor. Geçerli bir yetkilendirme stratejisi için Proje Ayarları > XR > ARCore Uzantıları'nı kontrol edin.
ErrorResolvingPackageTooNew Cloud Anchor'ı çözmek için kullanılan ARCore uzantıları paketi, Cloud Anchor'ı barındırmak için kullanılan sürümden daha yeni ve bu sürümle uyumlu olmadığı için Cloud Anchor çözülemedi.
ErrorResolvingPackageTooOld Cloud Anchor'ı çözmek için kullanılan ARCore uzantıları paketi, Cloud Anchor'ı barındırmak için kullanılan sürümden daha eski ve bu sürümle uyumlu olmadığı için Cloud Anchor çözülemedi.
ErrorResourceExhausted Uygulama, belirli bir Google Cloud projesine ayrılan istek kotasını tüketmiştir. Google Developers Console'dan projenizle ilgili ARCore API'si için ek kota istemeniz gerekir.
Success Bu bağlantı için barındırma veya çözümleme görevi başarıyla tamamlandı.

Barındırma ve çözümleme istekleri için API kotaları

ARCore API'de istek bant genişliği için aşağıdaki kotalar geçerlidir:

Kota türü Maksimum Süre Geçerlilik kapsamı:
Bağlayıcı sayısı sınırsız Yok proje
Sabit barındırma istekleri 30 dakika IP adresi ve proje
Sabit çözüm istekleri 300 dakika IP adresi ve proje

İyi bir kullanıcı deneyimi için en iyi uygulamalar

Uygulamanızda iyi bir kullanıcı deneyimi sağlamak için kullanıcılara aşağıdakileri yapmalarını söyleyin:

  • Sabitleme noktası oluşturmayı denemeden önce oturum başladıktan sonra birkaç saniye bekleyin (ör. bir nesne yerleştirerek). Bu sayede izlemenin kararlı hâle gelmesi için zaman tanınmış olur.
  • Sabitlenecek konumu seçerken birbirinden kolayca ayırt edilebilen görsel özelliklere sahip bir alan bulmaya çalışın. En iyi sonuçlar için yansıtıcı yüzeylerden veya boş beyaz duvarlar gibi görsel özellikleri olmayan yüzeylerden kaçının.

  • Kamerayı ilgi merkezinde eğitimli tutun ve ortamın farklı açılardan haritasını çıkarmak için cihazı ilgi alanı merkezinde hareket ettirin. Bu şekilde fiziksel mesafeyi büyük oranda koruyarak daha fazla görsel veri yakalayabilir ve çözümlemeyi artırabilirsiniz.

  • Cloud Anchor'ları barındırıp çözümlerken, gerçek ortamdaki aydınlatmanın yeterli olduğundan emin olun.

Kullanımdan kaldırma politikası

  • ARCore SDK'sı 1.12.0 veya sonraki sürümler ile oluşturulan uygulamalar, Cloud Anchor API'nin desteğinin sonlandırılması politikası kapsamındadır.
  • ARCore SDK 1.11.0 veya önceki sürümleri ile oluşturulan uygulamalar, SDK'nın eski ve kullanımdan kaldırılmış bir ARCore API'yi kullanması nedeniyle Cloud Anchor'ları barındıramaz veya çözemez.

Sırada ne var?