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

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

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

تفعيل 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.

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

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

ضبط الجلسة

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

// Define the configuration object to enable Geospatial features.
val newConfig = Config(
    // Set the GeospatialMode to VPS_AND_GPS.
    geospatial = GeospatialMode.VPS_AND_GPS,
    // Set the DeviceTrackingMode to LAST_KNOWN.
    deviceTracking = DeviceTrackingMode.LAST_KNOWN
)
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }
        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Geospatial.kt

يستفيد الوضع 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 for the current session.
val geospatial = Geospatial.getInstance(session)
Geospatial.kt

يجب استخدام العنصر 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.
val latitude = 37.422
val longitude = -122.084

// Use the geospatial instance to check VPS availability for a specific location.
val result = geospatial.checkVpsAvailability(latitude, longitude)
when (result) {
    is VpsAvailabilityAvailable -> {
        // VPS is available at this location.
    }
    is VpsAvailabilityErrorInternal -> {
        // VPS availability check failed with an internal error.
    }
    is VpsAvailabilityNetworkError -> {
        // VPS availability check failed due to a network error.
    }
    is VpsAvailabilityNotAuthorized -> {
        // VPS availability check failed due to an authorization error.
    }
    is VpsAvailabilityResourceExhausted -> {
        // VPS availability check failed due to resource exhaustion.
    }
    is VpsAvailabilityUnavailable -> {
        // VPS is not available at this location.
    }
}
Geospatial.kt

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

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

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

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

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

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

// Get the current device Pose from the AR Session's state.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose.
when (val result = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val geoPose = result.pose
        val lat = geoPose.latitude
        val lon = geoPose.longitude
        val alt = geoPose.altitude
        // Orientation is in the EUS (East-Up-South) coordinate system.
        val orientation = geoPose.eastUpSouthQuaternion
    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt

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

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

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

// Convert a GeospatialPose (lat/long/alt) back to a device-space Pose.
when (val result = geospatial.createPoseFromGeospatialPose(geoPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose: Pose = result.pose
        // devicePose is now ready to be used relative to the tracking origin.
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt