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