إنشاء تجارب باستخدام Geospatial Creator وPlaces API من Google Maps Platform

1. قبل البدء

تتيح لك أداة Geospatial Creator في Unity، المستندة إلى ARCore وPhotorealistic 3D Tiles من "منصة خرائط Google"، إنشاء تجارب الواقع المعزّز (AR) وعرضها بسرعة لخطوط الطول والعرض المحدّدة، وكل ذلك ضمن Unity Editor. يمكن أن يقلّل ذلك بشكل كبير من الوقت المستغرَق في إنشاء مشهد واحد للواقع المعزّز يستند إلى الموقع الجغرافي لتطبيقك، ولكن ماذا لو أردت إنشاء تجارب مماثلة متعددة في مواقع مختلفة؟ باستخدام واجهة برمجة التطبيقات C# في Geospatial Creator، يمكنك إجراء ذلك أيضًا.

في هذا الدرس العملي، ستكتب رمز C# برمجيًا يستخدم أداة Geospatial Creator وPlaces API من "منصة خرائط Google" لإنشاء تجارب جغرافية مكانية متعددة باستخدام نموذج أولي. يمكن استكشاف التجارب الناتجة وضبطها بدقة في Unity Editor قبل تجميعها في تطبيق.

الكتاب على الارتفاع الصحيح

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

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

  • كيفية استخدام واجهات برمجة التطبيقات في Geospatial Creator لإنشاء تجربة واحدة محددة الموقع الجغرافي وعرضها في مواقع جغرافية متعددة
  • كيفية استخدام Places API من "منصة خرائط Google" للعثور على المواقع الجغرافية للأماكن
  • كيفية تشغيل تجربة الواقع المعزّز على جهازك

المتطلبات

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

لاستخدام أداة Geospatial Creator، عليك إعداد إذن الوصول إلى Photorealistic 3D Tiles وخدمات ARCore على Google Cloud وPlaces API من "منصة خرائط Google".

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

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

لإعداد مشروع في Google Cloud، اتّبِع الخطوات التالية:

  1. أنشِئ مشروعًا في وحدة تحكّم Google Cloud.إنشاء مشروع على Google Cloud
  2. في مربّع النص اسم المشروع، أدخِل اسمًا مناسبًا، مثل ARCore Geospatial Project، ثم اختَر أي موقع جغرافي.
  3. انقر على إنشاء.
  4. في وحدة تحكّم Google Cloud، انقر على إنشاء مشروع في صفحة اختيار المشروع.
  5. راجِع تفعيل الفوترة وأسعار Photorealistic 3D Tiles وأسعار Places API (جديدة).

تفعيل Map Tiles API

توفّر Map Tiles API مربّعات ثلاثية الأبعاد لصور واقعية تظهر في Unity Editor.

  • لتفعيل Map Tiles API، انقر على الزر التالي، ثم اختَر تفعيل:

تفعيل ARCore API

تتيح لك واجهة برمجة التطبيقات ARCore API على Google Cloud الوصول إلى ARCore Geospatial API على الجهاز المستهدف.

  • لتفعيل ARCore API، انقر على الزر التالي، ثم انقر على تفعيل:

تفعيل Places API

تتيح لك Places API من "منصة خرائط Google" الحصول على بيانات الموقع الجغرافي لأكثر من 200 مليون مكان، وستستخدمها في تجربة البرمجة للعثور على أماكن ذات صلة. توفّر واجهة برمجة التطبيقات هذه نتائج البحث والإحداثيات الجغرافية للأماكن.

  • لتفعيل Places API، انقر على الزر التالي، ثم انقر على تفعيل:

إنشاء مفتاح واجهة برمجة تطبيقات لمشروعك

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

  1. في Google Cloud Console، ضِمن واجهات برمجة التطبيقات والخدمات، اختَر بيانات الاعتماد.
  2. في أعلى الصفحة، انقر على إنشاء بيانات اعتماد، ثم اختَر مفتاح واجهة برمجة التطبيقات.
  3. دوِّن المفتاح لأنّك ستحتاج إليه في الخطوات التالية.

