Diagnóstico e reparação: problema de conteúdo não exibido na aplicação

“Posso ver o mundo real, mas o conteúdo virtual não aparece.” Este é um dos problemas mais comuns no desenvolvimento de AR. A causa pode estar em múltiplas etapas, desde o próprio posicionamento Mega até a lógica de renderização da sua aplicação.

Este guia irá orientá-lo a diagnosticar e resolver este problema de forma sistemática.

Fluxo de diagnóstico: do externo para o interno

Seguir o princípio de “primeiro o externo, depois o interno” permite localizar o problema de forma eficiente. Execute os seguintes passos em ordem:

Passo um: validar o estado do posicionamento Mega usando ferramentas externas (sem modificar código)

Antes de mergulhar no código da sua aplicação, confirme primeiro se o serviço de posicionamento Mega em si está funcionando corretamente. Este é o passo mais crítico, pois ajuda a determinar se o problema está no próprio posicionamento Mega ou na integração do desenvolvimento da aplicação, como a renderização.

Usar o Mega Toolbox (aplicativo móvel)
- Instale o Aplicativo Mega Toolbox no seu telefone de teste (se ainda não estiver instalado).
- Abra o aplicativo e vá para a ferramenta Validação e Diagnóstico de Campo.
- Faça login na sua conta e selecione a mesma biblioteca de posicionamento usada na sua aplicação.
- Leve o telefone para o mesmo local onde o conteúdo não é exibido durante o teste da sua aplicação.
- Observe o resultado:
  - Se o Toolbox posicionar com sucesso (o status na interface mostra Found): Parabéns! O serviço de posicionamento Mega está normal. O problema está dentro da sua aplicação, especificamente na lógica de renderização e exibição de conteúdo. Pule para o Passo dois.
  - Se o Toolbox falhar no posicionamento (o status na interface mostra NotFound ou outro): O problema está no próprio serviço de posicionamento. Consulte a próxima seção para uma análise mais aprofundada.
Usar a execução simulada no PC (se os dados EIF foram coletados)
- Se você gravou dados EIF para este cenário, pode reproduzir esses dados no editor Unity usando a ferramenta de validação de sessão no PC.
- Observe o resultado:
  - Se o posicionamento for bem-sucedido durante a reprodução (o status na interface mostra Found): O problema está no código da sua aplicação ou no ambiente específico do dispositivo.
  - Se o posicionamento falhar durante a reprodução (o status na interface mostra NotFound ou outro): O problema está no próprio serviço de posicionamento. Consulte a próxima seção para uma análise mais aprofundada.

Passo dois: verificar a lógica de renderização e conteúdo dentro da aplicação

Se o Passo Um confirmar que o serviço de posicionamento Mega em si está normal, então o problema está no código da sua aplicação. Verifique os seguintes pontos:

O conteúdo está posicionado sob o nó correto?:
- Você posicionou corretamente os objetos 3D sob os nós MegaBlocks > Block_* gerados automaticamente pela ferramenta?
- Verifique a hierarquia entre o conteúdo e os nós Block para garantir que a posição de renderização do conteúdo virtual esteja correta durante a execução.
O Block Root do MegaTracker está configurado corretamente?:
- Expanda a Sessão AR e verifique se o Block Root no Mega Tracker é o nó MegaBlocks gerado pela ferramenta.
O nó MegaBlocks foi alterado?:
- Certifique-se de que os nomes dos nós Block_* não foram modificados e que nenhum valor nas propriedades de transform local foi alterado.
A escuta de eventos está correta?:
- Você modificou a lógica de tratamento de retorno de chamada (callback) de posicionamento do MegaTracker?
- Seu código só executa a operação de instanciação ou exibição do conteúdo virtual após o evento de status de posicionamento bem-sucedido ser acionado?
Renderização do headset e transparência:
- Seu objeto virtual está sendo ocultado por outros objetos? Verifique a fila de renderização e o Shader.
- Se estiver usando um dispositivo VST (video see-through), verifique se sua renderização está sendo sobreposta corretamente no fluxo de vídeo.
- Se estiver usando um dispositivo OST (optical see-through), verifique se o conteúdo não está visível devido à luz ambiente muito forte.
Problemas no próprio conteúdo:
- O prefab que você está instanciando tem algum problema? Por exemplo, arquivo de modelo ausente, erro de Shader, escala 0, etc. Tente colocar manualmente um objeto idêntico na cena para ver se ele é exibido normalmente.

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

Se no Passo um você descobrir que o Mega Toolbox também não consegue posicionar, é necessário examinar e resolver o problema de posicionamento com cuidado. Aqui estão as causas e contramedidas comuns:

Causa um: mapa e ambiente não correspondem
O ambiente físico mudou significativamente em comparação com o momento da captura e geração do mapa, ou a área de experiência não foi coberta durante a captura, ou o mapa em si está incorreto.
Sugestão de melhoria:
- Certifique-se de que o mapa carregado na sua biblioteca de posicionamento corresponde à cena do espaço físico atual.
- Se o ambiente foi reformado (como decoração, troca de mobília), é necessário recolher e gerar um novo mapa.
- Se a área onde ocorre o problema não foi coberta durante a captura e geração do mapa, é necessário regenerar o mapa através de uma atualização complementar.
Causa dois: ambiente de inicialização inadequado
Iniciar a aplicação em uma área com pouca textura (como uma parede lisa, apontando para o chão).
Sugestão de melhoria:
- Oriente os usuários a iniciarem a aplicação em áreas ricas em textura, para ajudar o sistema a completar o posicionamento inicial rapidamente.
- Forneça instruções claras na interface do usuário da aplicação, como “Levante o telefone e olhe ao redor”.
Causa três: problemas de rede ou serviço
Atrasos na rede causando timeout nas solicitações do serviço de posicionamento, ou o próprio serviço de posicionamento apresentando falhas, ou excedendo o limite de uso simultâneo, etc. Para o último caso, entre em contato conosco imediatamente.
Causa quatro: atingindo os limites da capacidade do algoritmo
O posicionamento Mega é baseado em algoritmos avançados de visão computacional, IA, etc., mas não é infalível e possui certos limites de capacidade algorítmica. Quando ocorrem falhas contínuas de posicionamento em certos cenários ou pontos, você pode nos fornecer feedback através de gravações de tela, gravação de dados EIF, etc., para nos ajudar a melhorar e iterar continuamente os algoritmos.

Além disso, é importante destacar que o posicionamento Mega requer um processo, geralmente em torno de 1-2 segundos. Considerando a complexidade de cenários reais, como congestionamento de rede, alta simultaneidade, redução de frequência do telefone devido ao aquecimento, esse tempo pode ser maior. Portanto, na aplicação, pode-se projetar uma interface de carregamento/espera clara, informando ao usuário “Posicionando...”, para evitar que o usuário pense erroneamente que o serviço caiu ou não está posicionando devido à espera.

Nota

O posicionamento inicial geralmente é mais lento do que os subsequentes, porque o sistema precisa carregar o conteúdo correspondente após o sucesso do posicionamento inicial. Isso é normal.
Mover o dispositivo rapidamente pode causar perda de posicionamento. Oriente os usuários a moverem o dispositivo de forma estável.

Resumo e melhores práticas

Sempre valide primeiro com ferramentas externas: Isso reduz mais rapidamente o escopo do problema para “posicionamento” ou “renderização”.
Estabeleça expectativas razoáveis para o usuário: Use dicas na interface do usuário para informar ao usuário que o posicionamento leva tempo e oriente-o para um ambiente adequado.
Preste atenção à lógica do conteúdo: Certifique-se de que as configurações, como o v