أنشِئ تطبيق الواقع المعزَّز باستخدام واجهة برمجة التطبيقات ARCore Geospatial API الجديدة

1. نظرة عامة

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

ما ستنشئه

في هذا الدرس البرمجي، ستتعرّف على كيفية بدء استخدام ARCore Geospatial API. ستتعرّف على المعلومات التي يمكن أن توفّرها Geospatial API لتجربة الواقع المعزّز بشكل عام، وكيف يمكن استخدام هذه البيانات لتقديم تجربة بسيطة في الواقع المعزّز تساعد في تحديد الاتجاهات.

أهداف الدورة التعليمية

  • كيفية إعداد مشروع ARCore يستخدم Geospatial API
  • كيفية طلب بيانات جغرافية من Geospatial API وعرضها باستخدام "خرائط Google"
  • كيفية وضع نقطة ربط مرتبطة بموقع جغرافي حقيقي

المتطلبات

2. إعداد بيئة التطوير

إعداد "استوديو Android"

لبدء استخدام Geospatial API، قدّمنا مشروعًا تمهيديًا يتضمّن أساسيات مشروع ARCore مدمجًا مع حزمة تطوير البرامج (SDK) لخرائط Google. يساعدك ذلك في البدء بسرعة باستخدام Geospatial API.

  1. ابدأ "استوديو Android" واستورِد مشروعًا من نظام التحكم بالإصدارات.
    • إذا كان لديك مشروع مفتوح، استخدِم ملف > جديد > مشروع من نظام التحكّم في الإصدارات....
    • إذا ظهرت لك نافذة مرحبًا بك في "استوديو Android"، استخدِم الحصول من نظام التحكم بالإصدارات. الحصول على الموقع الجغرافي من نظام التحكّم بالإصدار (VCS)
  2. اختَر Git، واستخدِم عنوان URL https://github.com/google-ar/codelab-geospatial.git لاستيراد المشروع.

إعداد مشروع على Google Cloud

تستخدِم Geospatial API صور StreetView مع معلومات مقياس المغناطيسية وجهاز استشعار الكاميرا في الجهاز لتحسين قيم الاتجاه. لاستخدام هذه الخدمة، عليك إعداد مشروع على Google Cloud.

  1. أنشِئ مشروعًا في Google Cloud Console:
    • انتقِل إلى إنشاء مشروع في Google Cloud Platform.
      إنشاء مشروع على السحابة الإلكترونية على Google Cloud
    • أدخِل اسم مشروع مناسبًا (على سبيل المثال، "مشروع واجهة برمجة التطبيقات الجغرافية المكانية في ARCore")، واختَر أي موقع جغرافي.
    • انقر على إنشاء.
  2. فعِّل واجهات برمجة التطبيقات اللازمة:
    • في الشريط الجانبي، انقر على واجهات برمجة التطبيقات والخدمات، ثمّ على المكتبة.
    • ابحث عن ARCore API.
    • انقر على تفعيل.
    • عُد إلى المكتبة.
    • ابحث عن حزمة تطوير البرامج بالاستناد إلى بيانات "خرائط Google" للتطبيقات المتوافقة مع Android.
    • انقر على تفعيل.
  3. إنشاء بيانات اعتماد مفتاح واجهة برمجة التطبيقات:
    • ضمن واجهات برمجة التطبيقات والخدمات، انقر على بيانات الاعتماد.
    • في الشريط العلوي، انقر على إنشاء بيانات اعتماد، ثم اختَر مفتاح واجهة برمجة التطبيقات.
    • سجِّل المفتاح الذي تم إنشاؤه لأنّك ستحتاج إليه في الخطوة التالية. ارجِع إلى صفحة بيانات الاعتماد إذا كنت بحاجة إلى استردادها.

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

دمج مفتاح واجهة برمجة التطبيقات مع مشروع "استوديو Android"

لربط مفتاح واجهة برمجة التطبيقات من Google Cloud بمشروعك، افتح المشروع الذي أنشأته في "استوديو Android" وعدِّل مفاتيح واجهة برمجة التطبيقات:

  1. افتح app > src > AndroidManifest.xml.
  2. ابحث عن إدخالات meta-data التالية:
    <meta-data
    android:name="com.google.android.ar.API_KEY"
    android:value="PLACEHOLDER_API_KEY" />

<meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="PLACEHOLDER_API_KEY" />
  3. استبدِل PLACEHOLDER_API_KEY بمفتاح واجهة برمجة التطبيقات الذي أنشأته في مشروعك على Google Cloud.

تمنح القيمة المخزّنة في com.google.android.ar.API_KEY هذا التطبيق الإذن باستخدام Geospatial API، وتمنح القيمة المخزّنة في com.google.android.geo.API_KEY هذا التطبيق الإذن باستخدام حزمة تطوير البرامج (SDK) لخرائط Google.

تأكيد مشروعك

تأكَّد من أنّ مشروعك جاهز تمامًا. شغِّل تطبيقك في "استوديو Android". من المفترض أن تتمكّن من رؤية شاشة الكاميرا، بالإضافة إلى خريطة تعمل في أسفل الشاشة.

مشروع النص الأساسي

3- تحديد موضع المستخدم

في هذه الخطوة، ستضيف رمزًا إلى المشروع النموذجي لبدء استخدام Geospatial API.

ضبط جلسة ARCore لاستخدام Geospatial API

للحصول على بيانات جغرافية مكانية، عليك تفعيل Geospatial API. غيِّر GeospatialMode في إعدادات الجلسة إلى ENABLED من خلال تعديل الدالة configureSession في HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

