بدء استخدام واجهتَي برمجة التطبيقات Scene Semantics وGeospatial Depth في ARCore

1. قبل البدء

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

تستخدم Scene Semantics API نموذج تعلُّم الآلة (ML) لتحليل صور الكاميرا وتقديم صورة لوحدات البكسل المصنّفة. ويمكنه التمييز بين 11 تصنيفًا مختلفًا للأماكن الخارجية.

تجمع واجهة برمجة التطبيقات Geospatial Depth API بين معلومات العمق من الحركة وأي أجهزة استشعار نشطة، مثل أجهزة استشعار قياس الوقت المنقضي، مع بيانات واجهة برمجة التطبيقات Streetscape Geometry API. يحسِّن هذا الوضع الأخطاء في عمليات رصد العمق على مسافة تصل إلى 65 مترًا.

في هذا الدرس العملي، ستنشئ تطبيق واقع معزّز يعرض نتائج واجهتَي برمجة التطبيقات Scene Semantics وGeospatial Depth.

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

• معرفة أساسية AR

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

• كيفية تفعيل واجهة برمجة التطبيقات Scene Semantics API
• كيفية الحصول على صورة دلالية وعرضها
• كيفية الحصول على صورة ذات دلالة إحصائية عالية وعرضها
• كيفية تحديد النسبة المئوية للبكسل التي تتوافق مع تصنيف معيّن
• كيفية إعداد مشروع على Google Cloud يمكنه استخدام واجهات ARCore Geospatial API
• كيفية تفعيل Geospatial Depth API
• كيفية عرض صور العمق

المتطلبات

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

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

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

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

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

3- عرض بيانات Scene Semantics API بشكل مرئي

تفعيل واجهة برمجة التطبيقات Scene Semantics API

يتم إيقاف واجهة برمجة التطبيقات Scene Semantics API تلقائيًا لتوفير طاقة المعالجة.

لتفعيل Scene Semantics API، اتّبِع الخطوات التالية:

1. في الملف CodelabActivity.kt، ابحث عن السطر التالي:

   // TODO: Enable the Scene Semantics API.
   

2. بعد هذا السطر، فعِّل Scene Semantics API في إعدادات الجلسة إذا كان جهازك يتيح ذلك:

   if (session.isSemanticModeSupported(Config.SemanticMode.ENABLED)) {
     semanticMode = Config.SemanticMode.ENABLED
   }
   

الحصول على صورة دلالية وعرضها

الصورة الدلالية هي نتيجة نموذج تعلُّم الآلة في ARCore الذي يحدّد قيمة SemanticLabel Enum لكل بكسل في خلاصة الكاميرا.

للحصول على صورة دلالية وعرضها على الشاشة، اتّبِع الخطوات التالية:

1. في الملف CodelabRenderer.kt، ابحث عن السطر التالي:

   // TODO: Obtain the semantic image for this frame.
   

2. بعد هذا السطر، احصل على صورة دلالية:

   frame.acquireSemanticImage().use { image ->
     semanticRenderer.updateCameraSemanticsTexture(image)
     activity.view.semanticLabelAtCenter = getLabelAt(image, image.width/2, image.height/2)
   }
   

   يتم استخدام الصورة الدلالية في الفئة SemanticRenderer لعرضها على الشاشة. عدِّل المتغيّر semanticLabelAtCenter لعرض التصنيف الدلالي في منتصف الشاشة في طريقة عرض التطبيق.
3. شغِّل تطبيقك ووجِّه الكاميرا نحو عناصر مختلفة في الخارج. يتغيّر عرض التصنيف الدلالي عند النظر إلى أنواع مختلفة من العناصر.
4. انقر على الإعدادات لتفعيل تراكب الصور الدلالي.

الحصول على صورة دلالية للثقة وعرضها

تقدّم صورة الثقة الدلالية إشارة إلى مدى ثقة ARCore في التصنيف الدلالي عند البكسل المطابق.

