Guia de solução de falhas de localização do Mega

O Mega usa algoritmos avançados de localização visual e realiza localização de alta precisão por meio de recuperação de Mega Block na nuvem e cálculo por correspondência de características visuais. Por isso, durante o uso real, erros de configuração, mudanças no ambiente, oscilações de rede e outros fatores podem causar falhas de localização.

Este documento tem como objetivo ajudar você a identificar rapidamente o status da localização, distinguir "espera normal" de "erro anormal" e realizar diagnóstico rápido com base em três categorias de fatores: configuração, ambiente e serviço.

Fluxo de localização

Você precisa coletar dados de mapeamento na área de destino, construir o Mega Block, adicionar o Mega Block reconstruído à biblioteca de localização e confirmar que a biblioteca de localização está disponível.

Em uma área coberta por um Mega Block já construído, com boa iluminação, características visuais ricas e rede normal, a localização geralmente é bem-sucedida em poucos segundos. Após a localização bem-sucedida, serão retornadas a posição e a atitude atuais do dispositivo no Mega Block.

Determinar o status da localização

• Se você usar o Mega Toolbox para verificar o resultado da localização, poderá ver diretamente o status da localização

  

• Se você for desenvolvedor Unity e não conseguir localizar, poderá ver na tela as informações específicas retornadas pela localização, MegaTrackerLocalizationStatus. Se essa informação não aparecer na tela, ative as informações de diagnóstico.

  

Valores possíveis de MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Erro desconhecido
Found	1	Localizado no Block
NotFound	2	Block não localizado
RequestTimeout	3	Tempo limite da solicitação (mais de 1 minuto)
RequestIntervalTooLow	4	Intervalo entre solicitações curto demais
QpsLimitExceeded	5	QPS excedeu o limite
WakingUp	6	Serviço em processo de ativação
MissingSpotVersionId	7	SpotVersionId ausente, possivelmente não configurado
ApiTokenExpired	8	API Token expirado

Soluções para as exceções acima:

• Tempo limite da solicitação: verifique e corrija a rede. Se necessário, aumente o tempo limite da solicitação MegaRequestTimeParameters.Timeout; porém, uma rede ruim também afeta o efeito de rastreamento, portanto tente resolver o problema de rede.
• Intervalo entre solicitações curto demais: aumente o intervalo entre solicitações.
• Falha de conexão ou transmissão: verifique e corrija a rede.
• QPS excedeu o limite: entre em contato com a equipe comercial da EasyAR para expansão de QPS.
• Serviço em processo de ativação: o sistema está despertando; aguarde um tempo e tente novamente.
• SpotVersionId ausente: configure o SpotVersionId.
• API Token expirado: gere novamente o API Token no painel administrativo da EasyAR.

UnknownError costuma ter duas situações comuns

• Falha de conexão ou transmissão
• Exceção retornada pelo serviço

Para UnknownError, é possível obter informações detalhadas por meio de MegaLocalizationResponse.ErrorMessage

Solução de problemas por classificação de erros comuns

Com base no status e no fenômeno retornados pela localização, os problemas comuns podem ser divididos em três categorias: problemas de configuração, fatores ambientais e o próprio serviço.

Problemas de configuração

Esse tipo de problema geralmente ocorre durante a etapa de integração no desenvolvimento e se manifesta como impossibilidade total de iniciar o serviço.

Relacionados a License

Se, durante o desenvolvimento ou teste, o log ou a tela mostrar problemas como License ou Invalid Key, as possíveis causas incluem: AppID/BundleID incompatível, License expirada, plano incompatível etc. Verifique sua configuração de License conforme a tabela abaixo.

Erro	Solução
Invalid Key: No matched Bundle ID	O Bundle ID não corresponde à license key; modifique qualquer um deles para que correspondam
Invalid Key: No matched Package Name	O Bundle ID não corresponde à license key; modifique qualquer um deles para que correspondam
Invalid Key: License does not apply to current variant	Foi usado o SDK do pacote empresarial com uma license key não empresarial, ou foi usado o SDK não empresarial com uma license key de pacote empresarial
Invalid Key: License for an old version does not apply	A versão da license é antiga demais; crie uma nova license
Invalid Key: Invalid format	O formato da license está incorreto, por exemplo, cópia incompleta
Invalid Key: Server verification failed	A license foi excluída ou não tem permissão de uso no dispositivo; se for uso em headset, entre em contato com a equipe comercial para adicionar permissão
License does not apply to eyewear	A license não pode ser usada em headset; troque para uma xr license
License is expired	A license expirou

Além disso, observe que a License de versão de teste tem algumas limitações. Usar a versão paga do EasyAR Sense e o serviço pago do EasyAR Mega pode resolver esse problema. Se você já estiver usando a versão paga do EasyAR Sense, pode ignorar ou remover diretamente o texto relacionado do sample.

