Как настроить Geospatial API в приложении

Поддерживаемые XR-устройства

Это руководство поможет вам создавать продукты для таких XR-устройств.

Подробнее о типах устройств XR…

Подробнее о типах устройств XR…

Чтобы использовать Geospatial API в приложении, необходимо настроить доступ к ARCore API в Google Cloud. Этот API содержит сервис визуального позиционирования, который обеспечивает точное позиционирование с использованием данных Google Просмотра улиц.

В этом руководстве рассказывается, как настроить проект Google Cloud, в котором включены нужные API и методы авторизации для доступа к API.

Как настроить проект Google Cloud или использовать существующий

Если у вас есть существующий облачный проект Google Cloud, выберите его.

Перейти на страницу выбора проекта

Если у вас нет проекта, создайте его.

Создать проект

Включите ARCore API

Чтобы использовать ARCore API, его нужно включить в проекте.

Как включить ARCore API

Как настроить авторизацию для Google Cloud

Приложение Android может взаимодействовать с ARCore API, используя два разных метода авторизации: авторизацию без ключа (OAuth 2.0), которая является рекомендуемым методом, и авторизацию с помощью ключа API:

• При авторизации без ключа используется комбинация названия пакета приложения и цифрового отпечатка ключа подписи.

• Ключ API – это строка, которая идентифицирует проект Google Cloud. Ключи API обычно не считаются безопасными, поскольку они, как правило, доступны клиентам. Для взаимодействия с ARCore API рекомендуется использовать авторизацию без ключа.

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

Запросите необходимые разрешения

Чтобы использовать Geospatial API в ARCore с Jetpack XR, вашему приложению необходимо запросить следующие динамические разрешения:

• ACCESS_FINE_LOCATION – требуется для определения точного местоположения пользователя.

На мобильных устройствах Geospatial API также требует следующих разрешений:

• android.permission.CAMERA – требуется для доступа к камере устройства.
• android.permission.INTERNET – требуется для связи с сервисами Google Cloud.

Как получить доступ к сеансу

Доступ к геопространственной информации через среду выполнения Jetpack XR Session, которую должно создать ваше приложение.

Настройте сеанс

Geospatial API по умолчанию отключен в сеансах XR. Чтобы включить его, необходимо настроить GeospatialMode в Session. Доступны следующие режимы:

• GeospatialMode.SPATIAL: Geospatial API включен. Geospatial API использует данные системы визуального позиционирования (VPS), глобальной системы позиционирования (GPS) и датчиков движения устройства, чтобы определить его геопространственное положение. Этот режим недоступен на умных очках.
• GeospatialMode.INERTIAL – Geospatial API включен в режиме низкого энергопотребления. Geospatial API использует только GPS и датчики движения устройства, чтобы определить его пространственное положение. Этот режим доступен только на умных очках.
• GeospatialMode.DISABLED – Geospatial API отключен. При переходе в этот режим из другого Geospatial API освобождает все полученные ресурсы и прекращает отслеживание.

Не все устройства поддерживают все геопространственные режимы. Подробнее о GeospatialMode… Используйте XrDevice.isGeospatialSupported, чтобы узнать, поддерживается ли определенный GeospatialMode.

В примере кода ниже показано, как задать GeospatialMode с помощью Session.configure.

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// 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.
}
Setup.kt

Запрашивать у пользователя разрешение на использование данных устройства

Приложения, использующие Geospatial API с ARCore для Jetpack XR, должны запрашивать у пользователя разрешение на использование данных с его устройства. Подробнее о требованиях к конфиденциальности пользователей…

Как использовать объект Geospatial

После настройки сеанса получите объект Geospatial с помощью Geospatial.getInstance. Используйте объект Geospatial, только когда он находится в состоянии GeospatialTrackingState.RUNNING.

В примерах кода ниже показано, как отслеживать состояние Geospatial API с помощью Geospatial.state.

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

Как интерпретировать значения точности

Когда Geospatial API включен, он предоставляет три значения точности: горизонтальную, вертикальную и точность ориентации. Эти значения точности обновляются со временем и могут быть уточнены по мере получения дополнительных данных. Чем больше значение, тем ниже точность. Значение определяется как радиус с уровнем достоверности 68 %. Другими словами, с вероятностью 68% фактическое значение находится в пределах указанного радиуса от расчетного.

Используйте Geospatial.State.horizontalAccuracy, verticalAccuracy и orientationYawAccuracy, чтобы получить текущие значения точности.

Для правильной работы приложения может требоваться определенный уровень точности. Например, ваше приложение может подождать, пока горизонтальная точность не станет меньше 5 метров, прежде чем отображать виртуальный контент. Чтобы повысить вероятность получения более точных данных, ваше приложение должно предлагать пользователям осмотреться вокруг, желательно на здания или другие объекты с высокой детализацией, которые присутствуют в Google Просмотре улиц. Используйте Geospatial.checkVpsAvailability, чтобы определить, доступна ли VPS в заданном местоположении.

Что дальше

Если Geospatial API настроен правильно, ваше приложение сможет:

• Преобразование между локальными и геопространственными позами
• Как отрисовывать контент в геопространственных позах