للحصول على صورة دلالية وعرضها على الشاشة، اتّبِع الخطوات التالية:

1. في الملف CodelabRenderer.kt، ابحث عن السطر التالي:

   // TODO: Obtain the confidence image for this frame.
   

2. بعد هذا السطر، احصل على صورة دلالية:

   frame.acquireSemanticConfidenceImage().use { image ->
     semanticRenderer.updateConfidenceSemanticsTexture(image)
     activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
   }
   

   يتم استخدام صورة الثقة الدلالية في الفئة SemanticRenderer لعرضها على الشاشة. عدِّل المتغيّر confidenceAtCenter لعرض التصنيف الدلالي في منتصف الشاشة في طريقة عرض التطبيق.
3. شغِّل تطبيقك ووجِّه الكاميرا نحو عناصر مختلفة في الخارج. يتغيّر عرض الثقة الدلالية عند النظر إلى أنواع مختلفة من العناصر.
4. انقر على الإعدادات لتفعيل تراكب الصور الدلالي.

تحديد مدى شيوع تصنيف معيّن

تشير نسبة انتشار التصنيف إلى النسبة المئوية لصورة دلالية تساوي تصنيفًا معيّنًا. على سبيل المثال، إذا كانت% 26 من الصورة تتضمّن القيمة SemanticLabel.SKY، تكون قيمة الانتشار للقيمة SemanticLabel.SKY هي 0.26f.

للحصول على مدى توفّر التصنيفات وعرضها على الشاشة، اتّبِع الخطوات التالية:

1. في الملف CodelabRenderer.kt، ابحث عن السطر التالي:

   // TODO: Obtain the prevalence of the selected label for this frame.
   

2. بعد هذا السطر، احصل على معدّل الانتشار للتصنيف المحدّد:

   activity.view.fractionOfLabel = frame.getSemanticLabelFraction(activity.view.selectedSemanticLabel)
   

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

4. عرض بيانات Geospatial Depth API

تعمل واجهة برمجة التطبيقات Geospatial Depth API على تحسين قراءات العمق عند تفعيل واجهتَي برمجة التطبيقات Geospatial API وStreetscape Geometry API. لاستخدام Geospatial Depth API مع Kotlin وAndroid Studio، يجب أن يكون لديك مشروع على Google Cloud.

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

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

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

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

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

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

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

1. في "استوديو Android"، انقر على app > src وانقر مرّتين على AndroidManifest.xml.
2. ابحث عن إدخالات meta-data التالية:

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

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

تأكيد مشروعك

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

تنبيه: إذا لم يتم تهيئة Geospatial API، تأكَّد من إدراج مفتاح واجهة برمجة التطبيقات في ملف AndroidManifest.xml تمامًا كما هو معروض في Google Cloud.

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

تتطلّب Geospatial Depth API تفعيل ثلاثة إعدادات في إعدادات جلسة تطبيقك.

لتفعيلها، اتّبِع الخطوات التالية:

1. في الملف CodelabRenderer.kt، ابحث عن السطر التالي:

   // TODO: Enable the Geospatial API, the Streetscape Geometry API, and the Depth API.
   

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

   val isDepthSupported = session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)
   val isGeospatialSupported = session.isGeospatialModeSupported(Config.GeospatialMode.ENABLED)
   if (isDepthSupported && isGeospatialSupported) {
     // These three settings are needed to use Geospatial Depth.
     geospatialMode = Config.GeospatialMode.ENABLED
     streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
     depthMode = Config.DepthMode.AUTOMATIC
   }
   

عرض معلومات العمق

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

5- الخاتمة

تهانينا! لقد أنشأت تطبيق واقع معزّز يعرض دلالات المشهد والعمق الجغرافي المكاني.

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

• دليل المطوّر لواجهة برمجة التطبيقات Scene Semantics API
• دليل المطوّرين لواجهة برمجة التطبيقات Geospatial Depth API