Unity (एआर फ़ाउंडेशन) के लिए, क्लाउड ऐंकर डेवलपर गाइड

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

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

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

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

ARCore API चालू करना

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ARCloudAnchor कॉम्पोनेंट को उस गेम ऑब्जेक्ट से हटाने पर, ARCloudAnchor.OnDestroy() अपने-आप कॉल हो जाता है जिसमें यह कॉम्पोनेंट मौजूद होता है. इससे, नेटिव Cloud Anchor ऑब्जेक्ट को अलग कर दिया जाएगा और उसे रिलीज़ कर दिया जाएगा.

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

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

मान ब्यौरा
ErrorResolvingCloudIdNotFound समस्या हल नहीं हो सकी, क्योंकि ARCore API को दिया गया Cloud Anchor आईडी नहीं मिला.
ErrorHostingDatasetProcessingFailed होस्टिंग की प्रोसेस पूरी नहीं हो सकी, क्योंकि सर्वर दिए गए ऐंकर के लिए डेटासेट को प्रोसेस नहीं कर सका. जब डिवाइस, आस-पास के वातावरण से ज़्यादा डेटा इकट्ठा कर ले, तब फिर से कोशिश करें.
ErrorHostingServiceUnavailable ARCore API को ऐक्सेस नहीं किया जा सका. ऐसा कई कारणों से हो सकता है. हो सकता है कि डिवाइस, हवाई जहाज़ मोड में हो या उसका इंटरनेट कनेक्शन काम न कर रहा हो. हो सकता है कि सर्वर पर भेजे गए अनुरोध का समय खत्म हो गया हो और कोई जवाब न मिला हो. ऐसा हो सकता है कि नेटवर्क कनेक्शन खराब हो, डीएनएस उपलब्ध न हो, फ़ायरवॉल से जुड़ी समस्याएं हों या कोई और समस्या हो. इनसे, डिवाइस के ARCore API से कनेक्ट होने की क्षमता पर असर पड़ सकता है.
ErrorInternal इस ऐंकर के लिए होस्टिंग या समस्या हल करने का टास्क, किसी इंटरनल गड़बड़ी की वजह से पूरा हो गया. ऐप्लिकेशन को इस गड़बड़ी को ठीक करने की कोशिश नहीं करनी चाहिए.
ErrorNotAuthorized अमान्य अनुमति की वजह से, ऐप्लिकेशन ARCore API के साथ काम नहीं कर सकता. अनुमति देने की मान्य रणनीति के लिए, प्रोजेक्ट सेटिंग > XR > ARCore एक्सटेंशन पर जाएं.
ErrorResolvingPackageTooNew Cloud Anchor को हल नहीं किया जा सका, क्योंकि Cloud Anchor को हल करने के लिए इस्तेमाल किया जाने वाला ARCore एक्सटेंशन पैकेज, उसे होस्ट करने के लिए इस्तेमाल किए जा रहे वर्शन से नया है और उसके साथ काम नहीं करता.
ErrorResolvingPackageTooOld Cloud Anchor को हल नहीं किया जा सका, क्योंकि Cloud Anchor को हल करने के लिए इस्तेमाल किया गया ARCore एक्सटेंशन पैकेज, उसे होस्ट करने के लिए इस्तेमाल किए जा रहे वर्शन से पुराना है और उसके साथ काम नहीं करता.
ErrorResourceExhausted ऐप्लिकेशन ने, दिए गए Google Cloud प्रोजेक्ट के लिए तय किया गया अनुरोध कोटा खत्म कर दिया है. आपको Google Developers Console से अपने प्रोजेक्ट के लिए, ARCore API के ज़्यादा कोटा का अनुरोध करना चाहिए.
Success इस ऐंकर के लिए, होस्टिंग या रिज़ॉल्व करने का टास्क पूरा हो गया.

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

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

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

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

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

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

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

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

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

आगे क्या करना है