عندما يكون "الوضع الجغرافي المكاني" ENABLED، يمكن للتطبيق الحصول على معلومات جغرافية مكانية.

طلب بيانات من Geospatial API

في HelloGeoRenderer.kt، ابحث عن السطر التالي:

// TODO: Obtain Geospatial information and display it on the map.

تحتها، تأكَّد من أنّ عنصر Earth متاح للاستخدام. ويكون ذلك عندما يكون لديه trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

أسفل TODO، اطلب معلومات جغرافية مكانية من ARCore. أضِف السطر التالي:

val cameraGeospatialPose = earth.cameraGeospatialPose

يمنحك ذلك GeospatialPose يحتوي على المعلومات التالية:

  • الموقع الجغرافي، معبَّرًا عنه بخطوط الطول والعرض يتم أيضًا تقديم تقدير لدقة الموقع الجغرافي.
  • الارتفاع وتقدير لدقة الارتفاع
  • الاتجاه، وهو تقدير للاتجاه الذي يشير إليه الجهاز، وتقدير لدقة الاتجاه

عرض معلومات تحديد المواقع على الخريطة

يمكنك استخدام GeospatialPose المخزّنة في cameraGeospatialPose لنقل علامة على الخريطة توضّح مكان المستخدم. تابِع من حيث توقّفت وأضِف ما يلي:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

يؤدي ذلك إلى تعديل موضع الخريطة باستمرار باستخدام القيم التي تم الحصول عليها من Geospatial API.

للتجربة:

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

يتبع السهم الأخضر موقعك الجغرافي واتجاهك.

4. وضع نقطة ارتساء باستخدام إحداثيات الأرض

يمكن لواجهة برمجة التطبيقات Geospatial API وضع نقاط ربط في أي زوج من الإحداثيات والتدوير في العالم الحقيقي. يتيح ذلك للمستخدمين رؤية المحتوى المثبّت عند زيارة مواقع جغرافية محدّدة.

في هذه الخطوة، ستضيف طريقة لوضع Anchor من خلال النقر على الخريطة.

ضبط إجراء عند النقر على الخريطة

يتضمّن المشروع الدالة onMapClick التي يتم استدعاؤها باستخدام خطوط الطول والعرض عند النقر على جزء الخريطة. ابحث عن الدالة onMapClick في HelloGeoRenderer.kt.

التأكّد من إمكانية استخدام عنصر Earth

قبل إنشاء نقاط ارتساء على الأرض، تأكَّد من أنّ قيمة TrackingState لعنصر الأرض هي TRACKING، ما يعني أنّ موضع الأرض معروف. تأكَّد أيضًا من أنّ EarthState هي ENABLED، ما يعني أنّه لم يتم رصد أي مشاكل في Geospatial API. أضِف الأسطر التالية داخل onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

تحديد موضع Anchor الجديد

بعد التأكّد من أنّ عنصر Earth يتتبّع الموقع الجغرافي، افصل earthAnchor السابق، إذا كان متوفّرًا. يمكنك استبدال earthAnchor برابط جديد في الخطوات التالية:

earthAnchor?.detach()

بعد ذلك، استخدِم cameraGeospatialPose لتحديد الارتفاع الخاص بنقطة الارتكاز الجديدة. استخدِم زوج الإحداثيات الناتج عن النقر على الخريطة لتحديد موضع نقطة الارتكاز.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

تنشئ createAnchor Anchor ثابتًا على الإحداثيات الجيوديسية مع تدوير معيّن. يحاول عنصر التثبيت هذا البقاء ثابتًا ومثبّتًا على الإحداثيات والارتفاع المحدّدين.

عرض العلامة الموضوعة على الخريطة

أخيرًا، حرِّك علامة جديدة تشير إلى المكان الذي تم وضع العلامة فيه:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

للتجربة:

في "استوديو Android"، انقر على تشغيل. ارفع جهازك وحرِّكه في كل الاتجاهات لمساعدة ARCore في إعداد التتبُّع. بعد فترة قصيرة، من المفترض أن يظهر لك على الخريطة علامة خضراء تشير إلى موقعك الجغرافي الحالي.

يؤدي النقر على الخريطة إلى استخدام Geospatial API لوضع نقطة ارتساء ثابتة في موقع جغرافي حقيقي. حاوِل وضع نقطة الارتكاز بالقرب من موقعك الجغرافي الحالي لتتمكّن من رؤيتها في عرض الواقع المعزّز. ويجب أن يظل ثابتًا أثناء التنقّل في بيئتك.

ضَع محدّد موقع من خلال النقر على الخريطة.

5- الخاتمة

في هذا الدرس التطبيقي حول الترميز، تعلّمت كيفية استخدام Geospatial API لإنشاء تجربة واقع معزّز بسيطة مرتبطة بالعالم الحقيقي.

ضَع محدّد موقع من خلال النقر على الخريطة.

المواضيع التي تناولناها

  • كيفية إعداد مشروع على السحابة الإلكترونية على Google Cloud تم تفعيل Geospatial API فيه
  • كيفية الحصول على معلومات جغرافية مكانية في مشروع ARCore وعرضها على خريطة
  • كيفية وضع نقطة ارتساء يتم تحديد موضعها في العالم الحقيقي باستخدام تحديد الموقع الجغرافي

مراجع إضافية

لمزيد من التفاصيل حول المفاهيم الجغرافية وحِزم تطوير البرامج (SDK) المستخدَمة في هذا الدرس التطبيقي حول الترميز، راجِع المراجع الإضافية التالية: