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

بدء استخدام واجهتَي برمجة التطبيقات Streetscape Geometry وRooftop anchors في ARCore

1. قبل البدء

‫ARCore هو إطار عمل من Google لإنشاء تجارب الواقع المعزّز (AR) على الهواتف الذكية. تساعد واجهتا برمجة التطبيقات Geospatial Streetscape Geometry وRooftop anchor تجارب الواقع المعزّز في التعرّف على المباني المحيطة بالمستخدمين.

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

عرض توضيحي كامل لتطبيق الدرس التطبيقي حول الترميز

المتطلبات الأساسية

معرفة أساسية AR
معرفة أساسية بواجهة ARCore Geospatial API

أهداف الدورة التعليمية

كيفية إعداد مشروع على Google Cloud يمكنه استخدام واجهات ARCore Geospatial API
كيفية الحصول على أشكال هندسية للمشاهد من واجهة Geospatial API
كيفية عرض المباني والتضاريس التي تم الحصول عليها من هندسة المشهد الحضري
كيفية إجراء العمليات الحسابية الأساسية على المضلّعات التي تم الحصول عليها
كيفية إجراء اختبار إصابة على الشكل الهندسي
كيفية استخدام نقاط تثبيت على الأسطح لربط المحتوى بأعلى المباني

المتطلبات

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

2. إعداد البيئة

لاستخدام واجهات Geospatial API مع Kotlin وAndroid Studio، يجب أن يكون لديك مشروع على Google Cloud ومشروعنا التجريبي.

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

تتصل واجهة برمجة التطبيقات ARCore Geospatial API بخدمة Google Cloud لتقديم معلومات تحديد الموقع الجغرافي من نظام تحديد المواقع المرئية (VPS) من Google في المناطق التي تغطيها خدمة "التجوّل الافتراضي" من Google.

لاستخدام هذا الخادم في مشروعك، اتّبِع الخطوات التالية:

أنشِئ مشروعًا في Google Cloud.
في حقل اسم المشروع، أدخِل اسمًا مناسبًا، مثل ARCore Geospatial API project، واختَر أي موقع جغرافي.
انقر على إنشاء.
في وحدة تحكّم Google Cloud، انقر على إنشاء مشروع في صفحة اختيار المشروع.
انقر على الرابط التالي لعرض ARCore API لهذا المشروع، ثم انقر على تفعيل:
أنشئ مفتاح واجهة برمجة تطبيقات لمشروعك:
1. ضمن واجهات برمجة التطبيقات والخدمات، انقر على بيانات الاعتماد.
2. انقر على إنشاء بيانات اعتماد واختَر مفتاح واجهة برمجة التطبيقات.
3. دوِّن المفتاح لأنّك ستحتاج إليه لاحقًا.

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

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

لبدء استخدام Geospatial API، قدّمنا مشروعًا تمهيديًا يتضمّن أساسيات مشروع ARCore المتكامل مع Geospatial API.

لإعداد Android Studio، اتّبِع الخطوات التالية:

افتح "استوديو Android" ونفِّذ أحد الإجراءات التالية:
- إذا كان لديك مشروع مفتوح، انقر على ملف > جديد > مشروع من نظام التحكّم بالإصدارات.
- إذا ظهرت لك نافذة مرحبًا بك في "استوديو Android"، انقر على الحصول على البيانات من نظام التحكّم بالإصدارات.
انقر على Git وأدخِل https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git لاستيراد المشروع.

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

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

في "استوديو Android"، انقر على app > src وانقر مرّتين على AndroidManifest.xml.

ابحث عن إدخالات meta-data التالية:

<meta-data
    android:name="com.google.android.ar.API_KEY"
    android:value="API_KEY" />

استبدِل العنصر النائب API_KEY بمفتاح واجهة برمجة التطبيقات الذي أنشأته في مشروعك على Google Cloud. تسمح القيمة المخزّنة في com.google.android.ar.API_KEY لهذا التطبيق باستخدام Geospatial API.

تأكيد مشروعك

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

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

3- عرض بيانات هندسة المشهد في الشارع

بعد التأكّد من أنّ Geospatial API تعمل على جهازك، يمكنك الحصول على هندسة المشهد من Geospatial API.

تفعيل هندسة المشهد الحضري

في الملف StreetscapeGeometryActivity.kt، ابحث عن السطر التالي:
```
// TODO: Enable Streetscape Geometry.
```
بعد هذا السطر، فعِّل وضع streetscape-geometry:
```
streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
```
عند تفعيل Geospatial API ووضع streetscape-geometry، يمكن لتطبيقك تلقّي معلومات حول هندسة المشهد الحضري حول المستخدم.

الحصول على بيانات هندسة المشهد

