العمل مع الوضعيات الجغرافية المكانية باستخدام ARCore for Jetpack XR

أجهزة XR المعنيّة
تساعدك هذه الإرشادات في إنشاء تجارب لهذه الأنواع من أجهزة الواقع الممتد.
مزيد من المعلومات حول أنواع أجهزة XR →
نظارات AI Glasses
مزيد من المعلومات حول أنواع أجهزة XR →

باستخدام Geospatial API في ARCore for Jetpack XR، يمكن لتطبيقك ربط المحتوى عن بُعد بأي منطقة تغطيها خدمة التجوّل الافتراضي من Google وإنشاء تجارب واقع معزّز على نطاق عالمي. تستخدم Geospatial API بيانات مستشعر الجهاز ونظام تحديد المواقع العالمي (GPS) لرصد البيئة المحيطة بالجهاز، ثم تطابق الأجزاء التي يمكن التعرّف عليها من تلك البيئة مع نموذج تحديد الموقع الجغرافي الذي يوفّره نظام تحديد المواقع المرئية (VPS) من Google لتحديد الموقع الجغرافي الدقيق لجهاز المستخدم. تتولّى واجهة برمجة التطبيقات أيضًا دمج الإحداثيات المحلية للمستخدم مع الإحداثيات الجغرافية من نظام تحديد المواقع المرئية (VPS)، ما يتيح لك العمل ضمن نظام إحداثيات واحد.

تفعيل ARCore API

قبل استخدام نظام تحديد المواقع المرئية (VPS) في تطبيقك، عليك أولاً تفعيل ARCore API في مشروع جديد أو حالي على Google Cloud. تتولّى هذه الخدمة استضافة نقاط الارتكاز الجغرافية المكانية وتخزينها وحلّها.

إضافة تبعيات مكتبة إضافية

يتطلّب استخدام Geospatial API بعض العناصر الاعتمادية الإضافية للمكتبة. أضِف ما يلي إلى ملف build.gradle.kts في تطبيقك:

Groovy

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation "com.google.android.gms:play-services-location:21.3.0"
}

Kotlin

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation("com.google.android.gms:play-services-location:21.3.0")
}

طلب الأذونات المطلوبة

لاستخدام Geospatial API في ARCore مع Jetpack XR، يجب أن يطلب تطبيقك أذونات وقت التشغيل التالية:

تضمين أذونات التطبيق في بيان الأذونات

قبل أن تتمكّن من طلب هذه الأذونات في وقت التشغيل، عليك تحديدها في ملف البيان الخاص بتطبيقك:

<manifest ... >
  <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
</manifest>

طلب الحصول على الأذونات

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

لا يمكن لواجهة Geospatial API أن تعمل ما لم تتمكّن من تحديد الموقع الجغرافي الدقيق للمستخدم. لهذا السبب، اتّبِع الإرشادات الخاصة بطلب أذونات تحديد الموقع الجغرافي في وقت التشغيل حتى يتم منح تطبيقك الإذنَين ACCESS_FINE_LOCATION وACCESS_COARSE_LOCATION.

الوصول إلى جلسة

الوصول إلى المعلومات الجغرافية المكانية من خلال Session Jetpack XR Runtime، الذي يجب أن ينشئه تطبيقك

ضبط الجلسة

لا يتم تفعيل معلومات وضع الجهاز تلقائيًا في جلسات XR. لتمكين تطبيقك من استرداد معلومات وضع الجهاز، اضبط الجلسة واضبط الوضعين GeospatialMode.VPS_AND_GPS وDeviceTrackingMode.LAST_KNOWN:

// Define the configuration object to enable Geospatial features.
val newConfig = session.config.copy(
  // Set the GeospatialMode to VPS_AND_GPS.
  geospatial = Config.GeospatialMode.VPS_AND_GPS
  // Set the DeviceTrackingMode to LAST_KNOWN.
  deviceTracking = Config.DeviceTrackingMode.LAST_KNOWN
)

// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureGooglePlayServicesLocationLibraryNotLinked -> {
            // This case generally indicates a missing library dependency.
        }
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }
        else -> {
            // Catch-all for other configuration errors returned using the result class.
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure. For example, if the specific mode is not supported on the current device or API version.
}

