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

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

1- نظرة عامة

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

ما ستقوم بإنشائه

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

ما ستتعرَّف عليه

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

المتطلبات

جهاز Android متوافق مع ARCore، متصل باستخدام كابل 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

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

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

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

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

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

افتح التطبيق > 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

للحصول على البيانات الجيوفضائية، يلزمك تفعيل واجهة برمجة التطبيقات الجغرافية المكانية. يمكنك تغيير GeospatialMode في ضبط الجلسة إلى ENABLED عن طريق تعديل دالة configureSession في HelloGeoActivity.kt:

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

إذا كان الوضع الجيوفضائي هو ENABLED، يمكن للتطبيق الحصول على المعلومات الجيوفضائية.

طلب البيانات من واجهة برمجة التطبيقات الجغرافية المكانية

في 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.
}

يمكنك طلب معلومات جيوفضائية من ARCore أسفل TODO. إضافة هذا السطر:

val cameraGeospatialPose = earth.cameraGeospatialPose

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

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

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

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

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

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

تجربة السمات والبيانات

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

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

4. تحديد مرساة باستخدام إحداثيات Earth

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

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

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

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

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

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

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

تحديد موضع علامة الارتساء الجديدة

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