في الملف StreetscapeGeometryActivity.kt، ابحث عن السطر التالي:
```
// TODO: Obtain Streetscape Geometry.
```
بعد هذا السطر، احصل على أشكال هندسية للمشهد في الشارع من خلال الحصول على جميع عناصر Trackable والفلتَرة حسب StreetscapeGeometry:
```
val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
```
يمكنك استخدام هذه الأشكال الهندسية في عرض مرئي بسيط متوفّر في نموذج المشروع. يعرض هذا التصوّر كل مضلّع من المباني أو التضاريس بلون مختلف.

في السطر التالي، أضِف الرمز التالي:

streetscapeGeometryRenderer.render(render, streetscapeGeometry)

شغِّل تطبيقك وانتقِل إلى مبنى في منطقتك.
بعد اكتمال عملية تحديد الموقع الجغرافي، انقر على الإعدادات وفعِّل عرض الأشكال الهندسية للمشاهدات الخارجية.
النظر إلى مبنى بتقنية الواقع المعزّز لكل مبنى مقسّم لونه الخاص، ويتم عرض Quality وType Enums الخاصين بالشكل الهندسي الأوسط.

عرض بيانات هندسة Streetscape في التطبيق

4. إجراء اختبار إصابة باستخدام بيانات هندسة المشهد في الشارع

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

إجراء اختبار النتائج

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

في الملف StreetscapeCodelabRenderer.kt، ابحث عن السطر التالي:
```
// TODO: determine the Streetscape Geometry at the center of the viewport
```
بعد هذا السطر، أضِف الرمز التالي:
```
val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
val hit = centerHits.firstOrNull {
  val trackable = it.trackable
  trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
} ?: return
```
يستخدم هذا الرمز إحداثيات المركز للعثور على شكل هندسي لمشهد شارع يمثّل مبنى. يمكنك استخدام هذه النتيجة لإضافة عناصر زخرفية.

إضافة زينة على شكل نجمة عند النقر

في الملف StreetscapeCodelabRenderer.kt، ابحث عن السطر التالي:
```
// TODO: Create an anchor for a star, and add it to the starAnchors object.
```
بعد هذا السطر، أضِف الرمز التالي:
```
val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
val anchor = hit.trackable.createAnchor(transformedPose)
starAnchors.add(anchor)
```
تحدّد الفئة ObjectPlacementHelper موقعًا مناسبًا لوضع النجمة من خلال النظر إلى وضع الضربة. يُستخدم الكائن starAnchors لعرض النجوم في عرض الواقع المعزّز.

التجربة الآن

شغِّل تطبيقك وانتقِل إلى مبنى في منطقتك.
بعد اكتمال عملية تحديد الموقع الجغرافي المكاني، وجِّه الكاميرا إلى المبنى وانقر على الشاشة. ستظهر نجمة على المبنى في وسط الشاشة.

يتم عرض النجوم في التطبيق

5- استخدام بيانات نقاط الارتكاز على الأسطح

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

إضافة سلوكيات إلى وضع البالون

يتضمّن المشروع وضعَين لوضع مواد العرض: وضع زهرة عباد الشمس الذي سبق لك استخدامه ووضع البالون.

لبرمجة سلوك وضع البالون، اتّبِع الخطوات التالية:

في الملف StreetscapeCodelabRenderer.kt، ابحث عن السطر التالي:
```
// TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
```

استخدِم وضع الضربة لإنشاء مكان رائع للبالون:

val transformedPose = ObjectPlacementHelper.createBalloonPose(frame.camera.pose, hit.hitPose)

حوِّل المتغيّر transformedPose إلى وضع جغرافي مكاني:

val earth = session?.earth ?: return
val geospatialPose = earth.getGeospatialPose(transformedPose)

أنشئ علامة ارتساء على السطح باستخدام خطوط الطول والعرض المحوَّلة:

earth.resolveAnchorOnRooftopAsync(
  geospatialPose.latitude, geospatialPose.longitude,
  0.0,
  transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
) { anchor, state ->
  if (!state.isError) {
    balloonAnchors.add(anchor)
  }
}

جرّبه الآن

شغِّل تطبيقك وانتقِل إلى مبنى في منطقتك.
بعد اكتمال عملية تحديد الموقع الجغرافي، انتقِل إلى وضع البالون وانقر على مبنى. سيظهر بالون فوق المبنى.

وضع البالونات على أسطح المباني

6. الخاتمة

تهانينا! لقد أنشأت تطبيق واقع معزّز يعرض هندسة المشهد الحضري في منطقتك ويتيح لك تزيين جوانبه بالنجوم. استخدمت أيضًا نقاط ربط على الأسطح لإضافة بالون إلى أعلى الأسطح من حولك.