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

Temel artırılmış gerçeklik kavramlarını anladığınızdan emin olun ve devam etmeden önce ARCore oturumunun nasıl yapılandırılacağı hakkında daha fazla bilgi edinin.

Cloud Anchor'ları kullanmaya yeni başladıysanız:

ARCore API'yi etkinleştirme

Uygulamanızda Cloud Anchor'ları kullanmadan önce öncelikle uygulamanızda ARCore API'yi etkinleştirmeniz gerekir.

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

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:

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'u Barındırın

Barındırma, hostCloudAnchorAsync() çağrısıyla başlar. ARCore, görsel verileri, cihaz duruşlarını ve sabitleme 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 bağlayıcının kullanım ö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 çağırmayı bekleyin veya işlem tamamlanana kadar Gelecekteki durumu 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. Elde edilen Cloud Anchor Kimliği'ni diğer istemcilerle paylaşın ve Cloud Anchor kimliğini kullanarak resolveCloudAnchorAsync().

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

Session.FeatureMapQuality, belirli bir kamera pozundan önceki birkaç saniye içinde ARCore tarafından görülen ö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 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'ı çözümlemede muhtemelen 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ç saniyede pozda tanımlanan özellik noktalarının kalitesi, ARCore'un bir Cloud Anchor'u başarıyla çözmesi için muhtemelen yeterli olsa da çözülmüş pozun doğruluğu büyük olasılıkla azalacaktı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ç saniyede pozda tanımlanan özellik noktalarının kalitesi, ARCore'un Cloud Anchor'u yüksek doğruluk derecesiyle başarıyla çözmesi için muhtemelen yeterli olacaktır.

Önceden barındırılan bir bağlayıcıyı çözümleme

Barındırılan bir Cloud Anchor'ı çözüme kavuşturmak 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. Çözülmüş bir Cloud Anchor'ı uygulamadan kaldırmak için detach() numaralı telefonu arayın.

Cloud Anchor işleminin sonuç durumunu kontrol etme

Barındırma veya çözümleme işleminin sonuç durumunu (hatalar dahil) kontrol etmek için Anchor.CloudAnchorState'i 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 internet bağlantısı çalışmıyor olabilir. Sunucuya gönderilen istek, yanıt alınmadan zaman aşımına uğramış 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 Sabitleyiciyi çözmek için kullanılan SDK sürümü, sabitleyiciyi barındırmak için kullanılan sürümden eski ve bu sürümle uyumlu olmadığı için Cloud sabitleyici çözülemedi.
ERROR_RESOURCE_EXHAUSTED 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 ankraj için barındırma veya çözümleme görevi başarıyla tamamlandı.

Ana makine 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ılardan aşağıdakileri yapmalarını isteyin:

  • Oturum başladıktan sonra bir bağlayıcı barındırmaya çalışmadan önce birkaç saniye bekleyin (bir nesne vb. yerleştirerek). Bu sayede izlemenin kararlı hâle gelmesi için biraz zaman tanını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 cihazı ilgi alanının etrafında hareket ettirin. Bu sırada, yaklaşık olarak aynı fiziksel mesafeyi koruyarak ortamın haritasını farklı açılardan çıkarın. 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ırken ve çözerken gerçek ortamda yeterli ışık olduğundan emin olun.

Kullanımdan kaldırma politikası

  • ARCore SDK 1.12.0 veya sonraki sürümler ile oluşturulmuş uygulamalar, Cloud Anchor API 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?