بدء العمل مع صانع المحتوى الجغرافي المكاني في Unity

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

تتوفّر أداة Geospatial Creator كجزء من "إضافات ARCore" في AR Foundation. سيوضّح لك دليل البدء السريع هذا كيفية استخدام أداة Geospatial Creator في Unity لإضافة محتوى AR جغرافي مكاني إلى تطبيق ARCore Geospatial Sample.

إذا كان لديك تطبيق حالي تريد استخدامه بدلاً من Geospatial Sample، عليك أولاً اتّباع دليل مطوّري Geospatial لنظام Unity. بعد ضبط تطبيقك لاستخدام Geospatial API، انتقِل إلى خطوة إضافة التبعيات المطلوبة أدناه وواصِل من هناك.

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

اتّبِع الخطوات الواردة في "بدء استخدام ARCore Extensions مع AR Foundation" لإعداد بيئة Unity من أجل إنشاء تجارب الواقع المعزّز.

على الرغم من أنّ حزمة ARCore Extensions تتوافق مع الإصدارات القديمة من Unity، يتطلّب تطبيق Geospatial Creator الإصدار 2021.3 من Unity أو إصدارًا أحدث.

تفويض واجهة برمجة التطبيقات

عليك إعداد إذن الوصول إلى واجهة برمجة التطبيقات لاستخدام واجهة ARCore Geospatial API وواجهة Google Map Tiles API.

Google Map Tiles API

توفّر Map Tiles API تمثيلاً ثلاثي الأبعاد وواقعيًا للمواقع الجغرافية المتوافقة. سنستخدم هذه المربّعات في Unity Editor لمعاينة المنطقة المحيطة بمشهد الواقع المعزّز.

يمكنك الاطّلاع على صفحة Map Tiles API لتفعيل واجهة برمجة التطبيقات والتعرّف على مزيد من المعلومات حول Map Tiles.

ARCore Geospatial API

تستخدم واجهة ARCore Geospatial API في تطبيقك أثناء وقت التشغيل لإنشاء والتفاعل مع نقاط الارتكاز الجغرافية المكانية.

لتفعيل واجهات Geospatial API، عليك إعداد ARCore API في تطبيقك. يمكنك استخدام طريقة التفويض "بدون مفتاح" (ننصح بها) أو "مفتاح واجهة برمجة التطبيقات".

توسيع نطاق تطبيق Geospatial Sample

في هذا الدليل، سنوضّح لك كيفية استخدام أداة Geospatial Creator لإضافة محتوى جغرافي مكاني إلى تطبيق ARCore Geospatial Sample.

ضبط عيّنة البيانات الجيوفضائية

في البداية، تعرَّف على تطبيق ARCore Geospatial Sample. في مشروع Unity جديد، افتح Unity Package Manager واختَر حزمة ARCore Extensions. في لوحة تفاصيل "إدارة الحِزم"، وسِّع عينات واستورِد عينة Geospatial إلى مشروع Unity.

قبل تشغيل التطبيق، عليك تفعيل وظائف ARCore وGeospatial في مشروعك. استخدِم تعديل > إعدادات المشروع... > إدارة المكوّنات الإضافية لتقنيات الواقع الممتد (XR Plug-in Management). ضَع علامة في المربّعات المناسبة لتفعيل موفّر المكوّن الإضافي ARCore لنظام التشغيل Android و/أو موفّر المكوّن الإضافي ARKit لنظام التشغيل iOS.

بعد ذلك، انتقِل إلى تعديل (Edit) > إعدادات المشروع (Project Settings)... > إدارة المكوّنات الإضافية لتقنيات الواقع الممتد (XR Plug-in Management)، افتح لوحة إضافات ARCore. تأكَّد من وضع علامة في المربّع بجانب "بيانات جغرافية فضائية" (لست بحاجة إلى تفعيل أداة Geospatial Creator الآن)، وأدخِل بيانات اعتماد واجهة برمجة التطبيقات. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات "تفعيل Geospatial Unity API" لنظامَي التشغيل Android وiOS.

