Android NDK (C) için Cloud Anchor geliştirici kılavuzu

Cloud Anchor'ları 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 Anchor'ları kullanmaya yeni başladıysanız çapaların ve Cloud Anchor'ların işleyiş şeklini anladığınızdan emin olun.

ARCore API'yi etkinleştir

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

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

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

// 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);

Cloud Anchor'ı barındırma

Barındırma işlemi, ArSession_hostCloudAnchorAsync() numarasına yapılan bir aramayla başlar. ARCore, ARCore API'sine görsel verileri, cihaz duruşlarını ve sabit pozu yükler. Ardından API bu bilgileri işleyerek 3D özellik haritası oluşturur ve nihai olarak çapa için cihaza benzersiz bir Cloud Anchor Kimliği döndürür.

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

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

  1. ArSession_hostCloudAnchorAsync() numaralı telefonu arayın.
  2. Geri çağırmayı bekleyin veya işlem tamamlanana kadar sürekli olarak Gelecek durumunu kontrol edin.
  3. İşlemin başarılı olup olmadığını belirlemek için sonuç durumunu kontrol edin veya başarısız olduysa hata kodunu yorumlayın.
  4. Elde edilen Cloud Anchor Kimliği'ni diğer istemcilerle paylaşın ve Cloud Anchor kimliğini ArSession_resolveCloudAnchorAsync() ile çözmek için kullanın.

Özellik noktalarının haritalama kalitesini kontrol etme

ArFeatureMapQuality, ARCore'un belirli bir kamera pozundan önceki birkaç saniye içinde gördüğü özellik noktalarının kalitesini belirtir. Daha yüksek kaliteli özellikler kullanılarak barındırılan Cloud Anchor'lar genellikle daha doğru bir şekilde çözümlenir. Belirli bir kamera pozu için özellik haritası kalitesine ilişkin bir tahmin elde etmek üzere ArSession_estimateFeatureMapQualityForHosting() aracını kullanın.

Değer Açıklama
INSUFFICIENT Önceki birkaç saniyede pozdan belirlenen özellik noktalarının kalitesi düşük. Bu durum, ARCore'un Cloud Anchor'ı çözme konusunda daha fazla zorlukla karşılaşacağını gösterir. Kullanıcının barındırmak istediği Cloud Anchor konumunun farklı açılardan görülebilmesi için cihazı hareket ettirmeye teşvik edin.
SUFFICIENT Önceki birkaç saniyede pozisyonda tespit edilen özellik noktalarının kalitesi, ARCore'un Bulut Bağlantısını başarıyla çözmesi için yeterli olacaktır, ancak çözülmüş pozun doğruluğu muhtemelen azalacaktır. Kullanıcının barındırmak istediği Cloud Anchor konumunun farklı açılardan görülebilmesi için cihazı hareket ettirmeye teşvik edin.
GOOD Önceki birkaç saniyede pozdan kaynaklanan özellik noktalarının kalitesi, ARCore'un Bulut Bağlantısını yüksek doğrulukla başarılı bir şekilde çözmesi için yeterlidir.

Daha önce barındırılan bir bağlantıyı çözümleyin

Barındırılan bir Cloud Anchor'ı çözümlemek için ArSession_resolveCloudAnchorAsync() numaralı telefonu arayın. ARCore API'si, kullanıcının sabitle göreceli konumunu ve yönünü belirlemek için sahnenin görsel özelliklerini düzenli aralıklarla bağlantının 3D özellik haritasıyla karşılaştırır. API bir 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ümleme işlemi başlatabilirsiniz. Aynı anda en fazla 40 eşzamanlı Cloud Anchor işlemi mevcut olabilir.

Bir işlemi iptal etme veya Cloud Anchor'ı kaldırma

Beklemedeki bir Cloud Anchor işlemini iptal etmek için ArFuture_cancel() numaralı telefonu çağırın. İzlemeyi durdurmak ve daha önce çözümlenmiş bir Cloud Anchor'ı unutmak için ArAnchor_detach() numaralı telefonu arayın. çapa referansları ArAnchor_release() çağrısı yapılarak ayrı olarak yayınlanmalıdır.

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 ArCloudAnchorState'i kullanın.

