Android के लिए Cloud ऐंकर डेवलपर गाइड (Kotlin/Java)

अपने ऐप्लिकेशन में क्लाउड ऐंकर इस्तेमाल करने का तरीका जानें.

ज़रूरी शर्तें

आगे बढ़ने से पहले, पक्का करें कि आपने एआर के बुनियादी सिद्धांतों और ARCore सेशन को कॉन्फ़िगर करने का तरीका समझ लिया हो.

अगर आपने हाल ही में Cloud Anchors का इस्तेमाल किया है, तो:

  • पक्का करें कि आपको ऐंकर और क्लाउड ऐंकर के काम करने का तरीका पता हो.
  • सिस्टम की ज़रूरतों, सेटअप, और इंस्टॉल करने से जुड़े निर्देशों के लिए, Cloud Anchors के क्विकस्टार्ट को पढ़ें.

ARCore API चालू करें

अपने ऐप्लिकेशन में क्लाउड ऐंकर का इस्तेमाल करने से पहले, आपको अपने ऐप्लिकेशन में ARCore API को चालू करना होगा.

सेशन कॉन्फ़िगरेशन में, Cloud Anchor की सुविधाएं चालू करना

अपने ऐप्लिकेशन में Cloud Anchors की सुविधा चालू करने के बाद, अपने ऐप्लिकेशन के एआर सेशन कॉन्फ़िगरेशन में Cloud Anchors की सुविधाएं चालू करें, ताकि यह ARCore API के साथ कम्यूनिकेट कर सके:

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 ऐंकर होस्ट करें

होस्टिंग की शुरुआत, hostCloudAnchorAsync() पर कॉल करने के साथ होती है. ARCore, विज़ुअल डेटा, डिवाइस के पोज़, और ऐंकर पोज़ को ARCore API पर अपलोड करेगा. इसके बाद एपीआई इस जानकारी को प्रोसेस करके, एक 3D फ़ीचर मैप बनाता है. इस तरह डिवाइस को ऐंकर के लिए एक खास क्लाउड ऐंकर आईडी मिलता है.

ARCore Cloud Anchor Management API का इस्तेमाल करके, होस्ट किए गए ऐंकर के लाइफ़टाइम को भी बढ़ाया जा सकता है.

Cloud Anchor के होस्ट की प्रक्रिया पूरी करने के लिए, आपके ऐप्लिकेशन को यह तरीका अपनाना चाहिए:

  1. hostCloudAnchorAsync() पर कॉल करें.
  2. कॉलबैक का इंतज़ार करें या आने वाले समय की स्थिति को तब तक देखते रहें, जब तक यह पूरा न हो जाए.
  3. नतीजे की स्थिति देखें, ताकि यह पता लगाया जा सके कि कार्रवाई पूरी हुई या नहीं. अगर कार्रवाई पूरी नहीं हुई है, तो गड़बड़ी के कोड का मतलब समझें.
  4. नतीजे के Cloud Anchor आईडी को अन्य क्लाइंट के साथ शेयर करें. साथ ही, इसका इस्तेमाल करके resolveCloudAnchorAsync() के साथ Cloud Anchor को हल करें.

सुविधा पॉइंट की मैपिंग क्वालिटी की जांच करना

Session.FeatureMapQuality से पता चलता है कि किसी कैमरा पोज़ के ज़रिए, पिछले कुछ सेकंड में ARCore को कौन-कौनसे फ़ीचर पॉइंट दिखते हैं. बेहतर क्वालिटी की सुविधाओं का इस्तेमाल करके होस्ट किए गए क्लाउड ऐंकर, आम तौर पर ज़्यादा सटीक तरीके से हल होते हैं. किसी कैमरा पोज़ के लिए, फ़ीचर मैप की क्वालिटी का अनुमान लगाने के लिए, Session.estimateFeatureMapQualityForHosting() का इस्तेमाल करें.