Imagem da câmera anormal

Durante o desenvolvimento ou teste de aplicativos EasyAR Mega, se ocorrerem problemas como tela preta, travamento ou ausência de imagem da câmera, siga as etapas abaixo para investigar sistematicamente e coletar informações.

1. Tentar resolver por conta própria

• Se você estiver desenvolvendo ou testando com Unity, certifique-se de que Diagnostics Controller (Script) esteja marcado em AR Session (EasyAR) -> Inspector para ativar as informações de diagnóstico.

  

• Verifique o conteúdo exibido na tela ou no log e veja se há uma mensagem textual clara na UI.

• Na maioria dos casos, as mensagens de erro são autoexplicativas. Se a mensagem na tela ou no log já explicar a causa, resolva de acordo com o motivo específico. Por exemplo: cameraDevice.openWithPreferredType fail (é necessário verificar se a câmera está disponível).

• Se a mensagem indicar "não suportado" (por exemplo, o dispositivo não suporta ARCore ou outro recurso), trata-se de uma limitação normal e não é necessário investigar mais.

2. Não consegue resolver por conta própria

   Primeiro tente resolver com base nas informações existentes. Se não conseguir, para ajudar a equipe da EasyAR a localizar rapidamente o problema, forneça informações técnicas detalhadas e reproduzíveis; não descreva apenas fenômenos como "tela preta". Recomenda-se incluir:

• Logs completos: Unity ou Sense
• Captura de tela ou gravação de tela: tela completa durante a tela preta; se houver informações de diagnóstico, garanta que elas estejam visíveis e capture-as.
• Informações detalhadas do dispositivo: modelo do dispositivo (por exemplo, iPhone 15, HUAWEi P40), versão do sistema (por exemplo, iOS 17.1, Android 14), versão do EasyAR Sense, versão do EasyAR Sense Unity Plugin, versão do Unity etc.

Execução fora do local com NotFound contínuo

O desenvolvedor testa no escritório usando simulador ou gravação de tela, mas nunca consegue localizar. Uma possível causa é que o modo MegaLocationInputMode está definido como Onsite, embora a execução não esteja ocorrendo no local. É necessário escolher o modo correto durante o desenvolvimento conforme o modo de entrada de localização do Mega:

Constant	Value	Description
Onsite	0	Modo de entrada para uso no local; os dados de posição geralmente são obtidos do dispositivo e inseridos no Mega, normalmente tratados internamente pelo FrameFilter
Simulator	1	Modo de entrada para uso remoto; os dados de posição precisam ser simulados como dados do local e inseridos no Mega por meio da interface correspondente (opcional)
FramePlayer	2	Modo de entrada ao usar FramePlayer. Esse modo é somente leitura

Causados por fatores ambientais

Esse tipo de problema se manifesta como serviço normal, mas localização retornando NotFound continuamente.

NotFound contínuo ao apontar para parede branca ou piso

Quando a imagem da câmera contém uma grande área de parede branca, vidro ou piso de cor uniforme, o status continuará retornando NotFound.

Motivo: a localização visual depende de características de textura. Áreas com pouca textura não permitem extrair pontos de característica.

Solução: isso é normal; mova a câmera para uma área rica em textura para iniciar.

No local e com textura rica, mas NotFound contínuo

A pessoa está no local e apontando para uma área com textura, mas ainda assim não consegue localizar por muito tempo.

Possíveis causas:

• Mudança de cena: o ambiente no local (como reforma, troca de pôsteres ou grande mudança de iluminação) difere muito da cena no momento do mapeamento.
• Coleta sem cobertura: a posição onde o usuário está ficou fora da área coberta pela coleta de mapeamento original.

Soluções:

• Mova-se para a área da rota coletada originalmente e tente novamente.
• Se a cena tiver sofrido uma mudança permanente e significativa, colete novamente e atualize o Block.

Causados pelo próprio serviço

Block recém-adicionado com WakingUp contínuo

Quando a biblioteca de localização acabou de ser configurada ou iniciada, o status do serviço pode exibir WakingUp ou NotFound por um longo período. Isso ocorre porque o serviço Mega tem mecanismo de inicialização fria; o primeiro carregamento precisa despertar do armazenamento frio. Mantenha a rede desimpedida, aguarde 10 a 30 segundos e tente novamente.

Serviço retorna exceção

Https status	Status code	Motivo
200	21	QPS excedeu o limite
200	1040 x	Parâmetros, biblioteca ou dados de mapa incorretos; consulte a descrição da mensagem específica
200	4000 x	Erro em nível de algoritmo; consulte a descrição específica
401	-	Falha de autenticação; consulte a descrição da mensagem específica
404	-	Caminho no URL inserido incorretamente
50x	-	Erro no programa do servidor