هناك بعض إعدادات Player الأخرى الخاصة بالنظام الأساسي والتي تكون مطلوبة لأي تطبيق Unity يستخدم ARCore. راجِع قسم ضبط إعدادات المشغّل في مستنداتنا لمعرفة التغييرات المطلوبة.

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

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

إضافة العناصر التابعة المطلوبة

يستفيد Geospatial Creator من حزمة Unity تابعة لجهة خارجية تُعرف باسم Cesium لعرض مربّعات "خرائط Google" في نافذة "المشهد" في Unity Editor. قبل تفعيل ميزات Geospatial Creator، لنضِف حزمة Cesium إلى مشروعك.

ننصحك بتثبيت أحدث إصدار من حزمة Cesium for Unity من صفحة GitHub الخاصة بـ Cesium:

  1. نزِّل أحدث إصدار من .tgz المُجمَّع مسبقًا من Cesium for Unity من صفحة إصدارات GitHub. الإصدار الحالي المقترَح من حزمة Cesium for Unity هو 1.1.0.
  2. افتح "مدير حِزم Unity" (Unity Package Manager) من خلال النقر على قائمة "النافذة" (Window) في Unity، ثم اختيار "مدير الحِزم" (Package Manager).
  3. انقر على رمز "+" واختَر "إضافة حزمة من ملف tarball".
  4. اختَر ملف ‎ .tgz الخاص بـ "Cesium for Unity" الذي نزّلته في الخطوة 1.
  5. قد يُطلب منك تثبيت تبعيات إضافية، مثل Text Mesh Pro.

إضافة حزمة ‎ .tgz باستخدام "مدير حزم Unity"

تفعيل Geospatial Creator

أنت الآن جاهز لتفعيل أداة "صناعة المحتوى الجغرافي المكاني":

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

بعد الانتهاء من المعالج، سيؤدي Unity إلى تجميع النصوص البرمجية. انتظِر إلى أن تكتمل عملية إعادة التجميع قبل المتابعة. (إذا لم يكن النظام الأساسي الذي اخترته هو Android أو iOS، يُرجى التبديل إلى أحدهما الآن).

إضافة مصدر Geospatial Creator باستخدام مربّعات الخرائط

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

لإضافة Geospatial Creator Origin إلى المشهد، انقر على Game Object > XR > Geospatial Creator Origin. يتطلّب العنصر الذي تم إنشاؤه حديثًا مرجعًا جغرافيًا يربط خط عرض وخط طول وارتفاعًا محدّدًا بموضع نقطة الأصل في إحداثيات اللعبة. من لوحة الفحص في Geospatial Creator Origin، أضِف مرجعًا جغرافيًا بالنقر على الزر إضافة مكوّن مرجع جغرافي في Cesium.

إضافة عنصر GameObject الخاص بميزة "مصدر Geospatial Creator"

بالإضافة إلى كونها نقطة مرجعية لكائنات الواقع المعزّز، تضيف أداة Cesium Georeference كائن Cesium 3D Tileset إلى المشهد. سيعرض هذا العنصر مربّعات "خرائط Google" في "طريقة عرض المشهد" في "المحرّر"، ما يتيح لك تصور المكان الذي سيظهر فيه محتوى الواقع المعزّز في العالم. يتوفّر حقل في أداة فحص Geospatial Creator Origin لإضافة مفتاح Map Tiles API الذي أعددته سابقًا. بعد ضبط هذا المفتاح، من المفترض أن تظهر مربّعات الخريطة في "طريقة العرض Scene".

الآن، غيِّر حقول خطوط الطول والعرض والارتفاع لتكون بالقرب من المكان الذي تريد أن يظهر فيه محتوى الواقع المعزّز في تطبيقك.

