Руководство по устранению сбоев позиционирования Mega

Mega использует передовые алгоритмы визуального позиционирования, обеспечивая высокую точность за счет облачного поиска Mega Block, сопоставления визуальных признаков и вычислений. Однако на практике сбои позиционирования могут возникать по разным причинам: ошибки конфигурации, изменения среды, колебания сети и т.д.

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

Процесс локализации

Требуется сбор данных для построения карты в целевой зоне, построение Мега-блока, добавление уже реконструированного Мега-блока в библиотеку локализации и подтверждение пригодности библиотеки локализации.

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

Определение статуса локализации

• Если вы используете Mega Toolbox для проверки результатов локализации, можете напрямую просмотреть статус локализации

  

• Если вы разработчик на Unity и столкнулись с невозможностью локализации, вы можете просмотреть конкретную информацию о возврате локализации MegaTrackerLocalizationStatus на экране. Если этой информации нет на экране, необходимо включить диагностическую информацию.

  

Возможные значения MegaTrackerLocalizationStatus

Константа	Значение	Описание
UnknownError	0	Неизвестная ошибка
Found	1	Локализован Block
NotFound	2	Block не найден
RequestTimeout	3	Таймаут запроса (превышение 1 минуты)
RequestIntervalTooLow	4	Слишком короткий интервал запросов
QpsLimitExceeded	5	Превышено ограничение QPS
WakingUp	6	Сервис находится в процессе пробуждения
MissingSpotVersionId	7	Отсутствует SpotVersionId (возможно, не задан)
ApiTokenExpired	8	Срок действия API Token истек

Решение при возникновении указанных исключений:

• Таймаут запроса: Проверить и исправить состояние сети. При необходимости можно увеличить время ожидания запроса MegaRequestTimeParameters.Timeout, однако плохая сеть также влияет на эффективность трекинга, поэтому проблемы с сетью необходимо решать.
• Слишком короткий интервал запросов: Увеличить интервал между запросами.
• Ошибка соединения или передачи: Проверить и исправить состояние сети.
• Превышено ограничение QPS: Связаться с коммерческим представителем EasyAR для расширения QPS.
• Сервис находится в процессе пробуждения: Система пробуждается, подождите некоторое время и повторите попытку.
• Отсутствует SpotVersionId: Настройте SpotVersionId.
• Срок действия API Token истек: Сгенерируйте новый API Token в панели управления EasyAR.

Для UnknownError обычно характерны две ситуации:

• Ошибка соединения или передачи данных.
• Сервис вернул исключение.

Для UnknownError подробную информацию можно получить через MegaLocalizationResponse.ErrorMessage.

Распространенные ошибки классификация

В зависимости от возвращенного состояния и явления локализации, распространенные проблемы можно разделить на следующие три категории: проблемы конфигурации, факторы среды, сам сервис.

Проблемы с конфигурацией

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

Лицензия и связанные вопросы

Если в процессе разработки или тестирования в журналах или на экране появляются сообщения о проблемах с License, Invalid Key и т.п., возможные причины: несоответствие AppID/BundleID, истекший срок действия лицензии, несоответствующий тарифный план и др. Пожалуйста, сверьтесь с приведенной ниже таблицей для проверки настроек вашей лицензии.

Ошибка	Решение
Invalid Key: No matched Bundle ID	Bundle ID не соответствует ключу лицензии (license key). Измените один из них, чтобы они совпадали.
Invalid Key: No matched Package Name	Bundle ID не соответствует ключу лицензии (license key). Измените один из них, чтобы они совпадали.
Invalid Key: License does not apply to current variant	Используется SDK для корпоративного пакета (Enterprise) с не корпоративной лицензией, или наоборот.
Invalid Key: License for an old version does not apply	Версия лицензии устарела. Создайте новую лицензию.
Invalid Key: Invalid format	Ошибка формата лицензии, например, ключ скопирован не полностью.
Invalid Key: Server verification failed	Лицензия удалена или не имеет прав на использование устройства. Если используется гарнитура (eyewear), свяжитесь с отделом продаж для добавления прав.
License does not apply to eyewear	Лицензия не может использоваться на гарнитурах (eyewear). Замените на xr-лицензию.
License is expired	Срок действия лицензии истек.

