Guia de solução de problemas de falha de posicionamento mega

O mega utiliza um algoritmo avançado de posicionamento visual, alcançando alta precisão através da recuperação baseada em nuvem de mega blocks e do cálculo de correspondência de características visuais. Portanto, na prática, falhas de posicionamento podem ocorrer devido a várias razões, como erros de configuração, alterações ambientais ou flutuações de rede.

Este documento visa ajudá-lo a avaliar rapidamente o estado de posicionamento, distinguir entre "espera normal" e "erro anormal", e realizar um diagnóstico rápido com base em três categorias principais: configuração, ambiente e serviço.

Fluxo de localização

É necessário coletar dados de mapeamento na área-alvo e construir um Mega Block, adicionar o Mega Block já reconstruído à biblioteca de localização e verificar a disponibilidade da biblioteca de localização.

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

Verificando o estado de localização

• Se você usar o Mega Toolbox para verificar os resultados de localização, pode verificar diretamente o estado de localização

  

• Se você é um desenvolvedor Unity e enfrenta problemas de localização, pode verificar as informações específicas retornadas MegaTrackerLocalizationStatus na tela. Se essas informações não estiverem visíveis, é necessário ativar as informações de diagnóstico.

  

Valores possíveis para MegaTrackerLocalizationStatus

Constante	Valor	Descrição
UnknownError	0	Erro desconhecido
Found	1	Bloco localizado
NotFound	2	Bloco não localizado
RequestTimeout	3	Tempo limite da solicitação excedido (mais de 1 minuto)
RequestIntervalTooLow	4	Intervalo entre solicitações muito curto
QpsLimitExceeded	5	Limite de QPS excedido
WakingUp	6	Serviço em processo de inicialização
MissingSpotVersionId	7	SpotVersionId ausente, possivelmente não configurado
ApiTokenExpired	8	Token de API expirado

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

• Tempo limite da solicitação: Verifique e repare a situação da rede. Se necessário, aumente o tempo limite da solicitação MegaRequestTimeParameters.Timeout. No entanto, problemas de rede também podem afetar o rastreamento, portanto, é essencial resolver os problemas de rede.
• Intervalo entre solicitações muito curto: Reduza a frequência das solicitações.
• Falha de conexão ou transmissão: Verifique e repare a situação da rede.
• Limite de QPS excedido: Contate o suporte comercial da EasyAR para aumentar a capacidade de QPS.
• Serviço em processo de inicialização: O sistema está iniciando. Aguarde um momento e tente novamente.
• SpotVersionId ausente: Configure o SpotVersionId.
• Token de API expirado: Gere um novo token de API no painel de gerenciamento da EasyAR.

O UnknownError geralmente ocorre em dois cenários:

• Falha de conexão ou transmissão.
• Resposta excepcional do serviço.

Para UnknownError, detalhes podem ser obtidos através de MegaLocalizationResponse.ErrorMessage.

Classificação e solução de problemas de erros comuns

Com base no estado e fenómenos reportados pelo posicionamento, os problemas comuns podem ser classificados nas três categorias seguintes: problemas de configuração, fatores ambientais e o próprio serviço.

Problema de configuração

Este tipo de problema geralmente ocorre durante a fase de desenvolvimento e integração, manifestando-se como o serviço não conseguir iniciar completamente.

Licença relacionada

Se durante o desenvolvimento ou testes, os logs ou mensagens na tão indicarem problemas como Licença, Chave inválida etc., as possíveis causas incluem: AppID/BundleID não correspondente, licença expirada, plano incompatível, entre outros. Por favor, verifique as configurações da sua licença conforme a tabela abaixo.

Erro	Solução
Invalid Key: No matched Bundle ID	O Bundle ID não corresponde à chave da licença. Por favor, altere um deles para que correspondam
Invalid Key: No matched Package Name	O Bundle ID não corresponde à chave da licença. Por favor, altere um deles para que correspondam
Invalid Key: License does not apply to current variant	Utilizou o SDK do pacote empresarial com uma chave de licença não empresarial, ou usou o SDK não empresarial com uma chave de licença do pacote empresarial
Invalid Key: License for an old version does not apply	A licença é de uma versão muito antiga. Deve criar uma nova licença
Invalid Key: Invalid format	Formato da licença inválido, por exemplo, não copiou completamente
Invalid Key: Server verification failed	Licença excluída ou sem permissão de uso do dispositivo. Se for para uso em headset, contate o comercial para adicionar permissão
License does not apply to eyewear	A licença não pode ser usada em headsets. Por favor, substitua pela licença xr
License is expired	Licença expirada