Soluções para exceções do serviço:

• QPS limit: entre em contato com a equipe comercial da EasyAR para expansão de QPS
• Falha de autenticação: resolva de acordo com a descrição específica da mensagem. Problemas comuns incluem grande desvio entre o horário do dispositivo e o horário padrão, API Key sem permissão CLS etc.
• Outras situações: informe a equipe da EasyAR para resolução

Feedback de problemas

Se, após a investigação acima, o problema ainda não puder ser resolvido, colete as informações abaixo e envie-as à equipe de suporte técnico da EasyAR.

Exportar informações de Serviço de localização Mega

• Desenvolvimento Unity, versão do plugin >= 4003
• Desenvolvimento Unity, versão do plugin 4.7 - 4002
• Desenvolvimento de miniprograma
• Outros cenários de uso do Mega Studio

Na ferramenta de editor do nó block que você está usando, clique no botão Diagnosis Info mostrado na figura abaixo para exportar as informações de diagnóstico do Mega Block. As informações de diagnóstico do Mega Block contêm apenas informações do Mega Block e da biblioteca de localização, sem outras informações sensíveis.

O formato do arquivo exportado deve ser Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Gravar arquivo EIF

Se você encontrar problemas ao testar em celular, use Toolbox para gravar arquivo EIF de celular

Se você encontrar problemas ao testar em óculos, use Toolbox para gravar arquivo EIF de óculos

Se você encontrar problemas no seu próprio aplicativo, pode usar seu aplicativo para gravar um arquivo EIF

Ao usar miniprograma WeChat, use miniprograma para gravar arquivo EIF

Gravar o fenômeno do problema com celular, óculos e outros dispositivos

No campo de AR, descrições textuais geralmente têm dificuldade para transmitir informações precisas, e a compreensão de cada pessoa pode variar muito. Ao mesmo tempo, gravações de tela em runtime são informações muito úteis, pois permitem que você e a equipe da EasyAR estabeleçam uma compreensão comum. É possível usar recursos integrados de celulares, óculos e outros dispositivos ou recorrer a software de terceiros para gravar. Observe que, durante a gravação de tela, o efeito de execução geralmente é afetado, e tanto o rastreamento quanto o desempenho podem sofrer impacto.

Nota

Antes de gravar a tela, recomenda-se consultar o Sample correspondente em runtime e exibir na tela algumas informações necessárias de Debug. Ao fornecer a gravação de tela, você também deve fornecer os dados EIF correspondentes ao período da gravação.

Feedback de problemas no desenvolvimento Unity

Se você encontrar problemas anormais durante o desenvolvimento Unity, verifique item por item se as 4 verificações abaixo já foram concluídas.

1. Já tentou a versão mais recente do EasyAR Sense Unity Plugin; versões novas geralmente incluem correções de bugs e novos recursos, portanto recomenda-se atualizar primeiro para a versão mais recente e testar
2. Já leu a documentação de desenvolvimento EasyAR e o guia Mega; a documentação geralmente inclui explicações para algumas situações
3. Já leu os logs do sistema e do Unity; recomenda-se fornecer logs completos ao fazer uma pergunta
4. Já tentou reproduzir o problema em um projeto Unity vazio, dentro do Sample

Se as 4 verificações acima já foram concluídas e ainda assim o problema não foi resolvido, você pode fornecer informações completas no EasyAR Sense Unity Plugin seguindo o fluxo abaixo, para que a equipe técnica da EasyAR possa analisar e resolver o problema.

1. Em Unity -> EasyAR -> Sense, selecione Perguntar

   

2. Em Perguntar, é necessário fornecer as seguintes informações

   • Selecione o ambiente de execução com problema; apenas um ambiente pode ser selecionado
   • Copie as informações do dispositivo: em EasyAR Session, defina DiagnosticsController.DumpSession como Log, copie a saída de um frame e preencha o resultado abaixo
   • Selecione todos os recursos EasyAR usados quando o problema ocorreu; múltiplas seleções são suportadas
   • Confirme que as 4 verificações acima foram concluídas; recomenda-se descrever, ao fazer a pergunta, como reproduzir o problema no Sample
   • Clique na função de copiar no canto superior direito Ao abrir a janela Perguntar pela primeira vez, as informações abaixo podem não ser exibidas por completo; elas aparecerão depois que você selecionar o ambiente e os recursos usados.

3. Clique abaixo em Ir para EasyAR Q&A para enviar as informações copiadas à EasyAR oficialmente, ou envie-as diretamente à equipe da EasyAR