Değer Açıklama
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND ARCore API, sağlanan Cloud Anchor Kimliği'ni bulamadığından çözümleme işlemi başarısız oldu.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED Sunucu, belirtilen sabit için veri kümesini başarıyla işleyemediğinden barındırma başarısız oldu. Cihaz ortamdan daha fazla veri topladıktan sonra tekrar deneyin.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API'sine ulaşılamadı. Bu bir dizi nedenden kaynaklanabilir. Cihaz, uçak modunda olabilir veya çalışan bir internet bağlantısı olmayabilir. Sunucuya gönderilen istek, yanıt alamadan zaman aşımına uğramış olabilir. Kötü bir ağ bağlantısı, DNS kullanılamaması, güvenlik duvarı sorunları veya cihazın ARCore API'ye bağlanma becerisini etkileyebilecek başka durumlar olabilir.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Bu anchor için barındırma veya çözümleme görevi dahili bir hatayla tamamlandı. Uygulama bu hatayı kurtarmaya çalışmamalıdır.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED ARCore API yetkilendirmesi ile ilgili sorunları giderme sayfasına göz atın.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW Bulut Bağlantısını çözümlemek için kullanılan SDK sürümü, bağlantıyı barındırmak için kullanılan sürümden daha yeni ve bu sürümle uyumlu olmadığından çözümlenemedi.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD Bulut Bağlantısını çözümlemek için kullanılan SDK sürümü, bağlantıyı barındırmak için kullanılan sürümden daha eski ve sürümle uyumlu olmadığından, Cloud Anchor çözümlenemedi.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED Uygulama, belirtilen Google Cloud projesine ayrılan istek kotasını aştı. Google Developers Console'dan projeniz için ARCore API'si için ek kota istemeniz gerekir.
AR_CLOUD_ANCHOR_STATE_SUCCESS Bu çapa için barındırma veya çözümleme görevi başarıyla tamamlandı.

Ana makine ve çözüm istekleri için API kotaları

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

Kota türü Maksimum Süre Uygulandığı yer
Bağlantı sayısı sınırsız Yok proje
Bağlantı barındırıcı istekleri 30 dakika IP adresi ve proje
Sabit resolve istekleri 300 dakika IP adresi ve proje

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

Uygulamanızda iyi bir kullanıcı deneyimi sunmak için kullanıcılardan aşağıdakileri yapmalarını isteyin:

  • Anchor barındırmaya çalışmadan önce (ör. nesne yerleştirerek) oturum başladıktan sonra birkaç saniye bekleyin. Bu, izlemenin kararlı hale gelmesi için biraz zaman tanır.
  • Anchor'ı barındıracak bir konum seçerken, birbirinden kolayca ayırt edilebilen görsel özelliklerin olduğu bir alan bulmaya çalışın. En iyi sonuçlar için boş beyaz duvarlar gibi görsel özellikleri olmayan yansıtıcı yüzeylerden veya yüzeylerden kaçının.
  • Kamerayı ilgi merkeziyle ilgili eğitimli halde tutun ve ortamın farklı açılardan haritasını çıkarmak için cihazı ilgili yerin çevresinde hareket ettirin. Bu sırada yaklaşık olarak aynı fiziksel mesafeyi koruyun. Bu, daha fazla görsel veri elde etmenize ve çözümü daha sağlam hale getirmenize yardımcı olur.

  • Cloud Anchor'ları barındırıp çözerken gerçek ortam ışığının yeterli olduğundan emin olun.

Kullanımdan kaldırma politikası

  • ARCore SDK 1.12.0 veya sonraki sürümleri ile oluşturulan uygulamalar Cloud Anchor API'nin kullanımdan kaldı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 desteği sonlandırılmış bir ARCore API'sini kullanması nedeniyle Cloud Anchor'ları barındıramaz veya çözümleyemez.

Sırada ne var?