Table of Contents

Diagnosticar e corrigir: conteúdo não aparece na aplicação

"Consigo ver o mundo real, mas o conteúdo virtual não aparece." Este é um dos problemas mais comuns no desenvolvimento AR. O problema pode se originar em vários estágios, desde a própria Mega localization até sua lógica de renderização.

Este artigo orienta você a diagnosticar e resolver esse problema de forma sistemática.

Fluxo de troubleshooting: de fora para dentro

Seguir o princípio "primeiro externo, depois interno" permite localizar o problema com eficiência. Execute as etapas a seguir em ordem:

Etapa 1: usar ferramentas externas para verificar o status da Mega localization (sem alterar código)

Antes de se aprofundar no código da aplicação, confirme primeiro se o serviço Mega localization está funcionando normalmente. Esta é a etapa mais crítica e ajuda a determinar se o problema está na própria Mega localization ou na integração da aplicação, como renderização.

  1. Usar Mega Toolbox (mobile)

    • Instale o Mega Toolbox App no telefone de teste, se ainda não estiver instalado.
    • Abra o App e entre em On-site verification and diagnosis tool.
    • Faça login na sua conta e selecione a mesma localization library da sua aplicação.
    • Leve o telefone para o mesmo local onde sua aplicação não consegue exibir conteúdo durante o teste.
    • Observe o resultado:
      • Se o Toolbox localizar com sucesso (a interface mostra status Found): o serviço Mega localization está normal. O problema está dentro da sua aplicação, especialmente na lógica de renderização e exibição de conteúdo. Vá para a Etapa 2.
      • Se o Toolbox falhar ao localizar (a interface mostra NotFound ou outro status): o problema está no próprio serviço de localization. Consulte a próxima seção para análise aprofundada.

  2. Usar execução simulada no PC (se EIF já foi adquirido)

    • Se você já gravou EIF data para essa cena, é possível reproduzir os dados no Unity editor no PC usando a ferramenta de verificação session.
    • Observe o resultado:
      • Se a localization tiver sucesso na reprodução (a interface mostra Found): o problema está no código da aplicação ou ambiente específico do dispositivo.
      • Se a localization falhar na reprodução (a interface mostra NotFound ou outro status): o problema está no próprio serviço de localization. Consulte a próxima seção para análise aprofundada.

Etapa 2: verificar renderização e lógica de conteúdo dentro da aplicação

Se a Etapa 1 confirmar que o serviço Mega localization está normal, o problema está no código da aplicação. Verifique:

  1. Se o conteúdo está abaixo do nó correto:

    • Você colocou corretamente os objetos 3D abaixo dos nós MegaBlocks > Block_* gerados automaticamente pela ferramenta?
    • Verifique a hierarquia entre o conteúdo e os nós Block para garantir que o conteúdo virtual seja renderizado na posição correta em runtime.

  2. Se o Block Root do MegaTracker está configurado corretamente:

    • Expanda AR Session e verifique se Block Root em Mega Tracker é o nó MegaBlocks gerado pela ferramenta.

  3. Se os nós MegaBlocks foram alterados:

    • Certifique-se de que os nomes dos nós Block_* não foram modificados e que nenhum valor das propriedades local transform foi alterado.

  4. Se o event listening está correto:

    • Você modificou a lógica de tratamento callback de localization do MegaTracker?
    • Seu código instancia ou exibe conteúdo virtual somente depois que o evento de status de localization bem-sucedida é acionado?

  5. Renderização de headset e transparência:

    • Seu objeto virtual está oculto por outros objetos? Verifique render queue e Shader.
    • Se usar dispositivo VST (video see-through), verifique se sua renderização está corretamente sobreposta ao fluxo de vídeo.
    • Se usar dispositivo OST (optical see-through), verifique se o conteúdo fica difícil de ver devido à luz ambiente muito forte.

  6. Problemas do próprio conteúdo:

    • Há algum problema com o Prefab instanciado? Por exemplo, arquivos de modelo ausentes, erro de Shader, escala 0 etc. Tente colocar manualmente o mesmo objeto na cena e veja se ele aparece normalmente.

Análise de causas comuns de falha de localization e sugestões de melhoria

Se na Etapa 1 o Mega Toolbox também não consegue localizar, verifique e resolva cuidadosamente o problema de localization. Causas comuns e contramedidas:

  • Causa 1: mapa e ambiente não correspondem
    O ambiente local mudou muito em relação ao momento de acquisition e mapping, ou a área da experiência não foi coberta durante a aquisição, ou o próprio mapa está incorreto.
    Sugestões de melhoria:

    • Certifique-se de que o mapa carregado na sua localization library é consistente com o espaço físico atual na cena.
    • Se o ambiente foi remodelado, como reforma ou troca de exposição, é necessário adquirir novamente e gerar o mapa.
    • Se a área problemática não foi coberta durante acquisition e mapping, gere novamente o mapa por incremental update.

  • Causa 2: ambiente de inicialização ruim
    A aplicação é iniciada em uma área com pouca textura, como parede de cor sólida ou apontando para o chão.
    Sugestões de melhoria:

    • Oriente os usuários a iniciar a aplicação em uma área com textura rica para ajudar o sistema a concluir rapidamente a initial localization.
    • Forneça prompts claros na UI da aplicação, como "Levante o telefone e olhe ao redor".

  • Causa 3: problemas de rede ou serviço
    Latência de rede causa timeout nas solicitações do serviço de localization, ou o próprio serviço de localization apresenta falha, ou o limite de uso concorrente é excedido. Para os últimos casos, envie feedback para nós rapidamente.

  • Causa 4: limite de capacidade do algoritmo atingido
    Mega localization é baseada em computer vision, AI e outros algoritmos avançados, mas não é onipotente e possui certos limites de capacidade. Quando a localization continua falhando em algumas cenas ou pontos, você pode nos enviar feedback por gravação de tela, gravação de EIF data e outros métodos para nos ajudar a melhorar e iterar continuamente os algoritmos.

Além disso, Mega localization precisa de um processo, geralmente cerca de 1-2 segundos. Considerando a complexidade de cenas reais, como congestionamento de rede, alta concurrency, aquecimento do telefone e redução de frequência, esse tempo pode ser maior. Portanto, você pode criar uma tela clara de loading/espera na aplicação informando "Localizing...", evitando que o usuário pense erroneamente que o serviço caiu ou que a localization não foi encontrada por causa da espera.

Nota
  • A primeira localization geralmente é mais lenta que as posteriores, pois o sistema precisa carregar o conteúdo correspondente após a primeira localization bem-sucedida. Isso é normal.
  • Mover rapidamente o dispositivo pode causar perda de localization. Oriente os usuários a mover o dispositivo suavemente.

Resumo e melhores práticas

  • Sempre verifique primeiro com ferramentas externas: isso reduz rapidamente o escopo do problema para "localization" ou "rendering".
  • Estabeleça expectativas razoáveis para o usuário: use prompts de UI para informar que localization leva tempo e guiar o usuário para um ambiente adequado.
  • Preste atenção à lógica de conteúdo: certifique-se de que configurações como content binding estão corretas.
  • Use bem os logs: imprimir logs em pontos-chave, como disparo de evento, aquisição de pose e status de resposta, ajuda a localizar rapidamente problemas de lógica de código.

Com o troubleshooting sistemático acima, você deve conseguir resolver a maioria dos problemas de "conteúdo não aparece". Se o problema persistir, prepare EIF data e logs e envie um relatório detalhado para nós por Issue report.