تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. نظرة عامة

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

ما الذي ستقوم ببنائه

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

المُعطيات

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

المتطلبات

جهاز ARCore Android متوافق ومتصل باستخدام كابل USB بجهاز التطوير، تم إعداده باستخدام تصحيح أخطاء USB.
تثبيت استوديو Android وضبطه لإنشاء تطبيقات Android
الإصدار 1.31 من خدمات Google Play للواقع المعزّز أو إصدار أحدث، مثبَّت على جهاز تطوير Android

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

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

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

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

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

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

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

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

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

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

افتح التطبيق > src > AndroidManifest.xml.

ابحث عن الإدخالات التالية البالغ عددها 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" />

استبدِل 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. وضع علامة مرجعية باستخدام إحداثيات Earth

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

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

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

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

التأكد من إمكانية استخدام كائن Earth

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

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

تحديد موضع العنصر الأساسي الجديد

بعد التأكّد من أنّ عنصر الأرض يتم تتبُّعه، عليك فصل العنصر 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) المستخدَمة في هذا الدليل التعليمي، اطّلِع على هذه المراجع الإضافية: