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

أجهزة XR المشمولة

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

مزيد من المعلومات حول أنواع أجهزة XR →

مزيد من المعلومات حول أنواع أجهزة 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 في تطبيقك:

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

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، يحتاج تطبيقك إلى طلب أذونات وقت التشغيل التالية:

• ACCESS_INTERNET: مطلوب للاتصال بخدمة السحابة الإلكترونية ARCore Geospatial API.
• ACCESS_COARSE_LOCATION: مطلوب لتحديد الموقع الجغرافي التقريبي للمستخدم.
• ACCESS_FINE_LOCATION: مطلوب لتحديد الموقع الجغرافي الدقيق للمستخدم.

الإعلان عن أذونات التطبيق

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

<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_KNOWNmodes:

// 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.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>.

التحقّق من توفّر نظام تحديد المواقع المرئية (VPS)

بما أنّ Geospatial API تستخدم مزيجًا من نظام تحديد المواقع المرئية (VPS) ونظام 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