إعداد البرنامج

لبدء استخدام برنامج Geospatial Creator، اتّبِع الخطوات التالية:

  1. استنسِخ هذا المستودع.
  2. نزِّل Unity Hub واستخدِمه لتثبيت الإصدار 2022.3 من Unity. تأكَّد من تثبيت أدوات الإصدار الاختيارية لنظام التشغيل Android أو iOS.
  3. في Unity Hub، انقر على إضافة > إضافة مشروع من القرص.
  4. في لوحة التسلسل الهرمي (Hierarchy)، اختَر AR Geospatial Creator Origin.
  5. في مربّع النص مفتاح Google Maps Tile API، أدخِل مفتاح واجهة برمجة التطبيقات، ثم اضغط على Enter (أو return على نظام التشغيل macOS).إدراج مفتاح واجهة برمجة التطبيقات في حقل "نقطة انطلاق Geospatial Creator"
  6. في تعديل > إعدادات المشروع > إدارة إضافات XR > إضافات ARCore، استخدِم مصادقة مفتاح واجهة برمجة التطبيقات لكل من Android أو iOS وأدخِل مفتاح واجهة برمجة التطبيقات.
  7. في ملف (File) > إعدادات الإنشاء (Build Settings)، غيِّر النظام الأساسي المستهدف إلى Android أو iOS.

3- إنشاء أول نقطة ربط

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

لمحة عن مكوّن "الأصل" في Geospatial Creator

يتطلّب كل مشهد Unity تم إنشاؤه باستخدام Geospatial Creator عنصرًا واحدًا بالضبط من Geospatial Creator Origin. يمثّل عنصر اللعبة هذا نقطة مرجعية لتحويل قيم خطوط الطول والعرض والارتفاع في العالم الحقيقي إلى إحداثيات لعبة Unity.

يحتوي نموذج المشروع على Geospatial Creator Origin، الذي يستخدم Cesium لعرض Photorealistic 3D Tiles في طريقة العرض Scene في "المحرّر"، ويتيح لك تحديد المكان الذي سيظهر فيه محتوى الواقع المعزّز في العالم.

نقل نقطة الأصل

انقل نقطة الأصل في Geospatial Creator إلى خطوط الطول والعرض الخاصة بفرع المكتبة الرئيسية في سان فرانسيسكو.

لاستخدام ميزة التكامل المضمّنة في Geospatial Creator مع Places API لنقل نقطة الأصل تلقائيًا إلى الموقع الجغرافي الصحيح، اتّبِع الخطوات التالية:

  1. في لوحة التسلسل الهرمي، اختَر عنصر اللعبة Geospatial Creator Origin.
  2. في لوحة الفحص، انقر على البحث عن الموقع الجغرافي.
  3. في مربّع حوار البحث، اكتب San Francisco Public Library. يجب أن تكون النتيجة الأولى في 100 Larkin Street.
  4. انقر على تطبيق على الكائنات لتطبيق نتيجة البحث على الأصل. من المفترض أن تلاحظ تعديل خط العرض وخط الطول للمصدر إلى الإحداثيات الجديدة.

المبنى ظاهر

إضافة مرساة Geospatial Creator إلى المشهد

بعد إنشاء Origin، أضِف نقطة ارتساء في Geospatial Creator باستخدام GameObject > XR > AR Geospatial Creator Anchor. سيكون العنصر الثابت تلقائيًا في الموقع الجغرافي نفسه الذي تم فيه إنشاء العنصر.

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

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

  1. في لوحة المشروع، اسحب نموذج الكتاب إلى جزء نافذة عرض المحرّر.
  2. في لوحة البنية الهرمية، تأكَّد من أنّ الكتاب هو عنصر تابع للعنصر الأساسي الذي أنشأته سابقًا. سيتم تحديد موضع أي عنصر لعبة فرعي من عنصر Geospatial Creator الثابت بالنسبة إلى العنصر الثابت.
  3. في لوحة التسلسل الهرمي، اختَر الكتاب. اضبط قيم الموضع على 0 و0 و0.

