العمل مع ARCore لميزة Jetpack XR

يتيح ARCore لـ Jetpack XR للتطبيقات العمل مع المفاهيم الأساسية للواقع المعزّز (AR)، وذلك باستخدام العناصر الأساسية لفهم المشهد على مستوى منخفض وتتبُّع الحركات. استخدِم ARCore لـ Jetpack XR عند إنشاء تجارب الواقع المعزّز ويجب استخدام بيانات مسطحة أو تثبيت المحتوى في مكان ثابت في الفضاء.

فهم دورة حياة الجلسة

يجب الوصول إلى جميع الأجسام التي تتتبّعها حزمة ARCore لتطبيق Jetpack XR من خلال جلسة. على غرار مراحل نشاط النشاط، تتضمّن عناصر الجلسة أيضًا مراحل نشاط يجب الحفاظ عليها وفقًا لاستخدام تطبيقك لميزات عنصر الجلسة. إذا كان تطبيقك يتضمّن نشاطًا واحدًا مزوّدًا بتكنولوجيا الواقع المعزّز، ننصحك بمعالجة دورة حياة الجلسة باستخدام مكوّن مدرك لدورة الحياة.

إنشاء جلسة

يجب إنشاء جلسة قبل استخدامها. يتطلب إنشاء جلسة أن يمنح المستخدم إذن android.permission.SCENE_UNDERSTANDING لتطبيقك.

لإنشاء جلسة:

when (val result = Session.create(owner)) {
  is SessionCreateSuccess -> {
    session = result.session
  }
  is SessionCreatePermissionsNotGranted -> {
   // Request android.permission.SCENE_UNDERSTANDING.
  }
}

راجِع SessionCreateResult لمعرفة أسباب تعذُّر إنشاء جلسة.

استئناف جلسة

يجب استئناف جلسة عندما يكون تطبيقك جاهزًا للتعامل مع تغييرات الحالة من ARCore لـ Jetpack XR. في العديد من الحالات، يتم إجراء ذلك في onResume() callback لنشاطك، ولكن قد يريد تطبيقك تأخير المعالجة إلى أن يتفاعل المستخدم.

يعرض مقتطف الرمز البرمجي التالي مثالاً على استئناف جلسة.

