تمت ترجمة هذه الصفحة بواسطة 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.
خدمات Google Play للواقع المعزّز 1.31 أو إصدار أحدث، مثبَّت على جهاز تطوير Android

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

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

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

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

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

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

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

باستخدام هذه الخطوات، تكون قد أنشأت مشروعًا على 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 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

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