Кроме того, обратите внимание, что пробные версии лицензий имеют некоторые ограничения. Использование платных версий EasyAR Sense и платного сервиса EasyAR Mega решает эту проблему. Если вы уже используете платную версию EasyAR Sense, вы можете проигнорировать это сообщение или просто удалить соответствующий текст из примера.

Камера画面异常

При разработке или тестировании приложений EasyAR Mega, если возникают такие проблемы, как черный экран, сбои, отсутствие изображения с камеры и другие аномалии, выполните следующие шаги для системного поиска и сбора информации.

1. Попробуйте самостоятельно решить

• Если вы разрабатываете или тестируете в Unity, убедитесь, что в AR Session (EasyAR) -> Inspector отмечен Diagnostics Controller (Script) для включения диагностической информации.

  

• Просмотрите содержимое экрана или журналов, проверьте, есть ли на UI явные текстовые подсказки.

• В большинстве случаев сообщения об ошибках являются самообъясняющими. Если информация на экране или в журнале уже указывает на причину ошибки, вы можете решить проблему, исходя из конкретной причины. Например: cameraDevice.openWithPreferredType fail (необходимо проверить доступность камеры).

• Если появляется сообщение "не поддерживается" (например, устройство не поддерживает ARCore или другую функцию), это является нормальным ограничением, и дальнейшее устранение не требуется.

2. Не удается решить самостоятельно

   Сначала попытайтесь решить проблему самостоятельно, используя имеющуюся информацию. Если это не удается, чтобы помочь сотрудникам EasyAR быстро определить проблему, обязательно предоставьте подробную, воспроизводимую техническую информацию. Не ограничивайтесь описанием явления, такого как "черный экран". Рекомендуется включить в отчет:

• Полные журналы: Unity или Sense.
• Скриншоты или запись экрана: полный экран в момент черного экрана; если есть диагностическая информация, убедитесь, что она видна и сделайте скриншот.
• Подробную информацию об устройстве: модель устройства (например, iPhone 15, HUAWEI P40), версия ОС (например, iOS 17.1, Android 14), версия EasyAR Sense, версия EasyAR Sense Unity Plugin, версия Unity и т.д.

Не на месте, постоянное отсутствие

Разработчики тестируют с помощью симулятора или записи экрана в офисе, но не могут определить проблему. Возможная причина — режим MegaLocationInputMode установлен в Onsite, но приложение запущено не на месте. В процессе разработки необходимо выбирать правильный режим в зависимости от режима ввода местоположения Mega:

Константа	Значение	Описание
Onsite	0	Режим ввода для использования на месте. Данные о местоположении обычно получаются с устройства и передаются в Mega, обычно обрабатываются внутри FrameFilter
Simulator	1	Режим ввода для удаленного использования. Данные о местоположении необходимо симулировать под данные с места и передавать в Mega через соответствующий интерфейс (опционально)
FramePlayer	2	Режим ввода при использовании FramePlayer. Этот режим доступен только для чтения

Факторы окружающей среды

Такие проблемы характеризуются тем, что сервис работает нормально, но определение местоположения постоянно возвращает NotFound.

Постоянное обнаружение NotFound на белой стене или полу

Когда в кадре камеры присутствует большая площадь белой стены, стекла или однотонного пола, состояние будет постоянно возвращать NotFound.

Причина: Визуальная локализация зависит от текстурных особенностей. В областях со слабой текстурой невозможно извлечь характерные точки.

Решение: Это нормальное явление. Необходимо переместить камеру в область с богатой текстурой для запуска.

На месте и текстурированная область, но постоянное NotFound

Пользователь находится на месте, направлен на текстурированную область, но долгое время не может успешно локализоваться.

Возможные причины:

• Изменение сцены: текущая среда на месте (например, ремонт, замена плакатов, резкое изменение освещения) слишком сильно отличается от сцены во время картографирования.
• Неполное покрытие при сборе данных: позиция пользователя выходит за пределы зоны покрытия, охваченной при первоначальном сборе данных для картографирования.

Решение:

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

По вине самого сервиса

Только что добавлен блок, статус WakingUp сохраняется