मान ब्यौरा
INSUFFICIENT पिछले कुछ सेकंड में पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी खराब है. इस स्थिति से यह पता चलता है कि ARCore को Cloud खाते के विकल्प से जुड़ी समस्या हल करने में ज़्यादा परेशानी हो सकती है. उपयोगकर्ता को डिवाइस को हिलाने के लिए कहें, ताकि वह जिस क्लाउड ऐंकर को होस्ट करना चाहता है उसकी पसंदीदा जगह को अलग-अलग ऐंगल से देखा जा सके.
SUFFICIENT पिछले कुछ सेकंड में पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी, ARCore के लिए क्लाउड ऐंकर को सही तरीके से हल करने के लिए काफ़ी हो सकती है. हालांकि, हो सकता है कि हल किए गए पोज़ की सटीकता कम हो जाए. उपयोगकर्ता को डिवाइस को हिलाने के लिए कहें, ताकि वह जिस क्लाउड ऐंकर को होस्ट करना चाहता है उसकी पसंदीदा जगह को अलग-अलग ऐंगल से देखा जा सके.
GOOD पिछले कुछ सेकंड में पोज़ से पहचाने गए फ़ीचर पॉइंट की क्वालिटी, ARCore के लिए ज़रूरत के मुताबिक हो सकती है. इससे, ARCore किसी क्लाउड ऐंकर को ज़्यादा सटीक तरीके से हल कर सकता है.

पहले होस्ट किए गए एंकर को ठीक करना

होस्ट किए गए Cloud Anchor से जुड़ी समस्या हल करने के लिए, resolveCloudAnchorAsync() को कॉल करें. ARCore API समय-समय पर, ऐंकर के 3D फ़ीचर मैप के साथ सीन की विज़ुअल सुविधाओं की तुलना, समय-समय पर करता है. ऐसा करके, उपयोगकर्ता की पोज़िशन और ओरिएंटेशन के बारे में पता लगाया जाता है. मैच मिलने पर, एपीआई होस्ट किए गए क्लाउड ऐंकर का पोज़ दिखाता है.

एक से ज़्यादा Cloud Anchors को क्रम से रिज़ॉल्व किया जा सकता है. एक समय में, Cloud ऐंकर पर एक साथ 40 कार्रवाइयां की जा सकती हैं.

किसी कार्रवाई को रद्द करना या Cloud ऐंकर को हटाना

Cloud anchor के उस ऑपरेशन को रद्द करने के लिए cancel() को कॉल करें जिसे मंज़ूरी मिलना बाकी है. ऐप्लिकेशन से पहले से हल किए गए Cloud Anchor को हटाने के लिए, detach() को कॉल करें.

Cloud anchor की कार्रवाई के नतीजे की स्थिति देखना

होस्ट करने या रिज़ॉल्व करने की प्रोसेस के नतीजे का स्टेटस देखने के लिए, Anchor.CloudAnchorState का इस्तेमाल करें. इसमें गड़बड़ियां भी शामिल हैं.

मान ब्यौरा
ERROR_CLOUD_ID_NOT_FOUND समस्या हल नहीं हो सकी, क्योंकि ARCore API को दिया गया Cloud Anchor आईडी नहीं मिला.
ERROR_HOSTING_DATASET_PROCESSING_FAILED होस्टिंग की प्रोसेस पूरी नहीं हो सकी, क्योंकि सर्वर दिए गए ऐंकर के लिए डेटासेट को प्रोसेस नहीं कर सका. जब डिवाइस आस-पास के माहौल से ज़्यादा डेटा इकट्ठा कर ले, तब फिर से कोशिश करें.
ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore एपीआई को ऐक्सेस नहीं किया जा सका. ऐसा कई कारणों से हो सकता है. हो सकता है कि डिवाइस हवाई जहाज़ मोड में हो या उस पर काम करने वाला इंटरनेट कनेक्शन न हो. ऐसा हो सकता है कि सर्वर को भेजे गए अनुरोध का समय खत्म हो गया हो और उस पर कोई जवाब न मिला हो. इंटरनेट की स्पीड अच्छी न होने, डीएनएस की उपलब्धता, फ़ायरवॉल से जुड़ी समस्याएं या ऐसी कोई भी वजह हो सकती है जिसकी वजह से ARCore API से डिवाइस कनेक्ट न हो पा रहा हो.
ERROR_INTERNAL इस ऐंकर के लिए होस्ट करने या रिज़ॉल्व करने का काम, किसी अंदरूनी गड़बड़ी के साथ पूरा हुआ. ऐप्लिकेशन को इस गड़बड़ी को ठीक करने की कोशिश नहीं करनी चाहिए.
ERROR_NOT_AUTHORIZED ऐप्लिकेशन से मिली अनुमति अमान्य है. ARCore API की अनुमति से जुड़ी समस्याएं हल करना लेख पढ़ें.
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Cloud Anchor को रिज़ॉल्व नहीं किया जा सका, क्योंकि ऐंकर को रिज़ॉल्व करने के लिए इस्तेमाल किया गया SDK टूल का वर्शन, उसे होस्ट करने के लिए इस्तेमाल किए गए वर्शन से नया है और साथ ही, उससे काम नहीं करता.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Cloud Anchor को रिज़ॉल्व नहीं किया जा सका, क्योंकि ऐंकर को रिज़ॉल्व करने के लिए इस्तेमाल किया गया SDK टूल का वर्शन, उसे होस्ट करने के लिए इस्तेमाल किए गए वर्शन से पुराना है और उसके साथ काम नहीं करता.
ERROR_RESOURCE_EXHAUSTED इस ऐप्लिकेशन ने Google Cloud प्रोजेक्ट के लिए दिया गया अनुरोध कोटा खत्म कर दिया है. आपको Google Developers Console से, अपने प्रोजेक्ट के लिए ARCore API के लिए अतिरिक्त कोटा का अनुरोध करना चाहिए.
SUCCESS इस ऐंकर के लिए, होस्टिंग या रिज़ॉल्व करने का टास्क पूरा हो गया.