تتم إضافة الكتاب إلى المشهد

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

على الرغم من إمكانية تحريك العنصر في المحرّر للعثور على الارتفاع التقريبي لنظام WGS84، يُفضّل ضبط نقاط الارتكاز الجغرافية المكانية كنقطة ارتكاز على السطح في هذه الحالة لتثبيت ارتفاعها تلقائيًا بالنسبة إلى سطح المبنى الذي تعلوه.

  • لإجراء ذلك، افتح لوحة فحص العنصر الثابت واضبط السمة Altitude Type على Rooftop.

لوحة "أداة الفحص"

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

  • لكي يطفو النموذج فوق سطح المكتبة بدلاً من أن يستقر عليه، غيِّر المَعلمة Altitude relative to rooftop لتصبح على ارتفاع 15 مترًا فوق السطح.

يظهر النموذج الآن بشكل جميل فوق المكتبة.

الكتاب على الارتفاع الصحيح

يتضمّن مشروعك الآن مشهدًا كاملاً للواقع المعزّز الجغرافي، بما في ذلك جميع مكوّنات نظام الواقع المعزّز المطلوبة، وGeospatial Creator Origin، وعنصر ربط واحد مع نموذج مرفق.

بعد ذلك، أنشئ نقاط ارتساء مكرّرة في مواقع جغرافية إضافية للمكتبة.

4. العثور على مواقع مرجعية جديدة باستخدام Places API

تتيح لك Places API من "منصة خرائط Google" الحصول على بيانات الموقع الجغرافي لأكثر من 200 مليون مكان. في هذا الدرس العملي، ستستخدم واجهة برمجة التطبيقات هذه للعثور على فروع أخرى للمكتبات العامة في سان فرانسيسكو واستخدام هذه النتائج لإنشاء نقطة ارتساء في Geospatial Creator لأول عشر نتائج بحث.

  • للبدء، انقر على الأصول > النصوص البرمجية > المحرّر، ثم افتح الملف ‘AnchorDuplicator.cs'. يوفّر هذا الملف بعض الرموز النموذجية التي تساعدك في بدء استخدام Places API وتحليل نتائجها.

المصادقة باستخدام Places API

  1. ابحث عن السطر التالي في فئة AnchorDuplicator:
    private const string API_KEY = "<YOUR_API_KEY_HERE>";
  2. استبدِل <YOUR_API_KEY_HERE> بالمفتاح الذي تم الحصول عليه في خطوات الإعداد.

إجراء طلب بحث في Places API عن عبارة بحث

بعد إكمال عملية إعداد تفويض Places API، يمكنك كتابة رمز برمجي يبدأ طلب POST.

  • لإجراء ذلك، ابحث عن طريقة CreatePlacesRequest واستخدِم تعريف الطريقة التالي:
    string postBody = "{ \"textQuery\": \"" + searchTerm + "\", " + 
                    "   \"locationBias\": { \"circle\": { " +
                    "      \"center\": { \"latitude\": " + lat + ", \"longitude\": " + lon + " }, " +
                    "      \"radius\": 10000 }" +
                    "   }" +
                    "}";

string url = "https://places.googleapis.com/v1/places:searchText";

UnityWebRequest request = UnityWebRequest.Post(url, postBody, "application/json");
request.SetRequestHeader("X-Goog-Api-Key", apiKey);
request.SetRequestHeader("X-Goog-FieldMask", "places.displayName,places.location");

return request;
    عند استدعاء الطريقة CreatePlacesRequest، يتم إرسال طلب يبحث عن searchTerm في دائرة تتمركز حول lat وlon.

اختبار عملك