Além disso, note que licenças de versão de avaliação têm algumas limitações. Utilizar o EasyAR Sense na versão paga e os serviços pagos do EasyAR Mega pode resolver isso. Se já estiver usando o EasyAR Sense pago, pode ignorar ou remover diretamente o texto relevante do sample.

Problema com a imagem da câmera

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

1. Tente resolver por conta própria

• Se estiver desenvolvendo ou testando com Unity, certifique-se de ter marcado Diagnostics Controller (Script) em AR Session (EasyAR) -> Inspector para ativar as informações de diagnóstico.
• Verifique o conteúdo exibido na tela ou nos logs, procurando por avisos textuais explícitos na interface do usuário (UI).
• Na maioria dos casos, as mensagens de erro são autoexplicativas. Se a tela ou os logs indicarem a causa, você pode resolvê-la com base nisso. Por exemplo: cameraDevice.openWithPreferredType fail (é necessário verificar se a câmera está disponível).
• Se a mensagem indicar "não suportado" (por exemplo, dispositivo não suporta ARCore ou outra característica), trata-se de uma limitação normal, não sendo necessária investigação adicional.

2. Incapaz de resolver por conta própria

   Tente resolver primeiro com as informações disponíveis. Se não for possível resolver sozinho, para ajudar a equipe do EasyAR a identificar o problema rapidamente, é essencial fornecer informações técnicas detalhadas e reproduzíveis. Evite descrever apenas o fenômeno, como "tela preta". Recomenda-se incluir no feedback:

• Logs completos: Logs do Unity ou do EasyAR Sense.
• Captura de tela ou gravação de tela: Tela completa durante o problema (tela preta). Se houver informações de diagnóstico visíveis, capture-as na imagem.
• Informações detalhadas do dispositivo: Modelo do dispositivo (por exemplo, iPhone 15, HUAWEI P40), versão do sistema operacional (por exemplo, iOS 17.1, Android 14), versão do EasyAR Sense, versão do EasyAR Sense Unity Plugin, versão do Unity, etc.

Não no local, continuou NotFound

Os desenvolvedores usaram simuladores ou gravações de tela para testes no escritório, mas não conseguiram localizar. A possível razão é que o modo MegaLocationInputMode estava definido como Onsite, mas não estava sendo executado no local. É necessário selecionar o modo correto durante o desenvolvimento, de acordo com o modo de entrada de localização do Mega:

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

Fatores ambientais causam

Este tipo de problema se manifesta como o serviço normal, mas o posicionamento continua retornando NotFound.

Em direção a parede branca, chão contínuo NotFound

Quando a imagem da câmera mostra uma grande área de parede branca, vidro ou chão de cor sólida, o status retornará continuamente NotFound.

Motivo: O posicionamento visual depende de características de textura. Áreas de textura fraca não podem extrair pontos característicos.

Solução: Este é um comportamento normal. É necessário mover a câmera em direção a uma área com textura rica para iniciar.

No local e com texturas ricas, mas persistentemente NotFound

A pessoa está no local, diante de uma área com texturas, mas não consegue localizar-se com sucesso por um longo período.

Possíveis causas:

• Mudança de cenário: O ambiente no local (como reformas, troca de pôsteres, mudanças bruscas de iluminação) difere significativamente do cenário durante o mapeamento.
• Área não coberta na coleta: A posição onde o usuário está ficou fora da área coberta durante o mapeamento inicial.

Soluções:

• Mover-se para as áreas da rota originalmente mapeada e tentar novamente.
• Se o cenário sofreu alterações permanentes e significativas, será necessário re-coletar e atualizar o Block.

Causado pelo próprio serviço

Acabei de adicionar Block, continuando WakingUp

Quando a biblioteca de localização é configurada ou iniciada, o status do serviço mostra WakingUp ou NotFound por um longo período. Isso ocorre porque o serviço Mega possui um mecanismo de inicialização a frio, e o carregamento inicial requer acordar do armazenamento frio. Mantenha a rede estável e aguarde 10~30 segundos antes de tentar novamente.

Exceção retornada pelo serviço