من المفترض أن تعرض "طريقة عرض المشهد" (Scene View) في "المحرّر" (Editor) الآن مربّعات الخريطة عند خط العرض وخط الطول المحدّدين للموقع الأصلي. في وقت التشغيل، نفترض أنّ تطبيقك سيستخدم كاميرا الواقع المعزّز، لذا يكون Geospatial Creator قد أعدّ مسبقًا كائن مجموعة مربّعات الخرائط الثلاثية الأبعاد من Cesium باستخدام العلامة "EditorOnly". لهذا السبب، لن يتم تنزيل المربّعات أو عرضها في وقت التشغيل في لعبتك. يمكن تغيير ذلك من خلال أداة فحص عنصر Cesium3DTileset. لمزيد من المعلومات حول ميزة "الإشارة الجغرافية" من Cesium و3D Tileset GameObjects، يُرجى الرجوع إلى مستندات Cesium for Unity.

إضافة نقطة ارتساء في "صناعة المحتوى الجغرافي المكاني" ووضعها

أنت الآن جاهز لوضع محتوى الواقع المعزّز في المشهد. انقر على GameObject > XR > Geospatial Creator Anchor لإضافة نقطة ارتساء إلى بنية المشهد. من خلال "أداة فحص العنصر الثابت" (Anchor's inspector)، يمكنك تحديد خط عرض وخط طول وارتفاع دقيق. سيتم تعديل تحويل الكائن على الفور إلى الموضع الصحيح في المشهد، ويمكنك معرفة المكان الذي سيظهر فيه الكائن بالضبط.

إضافة أداة "المرتكز" في Geospatial Creator

أثناء ضبط خطَّي العرض والطول الخاصَّين بنقطة الارتكاز، اختَر مكانًا قريبًا حتى تتمكّن من التأكّد من أنّه في المكان الصحيح أثناء وقت التشغيل. عند ضبط ارتفاع نقطة ربط Geospatial Creator، تتوفّر لك ثلاثة خيارات:

  • تضع التضاريس نقطة الارتكاز على مستوى الأرض عند خط العرض وخط الطول المحدّدَين. يتم تحديد مستوى الأرضية في وقت التشغيل من خلال نظام تحديد المواقع المرئية. إذا كنت جديدًا على واجهات برمجة التطبيقات الجغرافية المكانية في ARCore، يُعدّ الخيار "التضاريس" خيارًا جيدًا لأنّه سيتم تحديد موضع المرساة مباشرةً على الأرض بدقة عمودية عالية. يتيح لك حقل "إزاحة الارتفاع" تحديد موضع نقطة الارتكاز أعلى أو أسفل مستوى سطح الأرض بمقدار ثابت، وذلك بالأمتار. على سبيل المثال، يؤدي تحديد إزاحة بقيمة "1.0" إلى جعل نقطة الارتكاز "تطفو" على ارتفاع متر واحد فوق التضاريس.
  • يضع السطح نقطة الارتكاز بالنسبة إلى أعلى أي مبنى عند خط العرض والطول المحدّدَين. على غرار أداة تثبيت التضاريس، يتيح لك حقل "إزاحة الارتفاع" تحريك أداة التثبيت للأعلى أو للأسفل بالنسبة إلى موضع السطح، وذلك بالأمتار.
  • يضع نظام WGS84 نقطة الارتكاز على ارتفاع مطلق معيّن، بالأمتار، استنادًا إلى نظام إحداثيات WGS84. قد يتطلّب وضع العنصر بهذه الطريقة بعض المحاولات، لأنّ الارتفاع "0" في نظام WSG84 لا يشير بالضرورة إلى مستوى سطح البحر وقد لا يتطابق مع الارتفاع الذي يحدّده نظام تحديد المواقع العالمي (GPS). بالإضافة إلى ذلك، على الرغم من أنّ خطوط الطول والعرض للعناصر الثلاثية الأبعاد المعروضة دقيقة للغاية، قد تؤدي محاولة وضع العنصر على مستوى سطح الأرض باستخدام هذه العناصر كمرجع إلى حدوث خطأ في الارتفاع يصل إلى عدة أمتار.

لمزيد من المعلومات حول الأنواع المختلفة من نقاط الارتكاز الجغرافية المكانية في ARCore، يُرجى الرجوع إلى دليل المطوّرين الجغرافي المكاني.

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

إضافة شكل هندسي إلى نقطة الارتكاز

إذا أنشأت التطبيق وشغّلته الآن، لن يظهر لك العنصر الثابت في تطبيقك المتوافق مع الواقع المعزّز، لأنّه لا يتضمّن أي أشكال هندسية. لنضِف عنصرًا أساسيًا ثلاثي الأبعاد بسيطًا إلى نقطة الارتكاز: في بنية المشهد الهرمية، انقر بزر الماوس الأيمن على عنصر AR Geospatial Creator Anchor. من قائمة السياق، اختَر كائن ثلاثي الأبعاد > مكعّب. من المفترض أن يظهر مكعّب رمادي في طريقة عرض المشهد كعنصر ثانوي لعنصر الارتساء. إذا قرّرت تغيير موضع العنصر أو نسبة دورانه في "أداة التعديل"، ننصحك بتغيير موضع العنصر Anchor الأساسي بدلاً من العنصر Cube الفرعي. سيساعد ذلك في تقليل الخطأ في الترجمة من خطوط الطول والعرض إلى إحداثيات اللعبة.

نقطة ربط في أداة Geospatial Creator باستخدام عنصر أساسي على شكل مكعّب

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

إنشاء تطبيقك وتشغيله

حان الوقت لرؤية المرساة في العالم الحقيقي! جرِّب إنشاء تطبيقك وتشغيله، ثم انتقِل إلى الموقع الجغرافي الذي تتوقّع أن يظهر فيه المكعّب. هل هي موجودة؟ تهانينا، أنت الآن جاهز لإنشاء تجارب واقع معزّز أكثر تعقيدًا باستخدام Geospatial Creator.

إذا واجهت أي مشاكل، راجِع دليل تحديد المشاكل وحلّها.

حان الوقت الآن لإضافة نقاط ربط إضافية في AR Geospatial Creator بأشكال هندسية مختلفة. ننصحك بتجربة استخدام نقاط ربط متعددة على الأسطح والتضاريس مع إزاحاتها. إضافة نصوص برمجية لتحريك العناصر أو تفعيل التفاعلات معها

التعرّف على نقاط الارتكاز في Geospatial Creator وفئة ARGeospatialAnchor

عند إنشاء تجارب واقع معزّز معقّدة وتفاعلية، من المفيد فهم العلاقة بين عناصر Geospatial Creator Anchors وARGeospatialAnchor فئة C#‎ في ARCore:

لا يمكن إنشاء ARGeospatialAnchor إلا في وقت التشغيل من خلال استدعاء إحدى الدوال في ARAnchorManager، ولا يمكن إنشاؤها إلا بعد استقرار جلسة الواقع المعزّز. يمكن اعتبار مرساة Geospatial Creator Anchor عنصرًا نائبًا في المشهد، ينتظر أن تصبح جلسة الواقع المعزّز جاهزة لتحديد ARGeospatialAnchor. بعد أن تصبح الجلسة جاهزة، سيطلب العنصر النائب تلقائيًا من ARAnchorManager إنشاء ARGeospatialAnchor وحلّه.

بعد تحديد موقع المرساة في وقت التشغيل مباشرةً، سيتم ربط Geospatial Creator Anchor في بنية المشهد كعنصر تابع بـ GameObject الجديد. يعني ذلك أنّ أي مكوّنات أو عناصر تابعة لعنصر Geospatial Creator Anchor ستصبح مكوّنات فرعية أو عناصر تابعة للعنصر الجديد ARGeospatialAnchor GameObject. على سبيل المثال، سترث transform لعنصر هندسي أساسي مرتبط بـ Geospatial Creator Anchor قيمة transform من ARGeospatialAnchor، وبالتالي سيتم وضعه في الموقع الجغرافي المتوقّع في جلسة الواقع المعزّز أثناء وقت التشغيل.

إذا كنت بحاجة إلى تحديد ARGeospatialAnchor GameObjects معيّنة في وقت التشغيل، يمكنك البحث في المشهد عن العناصر التي تتطابق سمة name فيها مع نقطة الارتكاز التي تم إنشاؤها باستخدام Geospatial Creator. إذا تم بدء جلسة الواقع المعزّز، سيكون parent لهذا العنصر هو عنصر ARGeospatialAnchor المقابل.

تحديد المشاكل وحلّها

لماذا يتحرّك نقطة الارتكاز؟

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

لماذا يظهر المرساة على ارتفاع غير صحيح؟

عند استخدام نوع الارتفاع "يدوي" لـ "نقاط ربط Geospatial Creator"، سيتم ضبط ارتفاع نقطة الربط (بالمتر) وفقًا لنظام WGS84. في موقع جغرافي معيّن، قد يكون هناك تفاوت يصل إلى عدة أمتار بين مستوى سطح الأرض الظاهر في مربّعات الخريطة ومستوى سطح الأرض الفعلي الذي يتم رصده بواسطة نظام تحديد المواقع المرئي (VPS) من Google. إذا بدا أنّ Geospatial Anchor يقع بشكل غير صحيح أثناء وقت التشغيل، ننصحك بالتحقّق من ارتفاع نظام تحديد المواقع المرئية (VPS) شخصيًا باستخدام طبقة تصحيح الأخطاء في التطبيق النموذجي. يمكنك بعد ذلك تغيير الارتفاع في "محرّر Unity" ليتطابق مع ارتفاع نظام تحديد المواقع المرئية (VPS) المعروف في هذا الموقع الجغرافي.

لا يتم عرض مربّعات الخريطة بشكل صحيح في "طريقة عرض المشهد" في "أداة التعديل"

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

لإضافة Shader Graph، افتح "إدارة حزم Unity" (Window > Package Manager). تأكَّد من أنّك تتصفّح الحِزم المتاحة في "مستودع حِزم Unity" (Unity Package Registry) من خلال اختيار "الحِزم: مستودع حِزم Unity" (Packages: Unity Registry) من القائمة المنسدلة في أعلى نافذة "إدارة الحِزم" (Package Manager). ابحث عن حزمة com.unity.shadergraph وثبِّت أحدث إصدار. بعد تحميل الحزمة، من المفترض أن تتم إعادة تحميل المربّعات الثلاثية الأبعاد وعرضها بشكل صحيح في "عرض المشهد".

يعرض التطبيق شاشة سوداء أثناء التشغيل بدلاً من عرض الكاميرا

لا يتم ضبط Universal Rendering Pipeline (URP) من Unity تلقائيًا لكاميرا الواقع المعزّز. إذا ظهرت شاشة سوداء أثناء وقت التشغيل بدلاً من ناتج الكاميرا، عليك إضافة AR Background Renderer Feature إلى كل أداة عرض URP في المشهد.

إضافة ميزة "أداة عرض الخلفية في الواقع المعزّز"

لإضافة الميزة، ابحث عن "renderer" في مشروعك. بالنسبة إلى كل عنصر URP Renderer، انقر على الزر "إضافة ميزة العرض" (Add Renderer Feature) في "نافذة الفحص" (Inspector) وأضِف أداة عرض الخلفية AR Background Renderer.

لماذا يبدو أنّ نقاط الارتكاز الموضوعة بعيدًا عن نقطة الأصل موضوعة بشكل غير صحيح؟

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