После завершения настройки библиотеки позиционирования или сразу после её запуска, статус службы отображает WakingUp или длительное время NotFound. Поскольку сервис Mega имеет механизм холодного запуска, для первой загрузки требуется пробуждение из холодного хранилища. Сохраняйте стабильное интернет-соединение, подождите 10–30 секунд и повторите попытку.

Возвращена ошибка сервиса

Https status	Status code	Причина
200	21	Превышение лимита QPS
200	1040 x	Некорректные параметры, библиотека или данные карты. См. конкретное сообщение.
200	4000 x	Ошибка на уровне алгоритма. См. конкретное описание.
401	-	Ошибка аутентификации. См. конкретное сообщение.
404	-	Некорректный путь в URL.
50x	-	Ошибка серверного приложения.

Решение при возникновении ошибок сервиса:

• При превышении лимита QPS: свяжитесь с коммерческим представителем EasyAR для расширения QPS.
• При ошибке аутентификации: устраните проблему согласно описанию в сообщении. Распространенные причины: значительное отклонение времени устройства от стандартного, отсутствие прав CLS у API Key и т.д.
• В остальных случаях: сообщите об ошибке сотруднику EasyAR для решения.

Обратная связь

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

Экспорт информации Mega службы определения местоположения

Войдите в свою учетную запись в Unity Mega Studio, выберите библиотеку локализации с аномалиями и найдите кнопку Экспорт Mega службы определения местоположения, как показано на изображении ниже. Экспортируемый файл должен иметь формат MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. Mega служба определения местоположения содержит только информацию о Mega-блоках и библиотеках локализации, без иных конфиденциальных данных.

Запись файлов EIF

При возникновении проблем при тестировании на телефоне, используйте Toolbox для записи файла EIF с телефона

При возникновении проблем при тестировании на очках, используйте Toolbox для записи файла EIF с очков

Если вы столкнулись с проблемой в своем собственном приложении, вы можете записать файл EIF с помощью вашего приложения

При использовании мини-программы WeChat можно записать файл EIF через мини-программу

Запись проблемы с помощью телефона, очков и других устройств

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

Примечание

Перед записью экрана рекомендуется, во время выполнения, обратиться к соответствующему Sample и отобразить на экране необходимую Debug-информацию. Наряду с предоставлением записи экрана, вы должны предоставить соответствующие данные EIF за период записи.

Проблемы разработки unity

Если вы столкнулись с необычными проблемами в процессе разработки на Unity, вам следует последовательно проверить, выполнены ли следующие 4 пункта.

1. Уже опробована последняя версия EasyAR Sense Unity Plugin. Новые версии обычно содержат исправления ошибок и новые функции, поэтому рекомендуется сначала обновиться до последней версии.
2. Уже изучена документация по разработке EasyAR и руководство по MEGA. В документации часто приводятся пояснения по различным ситуациям.
3. Уже изучены системные логи и логи Unity. При обращении рекомендуется предоставить полные логи.
4. Уже предпринята попытка воспроизвести проблему в пустом проекте Unity или в образце (Sample).

Если после выполнения этих 4 проверок проблема не решена, вы можете предоставить полную информацию через EasyAR Sense Unity Plugin, следуя описанной ниже процедуре, для анализа и решения проблемы специалистами EasyAR.

1. В Unity -> EasyAR -> Sense выберите Задать вопрос (Ask Question)

   

2. В разделе Задать вопрос необходимо предоставить следующую информацию:

   • Выберите среду выполнения, в которой возникла проблема. Поддерживается выбор только одной среды.
   • Скопируйте информацию об устройстве. В EasyAR Session установите DiagnosticsController.DumpSession в значение Log, скопируйте вывод одного кадра и вставьте результат ниже.
   • Выберите все функции EasyAR, которые вы использовали при возникновении проблемы (поддерживается множественный выбор).
   • Подтвердите, что выполнены все 4 проверки, описанные выше. При обращении рекомендуется описать, как воспроизвести проблему в образце (Sample).
   • Нажмите функцию копирования в правом верхнем углу. При первом открытии окна Задать вопрос информация внизу отображается не полностью. Она станет доступна после выбора используемой среды и функций.

3. Нажмите на ссылку Перейти к вопросам и ответам EasyAR внизу, чтобы отправить скопированную информацию официальной поддержке EasyAR, или напрямую передайте её сотрудникам EasyAR.