Status Https	Código de status	Motivo
200	21	QPS excedeu o limite
200	1040 x	Parâmetro, biblioteca ou dados do mapa incorretos, consulte a descrição específica da mensagem
200	4000 x	Erro de nível de algoritmo, consulte a descrição específica
401	-	Falha na autenticação, consulte a descrição específica da mensagem
404	-	Entrada de caminho no URL incorreta
50x	-	Erro do programa do servidor

Métodos de resolução para exceções de serviço:

• Se ocorrer limitação de QPS: entre em contato com a equipe comercial da EasyAR para expansão de QPS
• Se ocorrer falha na autenticação: resolva de acordo com a descrição específica da mensagem; problemas comuns incluem desvio excessivo do horário do dispositivo em relação ao horário padrão, falta de permissão CLS para a API Key, etc.
• Outros casos: por favor, reporte à equipe da EasyAR para resolução

Problema de feedback

Se após a verificação acima o problema ainda não puder ser resolvido, siga as etapas abaixo para coletar informações e fornecer feedback à equipe de suporte técnico do EasyAR.

Exportar informações do serviço de localização Mega

Faça login na sua conta no Mega Studio do Unity, selecione a biblioteca de localização com anomalias e encontre o botão Exportar do Serviço de Localização Mega, conforme ilustrado abaixo. O formato do arquivo exportado deve ser MegaStudio_ServiceInfo_username_AA-MM-DD_HH-MM-SS.json. O Serviço de Localização Mega contém apenas informações sobre Mega Blocks e a biblioteca de localização, sem outros dados sensíveis.

Gravar eif file

Ao encontrar problemas durante testes em telefones, use o Toolbox para gravar eif file do telefone

Ao encontrar problemas durante testes em óculos, use o Toolbox para gravar eif file dos óculos

Se encontrar problemas em seu próprio aplicativo, você pode usar seu aplicativo para gravar eif file

Ao usar o WeChat Mini Program, você pode gravar eif file via Mini Program

Gravar o fenómeno do problema usando dispositivos como telefones, óculos

No campo de AR, a descrição textual geralmente tem dificuldade em transmitir informações precisas, e a compreensão de cada pessoa pode ser muito diferente. Ao mesmo tempo, a gravação de tela durante o tempo de execução é uma informação muito útil, permitindo que você e a equipe do EasyAR estabeleçam uma compreensão comum. Você pode usar funções integradas de dispositivos como telefones, óculos ou software de terceiros para gravação. É importante notar que o processo de gravação de tela geralmente afeta o desempenho em tempo de execução, podendo prejudicar tanto o efeito de rastreamento quanto o desempenho.

[!NOTA] Antes de gravar a tela, recomenda-se consultar a amostra correspondente durante o tempo de execução e exibir informações de depuração necessárias na tela. Ao fornecer a gravação de tela, você deve fornecer os dados EIF correspondentes coletados durante a gravação.

Feedback de problemas de desenvolvimento Unity

Se você encontrar problemas anormais durante o desenvolvimento com Unity, deve verificar sequencialmente se já completou as 4 verificações abaixo.

1. Já experimentou a versão mais recente do EasyAR Sense Unity Plugin, que geralmente inclui correções de bugs e novos recursos. Recomenda-se atualizar primeiro para a versão mais recente.
2. Já leu a documentação de desenvolvimento do EasyAR e o Guia Mega, que frequentemente contêm explicações sobre situações específicas.
3. Já analisou os logs do sistema e do Unity. Sugere-se fornecer logs completos ao relatar problemas.
4. Já tentou reproduzir o problema em um projeto Unity vazio ou nas amostras (Sample).

Se, após completar essas 4 verificações, o problema persistir, você pode fornecer informações completas no EasyAR Sense Unity Plugin seguindo o fluxo abaixo para análise e resolução pela equipe técnica do EasyAR.

1. No Unity, navegue até EasyAR -> Sense e selecione 提问 (Perguntar).
   

2. Em 提问, forneça 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 cole o resultado abaixo.
     
   • Selecione todas as funcionalidades do EasyAR utilizadas quando o problema ocorreu (múltipla escolha permitida).
   • Confirme que completou as 4 verificações acima. Sugere-se descrever como reproduzir o problema nas amostras (Sample).
   • Clique no ícone de cópia no canto superior direito.
     
     Ao abrir a janela 提问, as informações abaixo podem não ser exibidas completamente. Elas só serão visíveis após selecionar o ambiente e as funcionalidades.
     

3. Clique em 前往 EasyAR 问答 abaixo para enviar as informações copiadas à equipe oficial do EasyAR, ou forneça-as diretamente a um membro da equipe.