Android NDK (C) के लिए Cloud ऐंकर डेवलपर गाइड

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

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

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

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

ARCore API चालू करना

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

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

आपके ऐप्लिकेशन में 'क्लाउड ऐंकर' की सुविधा चालू हो जाने के बाद, अपने ऐप्लिकेशन के एआर (ऑगमेंटेड रिएलिटी) सेशन कॉन्फ़िगरेशन में क्लाउड ऐंकर सुविधाओं को चालू करें, ताकि यह ARCore API के साथ काम कर सके:

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

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

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

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

क्लाउड ऐंकर की होस्टिंग को पूरा करने के लिए, आपके ऐप्लिकेशन को यह तरीका अपनाना होगा:

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

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

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

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

पहले होस्ट किए गए ऐंकर को बंद करना

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

एक से ज़्यादा क्लाउड ऐंकर के लिए, क्रम से रिज़ॉल्व शुरू किए जा सकते हैं. एक समय में, एक साथ 40 Cloud ऐंकर कार्रवाइयां की जा सकती हैं.

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

अगर Cloud ऐंकर कार्रवाई को मंज़ूरी मिलना बाकी है, तो उसे रद्द करने के लिए ArFuture_cancel() को कॉल करें. ट्रैकिंग बंद करने और पहले से हल किए गए क्लाउड ऐंकर को हटाने के लिए, ArAnchor_detach() को कॉल करें. ArAnchor_release() को कॉल करके, ऐंकर के रेफ़रंस अलग से रिलीज़ किए जाने चाहिए.

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

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

वैल्यू ब्यौरा
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND समाधान नहीं किया जा सका, क्योंकि ARCore API को दिया गया Cloud ऐंकर आईडी नहीं मिला.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED होस्ट नहीं किया जा सका, क्योंकि सर्वर दिए गए ऐंकर के डेटासेट को प्रोसेस नहीं कर सका. जब डिवाइस वातावरण से ज़्यादा डेटा इकट्ठा कर ले, तब फिर से कोशिश करें.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE ARCore API से कनेक्ट नहीं किया जा सकता. ऐसा कई कारणों से हो सकता है. मुमकिन है कि डिवाइस हवाई जहाज़ मोड में हो या उसका इंटरनेट कनेक्शन ठीक से काम न करता हो. ऐसा हो सकता है कि सर्वर को भेजे गए अनुरोध का समय खत्म हो गया हो और कोई जवाब न मिला हो. इंटरनेट ठीक से काम नहीं कर रहा है, डीएनएस का उपलब्ध नहीं है, फ़ायरवॉल की समस्याएं हो सकती हैं या कुछ भी ऐसा हो सकता है जिसकी वजह से डिवाइस के ARCore API से कनेक्ट करने की सुविधा पर असर पड़ सकता है.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL इस ऐंकर के लिए, होस्ट करने या समाधान करने का टास्क पूरा हुआ, लेकिन कोई अंदरूनी गड़बड़ी हुई. ऐप्लिकेशन को इस गड़बड़ी को ठीक करने की कोशिश नहीं करनी चाहिए.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED ARCore API की अनुमति से जुड़ी समस्याएं हल करना देखें.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW क्लाउड ऐंकर की समस्या हल नहीं की जा सकी. ऐसा इसलिए, क्योंकि ऐंकर को ठीक करने के लिए इस्तेमाल किया गया SDK टूल का वर्शन, उसे होस्ट करने के लिए इस्तेमाल किए गए वर्शन से नया है और उसके साथ काम नहीं करता.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD क्लाउड ऐंकर की समस्या हल नहीं की जा सकी. ऐसा इसलिए, क्योंकि ऐंकर की समस्या हल करने के लिए इस्तेमाल किया जाने वाला SDK टूल का वर्शन, उसे होस्ट करने वाले वर्शन से पुराना है और उसके साथ काम नहीं करता.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED इस ऐप्लिकेशन के लिए, Google Cloud के प्रोजेक्ट के लिए तय किया गया अनुरोध कोटा खत्म हो गया है. आपको Google Developers Console से अपने प्रोजेक्ट के लिए ARCore API के लिए अतिरिक्त कोटा का अनुरोध करना चाहिए.
AR_CLOUD_ANCHOR_STATE_SUCCESS इस ऐंकर के लिए, होस्ट करने या समाधान करने का टास्क पूरा हुआ.

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

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

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

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

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

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

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

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

वर्शन रोकने की नीति

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

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