Узнайте, как использовать облачные привязки в своих приложениях.
Предварительные условия
Прежде чем продолжить, убедитесь, что вы понимаете фундаментальные концепции AR и то, как настроить сеанс ARCore .
Если вы новичок в облачных привязках, убедитесь, что вы понимаете, как работают привязки и облачные привязки .
Включите API ARCore
Прежде чем использовать Cloud Anchors в своем приложении, вы должны сначала включить API ARCore в своем приложении.
Включите возможности Cloud Anchor в конфигурации сеанса.
После включения функции Cloud Anchors в вашем приложении включите возможности Cloud Anchors в конфигурации сеанса AR вашего приложения, чтобы оно могло взаимодействовать с API ARCore:
// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);
// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);
// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
AR_CLOUD_ANCHOR_MODE_ENABLED);
// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);Разместите облачный якорь
Хостинг начинается с вызова ArSession_hostCloudAnchorAsync() . ARCore загрузит визуальные данные, позы устройства и позу привязки в API ARCore. Затем API обрабатывает эту информацию для создания трехмерной карты объектов, в конечном итоге возвращая уникальный идентификатор облачной привязки для привязки к устройству.
Вы также можете продлить срок службы размещенной привязки с помощью API ARCore Cloud Anchor Management .
Для завершения размещения Cloud Anchor вашему приложению необходимо выполнить следующие действия:
- Вызовите
ArSession_hostCloudAnchorAsync(). - Дождитесь обратного вызова или постоянно проверяйте состояние Future, пока оно не будет выполнено.
- Проверьте состояние результата , чтобы определить, завершилась ли операция успешно, или интерпретируйте код ошибки, если она не удалась.
- Поделитесь полученным идентификатором Cloud Anchor с другими клиентами и используйте его для разрешения Cloud Anchor с помощью
ArSession_resolveCloudAnchorAsync().
Проверьте качество отображения характерных точек.
ArFeatureMapQuality указывает качество характерных точек, видимых ARCore за предыдущие несколько секунд в заданной позе камеры. Облачные привязки, размещенные с использованием функций более высокого качества, обычно решаются более точно. Используйте ArSession_estimateFeatureMapQualityForHosting() чтобы получить оценку качества карты объектов для заданной позы камеры.
| Ценить | Описание |
|---|---|
INSUFFICIENT | Качество характерных точек, определенных по позе в предыдущие несколько секунд, низкое. Это состояние указывает на то, что ARCore, скорее всего, столкнется с большими трудностями при разрешении облачной привязки. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами. |
SUFFICIENT | Качество характерных точек, определенных по позе за предыдущие несколько секунд, вероятно, будет достаточным для ARCore для успешного определения облачной привязки, хотя точность решенной позы, вероятно, будет снижена. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами. |
GOOD | Качество характерных точек, определенных по позе за предыдущие несколько секунд, вероятно, достаточно для того, чтобы ARCore успешно определил привязку к облаку с высокой степенью точности. |
Разрешить ранее размещенную привязку
Вызовите ArSession_resolveCloudAnchorAsync() чтобы разрешить размещенную облачную привязку. API ARCore периодически сравнивает визуальные особенности сцены с трехмерной картой объектов привязки, чтобы точно определить положение и ориентацию пользователя относительно привязки. Найдя совпадение, API возвращает положение размещенного Cloud Anchor.
Вы можете последовательно инициировать решения для нескольких облачных якорей. Одновременно может выполняться до 40 одновременных операций Cloud Anchor.
Отменить операцию или удалить облачную привязку
Вызовите ArFuture_cancel() чтобы отменить ожидающую операцию Cloud Anchor. Вызовите ArAnchor_detach() чтобы прекратить отслеживание и забыть об уже разрешенной облачной привязке. Ссылки на якорь необходимо освободить отдельно, вызвав ArAnchor_release() .
Проверка состояния результата операции Cloud Anchor
Используйте ArCloudAnchorState , чтобы проверить статус результата операции размещения или разрешения, включая ошибки.
| Ценить | Описание |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND | Разрешение не удалось, поскольку API ARCore не смог найти предоставленный идентификатор привязки к облаку. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED | Не удалось разместить хостинг, поскольку серверу не удалось успешно обработать набор данных для данной привязки. Повторите попытку после того, как устройство соберет больше данных из окружающей среды. |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE | API ARCore был недоступен. Это может произойти по ряду причин. Устройство может находиться в режиме полета или не иметь работающего подключения к Интернету. Возможно, истекло время ожидания запроса, отправленного на сервер, и нет ответа. Возможно плохое сетевое соединение, недоступность DNS, проблемы с брандмауэром или что-то еще, что может повлиять на способность устройства подключаться к API ARCore. |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL | Задача размещения или решения для этой привязки завершилась с внутренней ошибкой. Приложение не должно пытаться устранить эту ошибку. |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED | См. раздел «Устранение проблем с авторизацией ARCore API» . |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW | Облачную привязку не удалось разрешить, поскольку версия SDK, используемая для разрешения привязки, новее и несовместима с версией, используемой для ее размещения. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD | Облачную привязку не удалось разрешить, поскольку версия SDK, используемая для разрешения привязки, старше и несовместима с версией, используемой для ее размещения. |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED | Приложение исчерпало квоту запросов, выделенную для данного проекта Google Cloud. Вам следует запросить дополнительную квоту для API ARCore для вашего проекта в консоли разработчиков Google. |
AR_CLOUD_ANCHOR_STATE_SUCCESS | Задача размещения или разрешения для этой привязки успешно завершена. |
Квоты API для запросов хоста и разрешения
API ARCore имеет следующие квоты на пропускную способность запросов:
| Тип квоты | Максимум | Продолжительность | Применяется к |
|---|---|---|---|
| Количество анкеров | неограниченный | Н/Д | проект |
| Привязка запросов хоста | 30 | минута | IP-адрес и проект |
| Привязка запросов на разрешение | 300 | минута | IP-адрес и проект |
Рекомендации по улучшению пользовательского опыта
Попросите пользователей сделать следующее, чтобы обеспечить удобство использования вашего приложения:
- Подождите несколько секунд после начала сеанса, прежде чем пытаться разместить привязку (путем размещения объекта и т. д.). Это дает отслеживанию некоторое время для стабилизации.
- Выбирая место для размещения якоря, постарайтесь найти область с визуальными особенностями, которые легко отличить друг от друга. Для достижения наилучших результатов избегайте отражающих поверхностей или поверхностей, лишенных визуальных особенностей, таких как пустые белые стены.
Держите камеру направленной на центр интереса и перемещайте устройство вокруг него, чтобы составить карту окружающей среды под разными углами, сохраняя при этом примерно то же физическое расстояние. Это поможет собрать больше визуальных данных и сделать решение более надежным.
При размещении и разрешении облачных привязок убедитесь, что в реальной среде достаточно освещения.
Политика прекращения поддержки
- На приложения, созданные с помощью ARCore SDK 1.12.0 или более поздней версии, распространяется политика прекращения поддержки API Cloud Anchor .
- Приложения, созданные с помощью ARCore SDK 1.11.0 или более ранней версии, не могут размещать или разрешать облачные привязки из-за использования SDK более старого, устаревшего API ARCore.
Что дальше
- Ознакомьтесь со справочной документацией Android NDK, чтобы узнать больше о способах использования ARCore в вашем приложении.