Diagnosi e correzione: il contenuto non viene visualizzato nell'applicazione

"Posso vedere il mondo reale, ma il contenuto virtuale non appare." Questo è uno dei problemi più comuni nello sviluppo AR. Il problema può derivare da più fasi, dalla Mega localization stessa fino alla logica di rendering.

Questo articolo guida nella diagnosi e risoluzione sistematica del problema.

Flusso di troubleshooting: dall'esterno all'interno

Seguire il principio "prima esterno, poi interno" permette di localizzare il problema in modo efficiente. Eseguire i seguenti passaggi in ordine:

Passaggio 1: usare strumenti esterni per verificare lo stato di Mega localization (senza modificare codice)

Prima di approfondire il codice dell'applicazione, confermare prima se il servizio Mega localization funziona normalmente. Questo è il passaggio più importante e aiuta a capire se il problema è nella Mega localization stessa o nell'integrazione dell'applicazione, ad esempio nel rendering.

Usare Mega Toolbox (mobile)
- Installare Mega Toolbox App sul telefono di test, se non è ancora installata.
- Aprire l'App ed entrare in On-site verification and diagnosis tool.
- Accedere all'account e selezionare la stessa localization library dell'applicazione.
- Portare il telefono nella stessa posizione in cui l'applicazione non riesce a mostrare contenuti durante il test.
- Osservare il risultato:
  - Se Toolbox localizza con successo (lo stato dell'interfaccia mostra Found): il servizio Mega localization è normale. Il problema è dentro l'applicazione, specialmente nella logica di rendering e visualizzazione contenuti. Passare al Passaggio 2.
  - Se Toolbox non localizza (lo stato dell'interfaccia mostra NotFound o altro): il problema è nel servizio localization stesso. Vedere la sezione successiva per un'analisi più approfondita.
Usare esecuzione simulata lato PC (se EIF è stato acquisito)
- Se sono stati registrati EIF data per questa scena, è possibile riprodurre i dati nell'editor Unity su PC usando lo strumento di verifica session.
- Osservare il risultato:
  - Se la localization riesce durante la riproduzione (lo stato dell'interfaccia mostra Found): il problema è nel codice dell'applicazione o nell'ambiente specifico del device.
  - Se la localization fallisce durante la riproduzione (lo stato dell'interfaccia mostra NotFound o altro): il problema è nel servizio localization stesso. Vedere la sezione successiva per un'analisi più approfondita.

Passaggio 2: controllare rendering e logica dei contenuti interni all'applicazione

Se il Passaggio 1 conferma che il servizio Mega localization è normale, il problema è nel codice dell'applicazione. Controllare quanto segue:

Se il contenuto è posizionato sotto il nodo corretto:
- Gli oggetti 3D sono stati posizionati correttamente sotto i nodi MegaBlocks > Block_* generati automaticamente dallo strumento?
- Controllare la relazione gerarchica tra contenuto e nodi Block per assicurare che il contenuto virtuale venga renderizzato nella posizione corretta a runtime.
Se Block Root di MegaTracker è impostato correttamente:
- Espandere AR Session e controllare se Block Root in Mega Tracker è il nodo MegaBlocks generato dallo strumento.
Se i nodi MegaBlocks sono stati modificati:
- Assicurarsi che i nomi dei nodi Block_* non siano stati modificati e che nessun valore nelle proprietà local transform sia stato modificato.
Se l'ascolto eventi è corretto:
- È stata modificata la logica di gestione callback di localization di MegaTracker?
- Il codice istanzia o mostra contenuto virtuale solo dopo il trigger dell'evento di stato localization riuscita?
Rendering headset e trasparenza:
- L'oggetto virtuale è occluso da altri oggetti? Controllare render queue e Shader.
- Se si usa un device VST (video see-through), controllare se il rendering è correttamente sovrapposto al video stream.
- Se si usa un device OST (optical see-through), controllare se il contenuto è poco visibile perché la luce ambientale è troppo forte.
Problemi del contenuto stesso:
- Il Prefab istanziato ha problemi? Ad esempio file modello mancanti, errori Shader, scale impostata a 0 e così via. Provare a posizionare manualmente lo stesso oggetto nella scena e verificare se viene visualizzato normalmente.

Analisi delle cause comuni di fallimento localization e suggerimenti di miglioramento

Se nel Passaggio 1 anche Mega Toolbox non riesce a localizzare, controllare e risolvere attentamente il problema di localization. Cause comuni e contromisure:

Causa 1: mappa e ambiente non corrispondono
L'ambiente sul posto è cambiato molto rispetto al momento di acquisizione e mapping, oppure l'area di esperienza non era coperta durante l'acquisizione, o la mappa stessa è errata.
Suggerimenti di miglioramento:
- Assicurarsi che la mappa caricata nella localization library sia coerente con lo spazio fisico corrente nella scena.
- Se l'ambiente è stato modificato, ad esempio ristrutturazione o cambio esposizione, è necessario riacquisire e rigenerare la mappa.
- Se l'area problematica non era coperta durante acquisizione e mapping, rigenerare la mappa tramite incremental update.
Causa 2: ambiente di inizializzazione non ideale
L'applicazione viene avviata in un'area con poche texture, ad esempio parete a tinta unita o puntando verso il pavimento.
Suggerimenti di miglioramento:
- Guidare gli utenti ad avviare l'applicazione in un'area con texture ricca per aiutare il sistema a completare rapidamente la initial localization.
- Fornire prompt chiari nella UI dell'applicazione, ad esempio "Solleva il telefono e guardati intorno".
Causa 3: problemi di rete o servizio
La latenza di rete causa timeout nelle richieste al servizio localization, oppure il servizio localization stesso presenta un guasto, o viene superato il limite di uso concorrente. Per questi ultimi casi, inviare feedback tempestivamente.
Causa 4: raggiunto il limite di capacità dell'algoritmo
Mega localization è basata su computer vision avanzata, AI e altri algoritmi, ma non è onnipotente e presenta certi limiti di capacità. Quando la localization fallisce continuamente in alcune scene o posizioni, è possibile inviare feedback tramite registrazioni schermo, registrazioni EIF data e altri metodi, aiutandoci a migliorare e iterare continuamente gli algoritmi.

Inoltre, va precisato che Mega localization richiede un processo, solitamente circa 1-2 secondi. Considerando la complessità delle scene reali, come congestione di rete, alta concurrency, riscaldamento del telefono e riduzione di frequenza, il tempo può essere maggiore. Pertanto è possibile progettare nell'applicazione una chiara pagina di caricamento/attesa che informi l'utente "Localizing...", evitando che l'utente creda erroneamente che il servizio sia inattivo o che la localization non sia trovata a causa dell'attesa.

Nota

La prima localization è solitamente più lenta delle successive, perché il sistema deve caricare i contenuti corrispondenti dopo la prima localization riuscita. È normale.
Muovere rapidamente il device può causare perdita di localization. Guidare gli utenti a muovere il device in modo stabile.

Riepilogo e best practice

Verificare sempre prima con strumenti esterni: è il modo più rapido per restringere l'ambito del problema a "localization" o "rendering".
Creare aspettative ragionevoli per l'utente: usare prompt UI per far sapere agli utenti che la localization richiede tempo e guidarli verso un ambiente adatto.
Prestare attenzione alla logica dei contenuti: assicurarsi che impostazioni come content binding siano corrette.
Usare bene i log: stampare log nei punti chiave, come trigger eventi, acquisizione posa e stato risposta, aiuta a individuare rapidamente problemi di logica del codice.

Con il troubleshooting sistematico sopra, dovrebbe essere possibile risolvere la maggior parte dei problemi di "contenuto non visualizzato". Se il problema persiste, preparare EIF data e log e inviare un report dettagliato tramite Issue report.