قبل المتابعة، عليك التأكّد من أنّ الطلبات إلى Places API ناجحة.

  1. تشغيل الدوال في Unity Editor:
    1. في Google AR Codelab، انقر على Run Places Request.
    2. افتح وحدة تحكّم Unity. من المفترض أن تظهر لك النتائج.تظهر الأماكن في &quot;وحدة التحكّم&quot;.

5- إضافة نقاط ارتساء إلى الأماكن آليًا

بعد التأكّد من أنّ Places API يعثر على نتائج، أنشئ نقاط ارتساء جديدة في Geospatial Creator في كل موقع جغرافي محدّد في النتائج.

إنشاء عنصر في القائمة

  1. في الفئة AnchorDuplicator، ابحث عن الطريقة CreateNewAnchorsFromPlaces واستخدِم تعريف الطريقة التالي:
    if (_places == null)
{
    Debug.LogError("Cannot create anchors: Places has not been initialized.");
    return;
}

// You start with only one anchor in the scene, which you want to copy:
var prototypeAnchorObject = GameObject
    .FindObjectOfType<ARGeospatialCreatorAnchor>()
    .gameObject;

foreach (var place in _places)
{
    var newAnchorObject = GameObject.Instantiate(prototypeAnchorObject);
    var anchor = newAnchorObject.GetComponent<ARGeospatialCreatorAnchor>();
    anchor.Latitude = place.location.latitude;
    anchor.Longitude = place.location.longitude;

    newAnchorObject.name = place.displayName.text;
}
    يتحقّق عنصر القائمة هذا من طلب تم بدؤه سابقًا ويستخدم أول ARGeospatialCreatorAnchor في المشهد كنموذج أوّلي لإنشاء نقاط ارتكاز، واحدة لكل مكان في نتيجة Places API.
  2. استخدِم خيار القائمة الجديد إنشاء نقاط ارتساء جديدة من ردّ "الأماكن" في Google AR Codelab لإنشاء نقاط الارتساء.
  3. من المفترض أن تظهر لك عدة نقاط ارتساء في لوحة التسلسل الهرمي.

التحقّق من مواضع نقاط الارتكاز

للتأكّد من أنّ جميع مواد العرض مثبّتة في المواقع الجغرافية الصحيحة قبل تشغيل التطبيق، اتّبِع الخطوات التالية:

  1. انقر على نقطة ارتساء تمت إضافتها في لوحة التسلسل الهرمي.
  2. اضغط على F.
  3. افحص عنصر الربط في عرض Scene.
  4. إذا لم يكن موضع نقطة الارتكاز صحيحًا، انقر على المحاذاة مع المربّع أو غيِّر قيم Latitude أو Longitude أو Editor Override Altitude يدويًا.

6. عرض مادة العرض في الواقع المعزّز

لعرض مادة العرض في الواقع المعزّز على جهاز Android أو iOS متوافق مع ARCore، اتّبِع الخطوات التالية:

  1. انقر على ملف > إعدادات الإنشاء، ثم اختَر إما Android أو iOS كمنصات إنشاء.
  2. انقر على تبديل المنصة.
  3. تأكَّد من أنّ جهاز التطوير متصل وتم إعداده للتطوير.
  4. انقر على إنشاء وتشغيل.
  5. تأكَّد من أنّ التطبيق يعمل على جهازك.
  6. انتقِل إلى المواقع الجغرافية التي ثبّتّ فيها المحتوى. إذا لم تغيّر الأمثلة، ستكون المواقع الجغرافية عبارة عن مكتبات عامة في سان فرانسيسكو.

عرض تجربة الواقع المعزّز

7. الخاتمة

تهانينا! لقد كتبت تطبيق Unity يستخدم Geospatial Creator وPlaces API من "منصة خرائط Google" لإنشاء تجارب جغرافية مكانية متعدّدة باستخدام نموذج أولي. نأمل أن تتمكّن من استخدام هذه المعلومات لتوسيع نطاق وصول محتوى Geospatial Creator إلى الجمهور.

مزيد من المعلومات