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

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

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

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

В целевой области нужно собрать данные для построения карты, построить Mega Block, добавить реконструированный Mega Block в библиотеку позиционирования и убедиться, что библиотека позиционирования доступна.

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

Определение состояния позиционирования

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

  

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

  

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

Constant	Value	Description
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

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

Ошибка	Способ решения
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 корпоративного пакета с license key не корпоративной версии либо используется SDK не корпоративного пакета с license key корпоративного пакета
Invalid Key: License for an old version does not apply	Версия license слишком старая, нужно заново создать новую license
Invalid Key: Invalid format	Неверный формат license, например скопирована не полностью
Invalid Key: Server verification failed	License удалена или нет разрешения на использование устройства; если используется шлем/очки, обратитесь в коммерческий отдел для добавления разрешения
License does not apply to eyewear	License нельзя использовать на шлемах/очках, замените ее на xr license
License is expired	License истекла

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

Аномалии изображения камеры

При разработке или тестировании приложения 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 и т. д.

Не на месте, постоянный NotFound

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

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

Вызвано факторами среды

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

Направление на белую стену или пол, постоянный NotFound

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

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

Способ решения: это нормальное явление; нужно переместить камеру к области с богатой текстурой для запуска.

На месте и текстура богатая, но постоянный NotFound

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

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

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

Способ решения:

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

Вызвано самим сервисом

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, версия плагина >= 4003
• Разработка Unity, версия плагина 4.7 - 4002
• Разработка мини-программы
• Другие сценарии использования Mega Studio

В инструменте редактора используемого вами block-узла нажмите кнопку Diagnosis Info, показанную на рисунке ниже, чтобы экспортировать диагностическую информацию Mega Block. Диагностическая информация Mega Block содержит только сведения о Mega Block и библиотеке позиционирования и не содержит другой чувствительной информации.

Формат экспортированного файла должен быть Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Запись EIF-файла

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

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

Если проблема возникла в вашем собственном приложении, можно использовать ваше приложение для записи EIF-файла

При использовании WeChat mini program можно использовать запись EIF-файла mini program

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

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

Примечание

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

Обратная связь по проблемам разработки Unity

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

1. Уже пробовали последнюю версию EasyAR Sense Unity Plugin; новые версии обычно содержат исправления bug и новые функции, поэтому рекомендуется сначала попробовать обновиться до последней версии
2. Уже прочитали документацию разработчика EasyAR и руководство Mega; документация обычно содержит пояснения по некоторым ситуациям
3. Уже изучили системные и Unity-логи; при вопросе рекомендуется предоставить полный лог
4. Уже пробовали воспроизвести проблему в пустом Unity-проекте в Sample

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

1. В Unity -> EasyAR -> Sense выберите Question

   

2. В Question нужно предоставить следующую информацию

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

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