دليل المطوِّر في Cloud Anchors لنظام التشغيل iOS

توفر واجهات برمجة التطبيقات ARCore SDK لواجهات iOS مع ARKit إمكانية توفير إمكانات Cloud Anchor، مما يتيح لك مشاركة علامة الارتساء بين أجهزة iOS وAndroid في البيئة نفسها.

تعرَّف على كيفية استخدام ARCore Cloud Anchor API أو خدمة ARCore Cloud Anchor في تطبيقاتك الخاصة.

المتطلبات الأساسية

  • الإصدار 13.0 من Xcode أو إصدار أحدث
  • الإصدار 1.4.0 من تطبيق Cocoapods أو إصدار أحدث في حال استخدام Cocoapods
  • جهاز Apple متوافق مع ARKit يعمل بنظام التشغيل iOS 12.0 أو إصدار أحدث (مطلوب نشر الإصدار 12.0 من نظام التشغيل iOS أو إصدار أحدث)

إذا كنت مستخدمًا جديدًا لتطبيق Cloud Anchors:

تفعيل Cloud Anchors في تطبيقك

لاستخدام واجهة برمجة تطبيقات Cloud Anchors، عليك إنشاء GARSessionConfiguration وإعداد السمة cloudAnchorMode لها، كما هو موضّح في ضبط جلسة ARCore في نظام التشغيل iOS. استخدِم setConfiguration:error: (GARSession) لضبط الإعدادات.

يجب أيضًا تفعيل ARCore API لتطبيقك.

استضافة علامات الارتساء وحلها

يمكنك استضافة الإعلانات الثابتة على السحابة الإلكترونية وحلها باستخدام ARCore Cloud Anchor API. تشمل واجهة برمجة التطبيقات طرق معاودة الاتصال للعمليات المكتملة، بالإضافة إلى الكائنات المستقبلية التي يمكن استقصاؤها.

استضافة إعلان ثابت

تؤدي استضافة علامة ARAnchor إلى وضع المرساة في نظام إحداثي مشترك لأي مساحة فيزيائية معيّنة.

يرسل طلب المضيف بيانات مرئية إلى خادم Google يحدّد موضع ARAnchor في نظام إحداثي يمثّل المساحة الفعلية الحالية. يعرض طلب المضيف الناجح معرّف Cloud Anchor جديد، والذي يمكن مشاركته واستخدامه لحل الارتساء لاحقًا.

- (void)addAnchorWithTransform:(matrix_float4x4)transform {
  self.arAnchor = [[ARAnchor alloc] initWithTransform:transform];
  [self.sceneView.session addAnchor:self.arAnchor];

  __weak ExampleViewController *weakSelf = self;
  self.hostFuture = [self.cloudAnchorManager
      hostCloudAnchor:self.arAnchor
           completion:^(NSString *anchorId, GARCloudAnchorState cloudState) {
             [weakSelf handleHostAnchor:anchorId cloudState:cloudState];
           }
                error:nil];
  [self enterState:HelloARStateHosting];
}

حل علامة ارتساء

يؤدي حل ARAnchor إلى السماح لأجهزة Android وiOS في مساحة فعلية محدّدة بإضافة إعلانات ثابتة سبق استضافتها إلى مشاهد جديدة.

يرسل طلب الحل إلى خادم Google معرّف ارتساء السحابة الإلكترونية مع البيانات المرئية من الإطار الحالي. سيحاول الخادم مطابقة هذه البيانات المرئية مع صور مكان تعيين نقاط الإرساء المستضافة حاليًا في Cloud. عند نجاح حل المشكلة، تتم إضافة علامة ارتساء جديدة إلى الجلسة ويتم إرجاعها.

- (void)resolveAnchorWithIdentifier:(NSString *)identifier {
  GARResolveCloudAnchorFuture *garFuture =
      [self.gSession resolveCloudAnchorWithIdentifier:identifier
                                    completionHandler:completion
                                                error:&error];
}

// Pass the ARFRame to the ARCore session every time there is a frame update.
// This returns a GARFrame that contains a list of updated anchors. If your
// anchor's pose or tracking state changed, your anchor will be in the list.
- (void)cloudAnchorManager:(CloudAnchorManager *)manager didUpdateFrame:(GARFrame *)garFrame {
  for (GARAnchor *garAnchor in garFrame.updatedAnchors) {
    if ([garAnchor isEqual:self.garAnchor] && self.resolvedAnchorNode) {
      self.resolvedAnchorNode.simdTransform = garAnchor.transform;
      self.resolvedAnchorNode.hidden = !garAnchor.hasValidTransform;
    }
  }
}

نمط استطلاع GARSession الاختياري

إذا كنت تستخدم "الميتال" أو تحتاج إلى أحد خيارات الاستطلاع، ويعمل تطبيقك بمعدل 30 لقطة في الثانية على الأقل، استخدِم النمط التالي لتمرير ARFrames إلى GARSession:

-(void)myOwnPersonalUpdateMethod {
  ARFrame *arFrame = arSession.currentFrame;
  NSError *error = nil;
  GARFrame *garFrame = [garSession update:arFrame error:&error];
  // your update code here
}

حصص واجهة برمجة التطبيقات

تتضمن واجهة برمجة تطبيقات ARCore الحصص التالية لمعدل نقل البيانات للطلب:

نوع الحصة الحد الأقصى المدة ينطبق على
عدد مرات الارتساء غير محدودة لا ينطبق المشروع
طلبات إعلانات المضيف الثابتة 30 دقيقة عنوان IP والمشروع
طلبات resolve الارتساء 300 دقيقة عنوان IP والمشروع

المشاكل المعروفة والحلول البديلة

هناك بعض المشاكل المعروفة عند التعامل مع ARCore SDK لنظام التشغيل iOS.

تتسبّب إعدادات المخطَّط التلقائية في تعطُّل التطبيق المتقطّع.

يتم تفعيل إعدادات مخطط GPU Frame وMetal API للتحقّق من صحة البيانات بشكل تلقائي، ما قد يؤدي أحيانًا إلى تعطُّل التطبيق داخل حزمة تطوير البرامج (SDK).

تشخيص تعطُّل التطبيق

عندما تشك في حدوث عطل، يمكنك إلقاء نظرة على تتبُّع تسلسل استدعاء الدوال البرمجية. إذا ظهر لك MTLDebugComputeCommandEncoder في تقرير تتبُّع تسلسل استدعاء الدوال البرمجية، من المحتمل أن يكون ذلك بسبب إعدادات المخطَّط التلقائية.

الحل

  1. الانتقال إلى Product > Scheme > Edit Scheme….

  2. فتح علامة التبويب "Run"

  3. انقر على Options لعرض الإعدادات الحالية.

  4. احرص على إيقاف كل من GPU Frame Capture وMetal API Validation.

  5. إنشاء تطبيقك وتشغيله

يمكنك الانتقال إلى CHANGELOG على Cocoapods لمعرفة المشاكل الأخرى المعروفة.

القيود

لا تتوافق حزمة ARCore SDK لنظام التشغيل iOS مع استدعاء طريقة ARKit setWorldOrigin(relativeTransform:).

اعتبارات الأداء

يزداد استخدام الذاكرة عند تفعيل واجهة برمجة التطبيقات ARCore. توقع ارتفاع استخدام بطارية الجهاز بسبب زيادة استخدام الشبكة واستخدام وحدة المعالجة المركزية (CPU).

الخطوات التالية