Работа с геопространственными позами с использованием ARCore для Jetpack XR

Применимые устройства XR
Данное руководство поможет вам создавать приложения для устройств XR такого типа.
Узнайте о типах устройств XR →
Очки с искусственным интеллектом
Узнайте о типах устройств XR →

Благодаря геопространственному API в ARCore для Jetpack XR ваше приложение может удаленно прикреплять контент к любой области, охватываемой Google Street View , и создавать AR-приложения в глобальном масштабе. Геопространственный API использует данные датчиков устройства и GPS для определения окружающей среды устройства, а затем сопоставляет распознаваемые части этой среды с моделью локализации, предоставляемой системой визуального позиционирования Google (VPS), чтобы определить точное местоположение устройства пользователя. API также обеспечивает объединение локальных координат пользователя с географическими координатами из VPS, что позволяет работать в единой системе координат.

Включите API ARCore

Прежде чем использовать систему визуального позиционирования (VPS) в своем приложении, необходимо сначала включить API ARCore в новом или существующем проекте Google Cloud. Этот сервис отвечает за размещение, хранение и разрешение геопространственных привязок.

Добавьте дополнительные зависимости библиотеки.

Для использования геопространственного 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 , которую должно создать ваше приложение .

Настройте сессию

Информация о положении устройства по умолчанию отключена в сессиях 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 обеспечит точность позиционирования примерно в 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

Ваше приложение должно быть правильно настроено для взаимодействия с API ARCore в 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