होस्ट और समस्या हल करने के अनुरोधों के लिए एपीआई कोटा

ARCore API के लिए, अनुरोध बैंडविड्थ के ये कोटे हैं:

कोटा का टाइप ज़्यादा से ज़्यादा कुल समय इस पर लागू होता है
ऐंकर की संख्या अनलिमिटेड लागू नहीं प्रोजेक्ट
ऐंकर होस्ट के अनुरोध 30 मिनट आईपी पता और प्रोजेक्ट
ऐंकर resolve अनुरोध 300 मिनट आईपी पता और प्रोजेक्ट

बेहतर उपयोगकर्ता अनुभव के लिए सबसे सही तरीके

उपयोगकर्ताओं को अपने ऐप्लिकेशन पर अच्छा अनुभव देने के लिए, उन्हें ये काम करने का निर्देश दें:

  • ऐंकर को होस्ट करने की कोशिश करने से पहले, सेशन शुरू होने के बाद कुछ सेकंड इंतज़ार करें (किसी चीज़ को रखने वगैरह से). इससे ट्रैकिंग को स्थिर होने का कुछ समय मिलता है.
  • ऐंकर को होस्ट करने के लिए जगह चुनते समय, ऐसी जगह चुनें जहां विज़ुअल की सुविधाएं एक-दूसरे से आसानी से अलग दिखें. बेहतर नतीजे पाने के लिए, ऐसी सतहों का इस्तेमाल न करें जिनमें रोशनी या किसी ऑब्जेक्ट की झलक दिखती हो. इसके अलावा, ऐसी सतहों का भी इस्तेमाल न करें जिनमें कोई विज़ुअल एलिमेंट न हो, जैसे कि खाली सफ़ेद दीवारें.

  • कैमरे को उस जगह पर फ़ोकस करके रखें जिस पर आपको फ़ोटो लेनी है. साथ ही, डिवाइस को उस जगह के आस-पास घुमाएं, ताकि अलग-अलग ऐंगल से आस-पास के माहौल को मैप किया जा सके. ऐसा करते समय, डिवाइस को उस जगह से लगभग उतनी ही दूरी पर रखें जितनी दूरी पर आपने फ़ोटो लेनी है. इससे, ज़्यादा विज़ुअल डेटा कैप्चर करने और बेहतर तरीके से रिज़ॉल्यूशन तय करने में मदद मिलेगी.

  • क्लाउड ऐंकर को होस्ट और ठीक करते समय, पक्का करें कि असल माहौल में ज़रूरत के मुताबिक रोशनी हो.

बंद किए जाने की नीति

  • ARCore SDK टूल के 1.12.0 या उसके बाद के वर्शन का इस्तेमाल करके बनाए गए ऐप्लिकेशन पर, Cloud Anchor API के बंद होने से जुड़ी नीति लागू होती है.
  • ARCore SDK 1.11.0 या इससे पहले के वर्शन का इस्तेमाल करके बनाए गए ऐप्लिकेशन, Cloud Anchors को होस्ट या रिज़ॉल्व नहीं कर सकते. इसकी वजह यह है कि SDK टूल में, पुराने और काम न करने वाले ARCore API का इस्तेमाल किया गया है.

अब क्या होगा