يستفيد وضع GeospatialMode.VPS_AND_GPS من بيانات نظام تحديد المواقع المرئية (VPS) ونظام تحديد المواقع العالمي (GPS) لتحديد الموقع الجغرافي المكاني للجهاز بدقة.

لا تتوافق بعض أجهزة XR مع الوضعَين GeospatialMode.VPS_AND_GPS وDeviceTrackingMode.LAST_KNOWN. في حال نجاح Session.configure()، يعني ذلك أنّ الجهاز يتيح هذه الأوضاع.

مطالبة المستخدم بالسماح باستخدام بيانات الجهاز

يجب أن تعرض التطبيقات التي تستخدم Geospatial API مع ARCore for Jetpack XR رسالة تطلب من المستخدم الموافقة على استخدام البيانات من جهازه. لمزيد من المعلومات، يمكنك الاطّلاع على متطلبات خصوصية المستخدم.

الحصول على الكائن Geospatial

بعد إعداد الجلسة، احصل على عنصر Geospatial باستخدام Geospatial.getInstance(session):

// Get the Geospatial instance
var geospatial = Geospatial.getInstance(session)

يجب استخدام العنصر Geospatial فقط عندما تكون حالته State.RUNNING. يمكنك مراقبة الحالة باستخدام Geospatial.state StateFlow<Geospatial.State>.

التحقّق من توفّر الخادم الخاص الافتراضي

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

في الظروف العادية، يمكنك توقّع أن توفّر خدمة VPS دقة تحديد المواقع الجغرافية تبلغ أقل من 5 أمتار، ودقة تحديد الاتجاه تبلغ 5 درجات. يمكنك التحقّق مما إذا كان الموقع الجغرافي يتضمّن تغطية VPS باستخدام وظيفة التعليق Geospatial.checkVpsAvailability(latitude, longitude). هذه المكالمة هي عملية غير متزامنة ولا تتطلّب ضبط الجلسة على الوضع GeospatialMode.VPS_AND_GPS.

يوضّح الرمز التالي كيفية التحقّق من توفّر نظام تحديد المواقع المرئية (VPS) من خط عرض وخط طول محدّدين:

// You can query the GPS to get the current device's location and check if it has VPS
val latitude = getLatitudeFromGPS()
val longitude = getLongitudeFromGPS()

// Must be called from a coroutine.
val result = geospatial.checkVpsAvailability(latitude, longitude)
if (result is VpsAvailabilityAvailable) {
  // VPS is available
} else if (result is VpsAvailabilityUnavailable) {
  // VPS is not available
}

يجب إعداد تطبيقك بشكل صحيح للتواصل مع ARCore API على Google Cloud، وإلا سيتلقّى تطبيقك النتيجة VpsAvailabilityNotAuthorized.

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

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

يمكن أن يساعدك ذلك في ما يلي:

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

لتحويل وضعية الجهاز إلى وضعية جغرافية فضائية باستخدام Geospatial.createGeospatialPoseFromPose()، اتّبِع الخطوات التالية:

// Get the current device Pose from the AR Session's state
// This is the device's position and orientation relative to the AR tracking origin.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose
when (val geospatialPoseResult = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val currentGeospatialPose = geospatialPoseResult.pose
        val horizontalAccuracy = geospatialPoseResult.horizontalAccuracy
        // ... use pose and accuracy
     val latitude = currentGeospatialPose.latitude
     val longitude = currentGeospatialPose.longitude
    // The orientation is stored as a Quaternion in the EUS (East-Up-South) system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south. True North is aligned with the -Z axis.
     val eusQuaternion = currentGeospatialPose.eastUpSouthQuaternion

    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}

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

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

لتحويل وضع جغرافي مكاني إلى وضع جهاز باستخدام Geospatial.createPoseFromGeospatialPose()، اتّبِع الخطوات التالية:

when (val poseResult = geospatial.createPoseFromGeospatialPose(geospatialPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose = poseResult.pose
    // devicePose is now ready to be used
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}