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

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

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

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

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

ARCore API चालू करें

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

सेशन कॉन्फ़िगरेशन में Cloud anchor की क्षमताएं चालू करें

अपने ऐप्लिकेशन में Cloud Anchors की सुविधा चालू होने के बाद, अपने ऐप्लिकेशन के एआर (ऑगमेंटेड रिएलिटी) सेशन कॉन्फ़िगरेशन में Cloud Anchors की सुविधाएं चालू करें. इससे यह 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);

Cloud ऐंकर होस्ट करें

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

बंद करने की नीति

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

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