when (val result = session.resume()) {
  is SessionResumeSuccess -> {
    // Session has been created successfully.
    // Attach any successful handlers here.
  }
  is SessionResumePermissionsNotGranted -> {
    // Request android.permission.SCENE_UNDERSTANDING.
}

راجِع SessionResumeResult لمعرفة الأسباب التي قد تؤدي إلى عدم استئناف الجلسة.

إيقاف جلسة مؤقتًا

عندما ينتقل نشاطك إلى الخلفية، يمكنك إيقاف الجلسة مؤقتًا باستخدام رمز Session.pause(). يؤدي إيقاف جلسة مؤقتًا إلى إيقاف التتبّع مؤقتًا إلى أن تتم استعادة الجلسة، مع الحفاظ على حالة نظام الرصد.

إتلاف جلسة

للتخلص من جلسة نهائيًا، استخدِم Session.destroy(). يؤدي ذلك إلى تحرير الموارد المستخدَمة في الجلسة وتدمير جميع حالات الجلسة.

استرداد حالة الطائرات التي تم رصدها

يوفّر ARCore لـ Jetpack XR حالة الطائرات من خلال StateFlow الذي يُرسِل حالة الطائرات. يؤدي الاشتراك في خطط في جلسة إلى إرسال إشعار إلى تطبيقك عند إضافة خطط أو تعديلها أو إزالتها.

Plane.subscribe(session).collect { planes ->
 // Planes have changed; update plane rendering
}

تتضمّن الطائرة السمات التالية:

  • label: وصف دلالي لموضوع معيّن Plane. يمكن أن يكون Wall أو Floor أو Ceiling أو Table.
  • centerPose: وضع مركز سطح الالتقاط
  • ‫extents: سمات الطائرة التي تم رصدها، بال متر
  • ‫vertices: قائمة بنقاط مضلع محدب تقريبًا للمستوى

إجراء اختبار تصادم مع الطائرات

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

لإجراء اختبار مطابقة، استخدِم Interaction.hitTest() مع Ray:

val results = Interaction.hitTest(session, ray)
// When interested in the first Table hit:
val tableHit = results.firstOrNull {
  val trackable = it.trackable
  trackable is Plane && trackable.state.value.label == Plane.Label.Table
}

تثبيت المحتوى في مكان ثابت في المساحة

لمنح الأجسام الافتراضية موضعًا في العالم الواقعي، استخدِم علامة Anchor. يساعد عنصر الربط تطبيقك في تتبُّع موقع ثابت في المساحة المادية.

يتم إنشاء عنصر ربط باستخدام Pose، والذي يمكنinterpreted تفسيره بالنسبة إلى Trackable حالي أو لا.

إنشاء عنصر ربط بالنسبة إلى عنصر قابل للتتبّع

عند إنشاء عنصر تثبيت بالنسبة إلى Trackable، مثل Plane، مما يؤدي إلى تتبُّع عنصر التثبيت للعنصر Trackable المرفق عند تنقّله في المساحة

val anchor = trackable.createAnchor(pose)

إنشاء عنصر ربط بدون عنصر قابل للتتبّع

لإنشاء عنصر تثبيت غير مرتبط بعنصر Trackable:

when (val result = Anchor.create(session, pose)) {
  is AnchorCreateSuccess -> // ...
  else -> // handle failure
}

إرفاق عنصر بعنصر ربط

لعرض نموذج في هذا الموقع الجغرافي، أنشئ GltfModel واضبط وضعه على وضع العنصر الأساسي. تأكَّد من أنّ النموذج مخفي عندما يكون TrackingState العنصر الأساسيStopped.

// renderSession is androidx.xr.core.Session
anchor.state.collect { state ->
  if (state.trackingState == TrackingState.Tracking) {
    gltfEntity.setPose(
      renderSession.perceptionSpace.transformPoseTo(state.pose, renderSession.activitySpace)
    )
  } else if (state.trackingState == TrackingState.Stopped) {
    entity.setHidden(true)
  }
}

فهم TrackingState

يحتوي كل Trackable على TrackingState يجب التحقّق منه قبل استخدامه. إنّ Trackable التي لها TrackableState تبلغ Tracking يتم تعديل Pose الخاص بها بشكل نشط من قِبل النظام. قد يصبح Trackable الذي يُصنَّف على أنّه Paused Tracking في المستقبل، في حين أنّ Stopped لن يصبح Tracking أبدًا.

الاحتفاظ بنقطة تثبيت على مدار الجلسات

يختفي العنصر النائب الذي لم يتم الاحتفاظ به بعد إغلاق الجلسة. من خلال تثبيت علامة مرجعية، سيتذكر تطبيقك موضع تلك العلامة في data الخاصة بالتطبيق. يمكن استرجاع هذا العنصر في جلسة لاحقة ويتم تثبيته في الموقع الجغرافي نفسه في العالم.

للحفاظ على إشارة مرجعية، استخدِم anchor.persist() كما هو موضّح هنا:

val uuid = anchor.persist()

يمكن لتطبيقك استرداد العنصر الأساسي باستخدام الرمز UUID في جلسة مستقبلية:

when (val result = Anchor.load(session, uuid)) {
  is AnchorCreateSuccess -> // Loading was successful. The anchor is stored in result.anchor.
  else -> // handle failure
}

عندما لا تحتاج إلى مراسٍ بعد الآن، اتصل بالرقم التالي: unpersist(). يؤدي ذلك إلى إزالة العنصر الأساسي من مساحة تخزين تطبيقك وإلى جعل معرّف UUID المحدّد غير قابل للاسترداد للمكالمات إلى Anchor.load().

Anchor.unpersist(session, uuid)

يمكن لتطبيقك أيضًا طلب قائمة بجميع العناصر الثابتة التي تم الاحتفاظ بها والتي لا تزال متوفّرة في مساحة تخزين تطبيقك:

val uuids = Anchor.getPersistedAnchorUuids(session)