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