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

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

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

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

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

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

ARCore API चालू करना

अपने ऐप्लिकेशन में Cloud Anchors का इस्तेमाल करने से पहले, आपको अपने ऐप्लिकेशन में 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)

क्लाउड ऐंकर होस्ट करना

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

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

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

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

फ़ीचर पॉइंट की मैपिंग क्वालिटी देखना

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

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

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

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

एक से ज़्यादा Cloud ऐंकर के लिए, क्रम में समाधान शुरू किए जा सकते हैं. एक बार में ज़्यादा से ज़्यादा 40 क्लाउड ऐंकर ऑपरेशन मौजूद हो सकते हैं.

कोई कार्रवाई रद्द करना या Cloud Anchor हटाना

Cloud Anchor से जुड़ा कोई ऐसा ऑपरेशन रद्द करने के लिए जिसे पूरा नहीं किया गया है, cancel() को कॉल करें. ऐप्लिकेशन से पहले से हल हो चुके Cloud ऐंकर को हटाने के लिए, detach() को कॉल करें.

Cloud Anchor के इस्तेमाल से जुड़ी कार्रवाई के नतीजे की स्थिति देखना

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

मान ब्यौरा
ERROR_CLOUD_ID_NOT_FOUND समस्या हल नहीं हो सकी, क्योंकि ARCore API को दिया गया Cloud Anchor आईडी नहीं मिला.
ERROR_HOSTING_DATASET_PROCESSING_FAILED होस्टिंग की प्रोसेस पूरी नहीं हो सकी, क्योंकि सर्वर दिए गए ऐंकर के लिए डेटासेट को प्रोसेस नहीं कर सका. जब डिवाइस आस-पास के माहौल से ज़्यादा डेटा इकट्ठा कर ले, तब फिर से कोशिश करें.
ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API को ऐक्सेस नहीं किया जा सका. ऐसा कई कारणों से हो सकता है. हो सकता है कि डिवाइस, हवाई जहाज़ मोड में हो या उसका इंटरनेट कनेक्शन काम न कर रहा हो. हो सकता है कि सर्वर पर भेजे गए अनुरोध का समय खत्म हो गया हो और कोई जवाब न मिला हो. ऐसा हो सकता है कि नेटवर्क कनेक्शन खराब हो, डीएनएस उपलब्ध न हो, फ़ायरवॉल से जुड़ी समस्याएं हों या कोई और समस्या हो. इनसे, डिवाइस के 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 मिनट आईपी पता और प्रोजेक्ट
ऐंकर समाधान से जुड़े अनुरोध 300 मिनट आईपी पता और प्रोजेक्ट

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

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

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

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

  • Cloud Anchors होस्ट करते और उन्हें रिज़ॉल्व करते समय, पक्का करें कि रीयल-लाइफ़ एनवायरमेंट में ज़रूरत के मुताबिक रोशनी हो.

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

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

अब क्या होगा