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

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

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

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

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

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

على الرغم من أنّ إضافات ARCore متوافقة مع الإصدارات السابقة من Unity، يحتاج صانع المحتوى الجغرافي المكاني إلى استخدام Unity 2021.3 أو إصدار أحدث.

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

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

واجهة برمجة تطبيقات Tiles في "خرائط Google"

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

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

واجهة برمجة تطبيقات ARCore Geospatial

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

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

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

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

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

أولاً، تعرف على تطبيق ARCore Geospatial عيّنة. في مشروع Unity جديد، افتح مدير حزمة Unity واختر حزمة إضافات ARCore. في لوحة تفاصيل "مدير الحزمة"، وسِّع عيّنات واستورِد العينة الجيوفضائية إلى مشروع Unity.

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

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

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

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

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

إضافة التبعيات المطلوبة

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

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

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

تفعيل ميزة صانع المحتوى الجغرافي المكاني

أنت الآن جاهز لتفعيل ميزة "المنشئ الجغرافي المكاني":

1. من مربّع الحوار "إعدادات الإصدار"، تأكّد من أنّ النظام الأساسي الذي اخترته هو "Android" أو "iOS". إنّ ميزات صانع المحتوى الجغرافي المكانية غير متاحة حاليًا للمنصات الأخرى.
2. انتقِل إلى Project Settings (إعدادات المشروع) > XR Plug-in Management (إدارة مكوّنات XR الإضافية) > ARCore Extensions.
3. إذا لم يسبق لك ضبط مفاتيح واجهة برمجة تطبيقات ARCore لنظام التشغيل Android و/أو iOS في خطوة سابقة، يُرجى التأكّد من ضبطها الآن.
4. تفعيل خيارَي التبديل بين "الموقع الجغرافي" و "صانع المحتوى الجيوفضائي". بعد النقر لتفعيل زر إيقاف/تفعيل أداة إنشاء المواقع الجغرافية المكانية، سيتم عرض معالج غير مشروط لتأكيد توافق مشروعك مع أداة إنشاء المواقع الجغرافية المكانية.
5. انقر فوق "إنهاء" في المعالج.

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

إضافة مصدر صانع محتوى جغرافي مكاني باستخدام مربّعات الخرائط

يحتاج المشهد إلى عنصر واحد فقط من نوع "مصدر صانع المحتوى الجغرافي المكاني". يُستخدم هذا الكائن كنقطة مرجعية لتحويل قيم خطوط الطول والعرض في العالم الحقيقي إلى إحداثيات لعبة Unity.

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

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

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

من المفترض أن يُظهر "عرض المنظر" في "محرّر إعلانات Google" الآن مربّعات الخرائط المحدّدة في خط العرض وخط الطول الأصليَّين. نفترض في وقت التشغيل أن تطبيقك سيستخدم كاميرا الواقع المعزّز، لذا قد أجرى صانع المحتوى الجغرافي المكاني ضبط كائن Cesium 3D Map Tileset باستخدام العلامة "Editor Only". وبسبب ذلك، لن يتم تنزيل المربّعات أو عرضها أثناء وقت التشغيل في لعبتك. يمكن تغيير هذا من عارض الكائن Cesium3DTileset. ولمعرفة المزيد من المعلومات حول مرجع Cesium التابع لـ Cesium وكائنات GameObjects الثلاثية الأبعاد، راجع وثائق Cesium for Unity.

إضافة وضع ثابت صانع محتوى جغرافي مكاني

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

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

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

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

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

إضافة "هندسة" إلى علامة الارتساء

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

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

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

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

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

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

فهم الروابط الجغرافية المكانية لصنّاع المحتوى وفئة ARGeospatialAnchor

عند إنشاء تجارب واقع معزز وتفاعلية، من المفيد فهم العلاقة بين منشئي المحتوى الجيوفضائيين وفئة ARGeospatialAnchor C# من ARCore:

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

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

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

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

لماذا يتم تغيير موضع الإعلان الثابت؟

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

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

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

لا يتم عرض مربعات الخرائط بشكل صحيح في عرض المشهد في المحرر

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

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

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

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

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

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

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