Руководство разработчика Cloud Anchors для Android (Kotlin/Java)

Узнайте, как использовать облачные привязки в своих приложениях.

Предварительные условия

Прежде чем продолжить, убедитесь, что вы понимаете фундаментальные концепции AR и то, как настроить сеанс ARCore .

Если вы новичок в Cloud Anchors:

Включите API ARCore

Прежде чем использовать облачные привязки в своем приложении, необходимо сначала включить API ARCore в своем приложении.

Включите возможности Cloud Anchor в конфигурации сеанса.

После включения функции Cloud Anchors в вашем приложении включите возможности Cloud Anchors в конфигурации сеанса AR вашего приложения, чтобы оно могло взаимодействовать с API ARCore:

Ява 

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

Котлин 

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Разместите облачный якорь

Хостинг начинается с вызова hostCloudAnchorAsync() . ARCore загрузит визуальные данные, позы устройства и позу привязки в API ARCore. Затем API обрабатывает эту информацию для создания трехмерной карты объектов, в конечном итоге возвращая уникальный идентификатор облачной привязки для привязки к устройству.

Вы также можете продлить срок службы размещенной привязки с помощью API ARCore Cloud Anchor Management .

Чтобы завершить размещение Cloud Anchor, вашему приложению необходимо выполнить следующие действия:

  1. Вызовите hostCloudAnchorAsync() .
  2. Дождитесь обратного вызова или постоянно проверяйте состояние Future, пока оно не будет выполнено.
  3. Проверьте состояние результата, чтобы определить, завершилась ли операция успешно, или интерпретируйте код ошибки, если она не удалась.
  4. Поделитесь полученным идентификатором Cloud Anchor с другими клиентами и используйте его для разрешения Cloud Anchor с resolveCloudAnchorAsync() .

Проверьте качество отображения характерных точек.

Session.FeatureMapQuality указывает качество характерных точек, видимых ARCore за предыдущие несколько секунд в заданной позе камеры. Облачные привязки, размещенные с использованием функций более высокого качества, обычно решаются более точно. Используйте Session.estimateFeatureMapQualityForHosting() чтобы получить оценку качества карты объектов для заданной позы камеры.

Ценить Описание
INSUFFICIENT Качество характерных точек, определенных по позе в предыдущие несколько секунд, низкое. Это состояние указывает на то, что ARCore, скорее всего, столкнется с большими трудностями при разрешении облачной привязки. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами.
SUFFICIENT Качество характерных точек, определенных по позе за предыдущие несколько секунд, вероятно, будет достаточным для ARCore для успешного определения облачной привязки, хотя точность решенной позы, вероятно, будет снижена. Поощряйте пользователя перемещать устройство так, чтобы желаемое положение Cloud Anchor, которое он хочет разместить, можно было просматривать под разными углами.
GOOD Качество характерных точек, определенных по позе за предыдущие несколько секунд, вероятно, достаточно для того, чтобы ARCore успешно определил привязку к облаку с высокой степенью точности.

Разрешить ранее размещенную привязку

resolveCloudAnchorAsync() , чтобы разрешить размещенную облачную привязку. API ARCore периодически сравнивает визуальные особенности сцены с трехмерной картой объектов привязки, чтобы точно определить положение и ориентацию пользователя относительно привязки. Когда API находит совпадение, он возвращает положение размещенного Cloud Anchor.

Вы можете последовательно инициировать решения для нескольких облачных якорей. Одновременно может выполняться до 40 одновременных операций Cloud Anchor.

Отменить операцию или удалить облачную привязку

Вызовите cancel() , чтобы отменить ожидающую операцию Cloud Anchor. Вызовите detach() чтобы удалить из приложения уже решенную облачную привязку.

Проверка состояния результата операции Cloud Anchor

Используйте Anchor.CloudAnchorState, чтобы проверить состояние результата операции размещения или разрешения, включая ошибки.

Ценить Описание
ERROR_CLOUD_ID_NOT_FOUND Разрешение не удалось, поскольку API ARCore не смог найти предоставленный идентификатор привязки к облаку.
ERROR_HOSTING_DATASET_PROCESSING_FAILED Не удалось разместить хостинг, поскольку серверу не удалось успешно обработать набор данных для данной привязки. Повторите попытку после того, как устройство соберет больше данных из окружающей среды.
ERROR_HOSTING_SERVICE_UNAVAILABLE API ARCore был недоступен. Это может произойти по ряду причин. Устройство может находиться в режиме полета или не иметь работающего подключения к Интернету. Возможно, истекло время ожидания запроса, отправленного на сервер, и нет ответа. Возможно плохое сетевое соединение, недоступность DNS, проблемы с брандмауэром или что-то еще, что может повлиять на способность устройства подключаться к API ARCore.
ERROR_INTERNAL Задача размещения или решения для этой привязки завершилась с внутренней ошибкой. Приложение не должно пытаться устранить эту ошибку.
ERROR_NOT_AUTHORIZED Авторизация, предоставленная приложением, недействительна. См. раздел «Устранение проблем с авторизацией ARCore API» .
ERROR_RESOLVING_SDK_VERSION_TOO_NEW Облачную привязку не удалось разрешить, поскольку версия SDK, используемая для разрешения привязки, новее и несовместима с версией, используемой для ее размещения.
ERROR_RESOLVING_SDK_VERSION_TOO_OLD Облачную привязку не удалось разрешить, поскольку версия SDK, используемая для разрешения привязки, старше и несовместима с версией, используемой для ее размещения.
ERROR_RESOURCE_EXHAUSTED Приложение исчерпало квоту запросов, выделенную для данного проекта Google Cloud. Вам следует запросить дополнительную квоту для API ARCore для вашего проекта в консоли разработчиков Google.
SUCCESS Задача размещения или разрешения для этой привязки успешно завершена.

Квоты API для запросов хоста и разрешения

API ARCore имеет следующие квоты на пропускную способность запросов:

Тип квоты Максимум Продолжительность Применяется к
Количество анкеров неограниченный Н/Д проект
Привязка запросов хоста 30 минута IP-адрес и проект
Привязка запросов на разрешение 300 минута IP-адрес и проект

Рекомендации по улучшению пользовательского опыта

Попросите пользователей сделать следующее, чтобы обеспечить удобство использования вашего приложения:

  • Подождите несколько секунд после начала сеанса, прежде чем пытаться разместить привязку (путем размещения объекта и т. д.). Это дает отслеживанию некоторое время для стабилизации.
  • Выбирая место для размещения якоря, постарайтесь найти область с визуальными особенностями, которые легко отличить друг от друга. Для достижения наилучших результатов избегайте отражающих поверхностей или поверхностей, лишенных визуальных особенностей, таких как пустые белые стены.

  • Держите камеру направленной на центр интереса и перемещайте устройство вокруг него, чтобы составить карту окружающей среды под разными углами, сохраняя при этом примерно то же физическое расстояние. Это поможет собрать больше визуальных данных и сделать решение более надежным.

  • При размещении и разрешении облачных привязок убедитесь, что в реальной среде достаточно освещения.

Политика прекращения поддержки

  • На приложения, созданные с помощью ARCore SDK 1.12.0 или более поздней версии, распространяется политика прекращения поддержки API Cloud Anchor .
  • Приложения, созданные с помощью ARCore SDK 1.11.0 или более ранней версии, не могут размещать или разрешать облачные привязки из-за использования SDK более старого, устаревшего API ARCore.

Что дальше