Android (Kotlin/Java) için Cloud Anchor geliştirici kılavuzu

Cloud Anchor'ı 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:

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, uygulamanızın ARCore API ile iletişim kurabilmesi için AR oturumu yapılandırmasında Cloud Anchor özelliklerini etkinleştirin:

Java

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Kotlin

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Cloud Anchor barındırma

Barındırma, hostCloudAnchorAsync() çağrısı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. hostCloudAnchorAsync() numaralı telefonu arayın.
  2. Geri aramayı bekleyin veya işlem tamamlanana kadar gelecek durumunu sürekli olarak kontrol edin.
  3. İşlemin başarılı olup olmadığını belirlemek için sonuç durumunu kontrol edin veya başarısız olursa hata kodunu yorumlayın.
  4. Sonuç olarak elde edilen Cloud Anchor kimliğini diğer istemcilerle paylaşın ve Cloud Anchor'ı resolveCloudAnchorAsync() ile çözmek için kullanın.

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

Session.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ülür. Belirli bir kamera pozu için özellik haritası kalitesinin tahminini almak üzere Session.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'ı çözmek için 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.

Birden fazla Cloud Anchor için sırayla çözüm başlatabilirsiniz. Aynı anda en fazla 40 eşzamanlı Cloud Anchor işlemi olabilir.

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

Beklemedeki bir Cloud Anchor işlemini iptal etmek için cancel() numaralı telefonu arayın. Önceden çözülmüş bir Cloud Anchor'ı uygulamadan kaldırmak için detach() işlevini çağırın.

Cloud Anchor işleminin sonuç durumunu kontrol etme

Hatalar da dahil olmak üzere barındırma veya çözümleme işleminin sonuç durumunu kontrol etmek için Anchor.CloudAnchorState değerini kullanın.

Değer Açıklama
ERROR_CLOUD_ID_NOT_FOUND ARCore API, sağlanan Cloud Anchor kimliğini bulamadığı için çözümleme başarısız oldu.
ERROR_HOSTING_DATASET_PROCESSING_FAILED 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.
ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API'ye erişilemedi. Bu bir dizi nedenden kaynaklanabilir. Cihaz uçak modunda olabilir veya çalışan bir internet bağlantısı olmayabilir. 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ğlanmasını etkileyebilecek başka herhangi bir şey olabilir.
ERROR_INTERNAL Bu ankraj için barındırma veya çözümleme görevi dahili bir hatayla sonlandırıldı. Uygulama bu hatadan kurtarmaya çalışmamalıdır.
ERROR_NOT_AUTHORIZED Uygulama tarafından sağlanan yetkilendirme geçerli değil. ARCore API yetkilendirmesiyle ilgili sorunları giderme başlıklı makaleyi inceleyin.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Sabitleyiciyi çözmek için kullanılan SDK sürümü, sabitleyiciyi barındırmak için kullanılan sürümden daha yeni ve bu sürümle uyumlu olmadığı için Cloud sabitleyici çözülemedi.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Bağlayıcıyı çözmek için kullanılan SDK sürümü, barındırmak için kullanılan sürümden daha eski ve sürümle uyumsuz olduğundan Cloud Anchor çözülemedi.
ERROR_RESOURCE_EXHAUSTED Uygulama, belirli bir Google Cloud projesine ayrılan istek kotasını tüketmiştir. Google Developers Console'dan projeniz için ARCore API'ye ek kota isteğinde bulunmanız gerekir.
SUCCESS Bu ankraj 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ümleme 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ılardan aşağıdakileri yapmalarını isteyin:

  • Sabitleme noktası oluşturmayı denemeden önce oturum başladıktan sonra birkaç saniye bekleyin (ör. bir nesne yerleştirerek). Bu, izlemenin dengelenmesi için biraz zaman tanır.
  • 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ıtan yüzeylerden veya boş beyaz duvarlar gibi görsel özelliklerin eksik olduğu yüzeylerden kaçının.

  • Kamerayı ilgi alanının üzerinde tutarak ve cihazı ilgi alanının etrafında hareket ettirerek ortamı farklı açılardan haritalandırın. Bu işlemi yaparken yaklaşık olarak aynı fiziksel mesafeyi koruyun. Bu, daha fazla görsel veri yakalamanıza ve çözme işleminin daha güçlü olmasına yardımcı olur.

  • 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ümler ile oluşturulan uygulamalar, SDK'nın desteği sonlandırılmış eski bir ARCore API'si kullanması nedeniyle Cloud Anchor'ları barındıramaz veya çözemez.

Sırada ne var?