با استفاده از ARCore برای Jetpack XR با ژست‌های مکانی کار کنید

دستگاه‌های XR قابل اجرا
این راهنما به شما کمک می‌کند تا برای این نوع دستگاه‌های XR تجربه ایجاد کنید.
درباره انواع دستگاه‌های XR اطلاعات کسب کنید →
عینک هوش مصنوعی
درباره انواع دستگاه‌های XR اطلاعات کسب کنید →

با استفاده از API مکانی در ARCore برای Jetpack XR، برنامه شما می‌تواند از راه دور محتوا را به هر منطقه‌ای که توسط Google Street View پوشش داده می‌شود، ضمیمه کند و تجربیات AR را در مقیاس جهانی ایجاد کند. API مکانی از حسگر دستگاه و داده‌های GPS برای تشخیص محیط دستگاه استفاده می‌کند، سپس بخش‌های قابل تشخیص آن محیط را با یک مدل محلی‌سازی ارائه شده توسط سیستم موقعیت‌یابی بصری (VPS) گوگل مطابقت می‌دهد تا مکان دقیق دستگاه کاربر را تعیین کند. این API همچنین مختصات محلی کاربر را با مختصات جغرافیایی VPS ادغام می‌کند تا بتوانید در یک سیستم مختصات واحد کار کنید.

فعال کردن API ARCore

قبل از استفاده از سیستم موقعیت‌یابی بصری (VPS) در برنامه خود، ابتدا باید API ARCore را در یک پروژه جدید یا موجود 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")
}

درخواست مجوزهای مورد نیاز

برای استفاده از 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>

درخواست مجوز

پس از اعلام مجوزهای مورد نیاز، برنامه شما باید در زمان اجرا آنها را درخواست کند . حتماً توضیح دهید که چرا برنامه شما به این مجوزها نیاز دارد .

API مربوط به موقعیت مکانی نمی‌تواند کار کند مگر اینکه بتواند موقعیت مکانی دقیق کاربر را تعیین کند. به همین دلیل، برای درخواست مجوزهای موقعیت مکانی در زمان اجرا، دستورالعمل‌های مربوط به آن را دنبال کنید تا برنامه شما بتواند مجوزهای ACCESS_FINE_LOCATION و ACCESS_COARSE_LOCATION را دریافت کند.

دسترسی به یک جلسه

از طریق یک Session زمان اجرای Jetpack XR که برنامه شما باید ایجاد کند ، به اطلاعات مکانی دسترسی پیدا کنید.

پیکربندی جلسه

اطلاعات موقعیت دستگاه به طور پیش‌فرض در جلسات 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() با موفقیت اجرا شود، دستگاه از این حالت‌ها پشتیبانی می‌کند.

از کاربر بخواهید اجازه استفاده از داده‌های دستگاه را بدهد

برنامه‌هایی که از API جغرافیایی با ARCore برای 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

از آنجا که API جغرافیایی از ترکیبی از VPS و GPS برای تعیین موقعیت جغرافیایی استفاده می‌کند، هر زمان که دستگاه بتواند موقعیت مکانی خود را تعیین کند، در دسترس است. در مناطقی با دقت پایین GPS، مانند فضاهای داخلی و محیط‌های شهری متراکم، API برای تولید موقعیت‌های با دقت بالا به پوشش VPS متکی است.

در شرایط معمول، می‌توانید انتظار داشته باشید که VPS دقت موقعیتی تقریباً ۵ متر و دقت چرخشی ۵ درجه را ارائه دهد. می‌توانید با استفاده از تابع تعلیق Geospatial.checkVpsAvailability(latitude, longitude) بررسی کنید که آیا یک مکان پوشش VPS دارد یا خیر. این فراخوانی یک عملیات ناهمزمان است و نیازی به پیکربندی جلسه با حالت 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

برنامه شما باید به درستی تنظیم شده باشد تا با API ARCore در Google Cloud ارتباط برقرار کند ؛ در غیر این صورت، برنامه شما نتیجه VpsAvailabilityNotAuthorized دریافت می‌کند.

تبدیل حالت دستگاه به حالت مکانی

شما می‌توانید حالت دستگاه را به حالت جغرافیایی تبدیل کنید تا عینک‌های هوش مصنوعی بتوانند با آن تعامل داشته باشند و داده‌های آگاه از مکان تولید کنند. این خط لوله، موقعیت و جهت فعلی دستگاه را در سیستم مختصات محلی آن (حالت دستگاه) به مختصات شناخته شده جهانی تبدیل می‌کند.

این می‌تواند به شما کمک کند:

  • محتوای AR پایدار را ایجاد کنید، که در آن شیء مجازی قرار داده شده توسط کاربر به طور دقیق در یک مکان جهانی برای بازیابی بعدی لنگر انداخته می‌شود.
  • با به‌روزرسانی مداوم موقعیت کاربر روی نقشه، تجربیات مبتنی بر مکان را فعال کنید تا ناوبری در لحظه یا گیم‌پلی با محدودیت جغرافیایی امکان‌پذیر شود.
  • زمینه دقیق دنیای واقعی کاربر را برای راه‌اندازی منطق برنامه مرتبط با مکان تعیین کنید.

برای تبدیل حالت دستگاه به حالت مکانی با استفاده از 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

تبدیل موقعیت مکانی به موقعیت دستگاه

شما می‌توانید یک ژست مکانی را به یک ژست دستگاه تبدیل کنید تا به ارائه تجربیات مبتنی بر موقعیت مکانی و مبتنی بر موقعیت مکانی در عینک‌های هوش مصنوعی کمک کنید. این تبدیل، اطلاعات تعریف‌شده توسط مختصات دنیای واقعی - مانند موقعیت یک نقطه عطف، یک مسیر ناوبری یا محتوای AR پایدار - را دریافت کرده و آن را به فضای بصری دقیق عینک کاربر تبدیل می‌کند.

برای تبدیل یک موقعیت مکانی به موقعیت دستگاه با استفاده از 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