Diagnostica e risoluzione dei problemi: il contenuto non viene visualizzato nell'applicazione

"Posso vedere il mondo reale, ma i contenuti virtuali non appaiono." Questo è uno dei problemi più comuni nello sviluppo di AR. Il problema potrebbe derivare da molteplici fattori, dalla localizzazione Mega stessa alla logica di rendering.

Questa guida ti aiuterà a diagnosticare e risolvere sistematicamente questo problema.

Flusso di risoluzione dei problemi: dall'esterno verso l'interno

Segui il principio "prima esterno, poi interno" per individuare efficientemente il problema. Esegui questi passaggi in ordine:

Passaggio uno: verifica dello stato di localizzazione mega con strumenti esterni (nessuna modifica al codice)

Prima di approfondire il codice dell'app, conferma che il servizio di localizzazione Mega funzioni correttamente. Questo passaggio cruciale aiuta a determinare se il problema riguarda la localizzazione Mega o l'integrazione nello sviluppo.

Usare Mega Toolbox (lato mobile)
- Installa Mega Toolbox App sul tuo telefono di test (se non già installato).
- Apri l'app e accedi alla funzione "Test di localizzazione in loco" o simile.
- Accedi con il tuo account e seleziona la stessa libreria di localizzazione usata nella tua app.
- Porta il telefono nella stessa posizione in cui i contenuti non vengono visualizzati nella tua app.
- Osserva il risultato:
  - Se Toolbox localizza correttamente (stato Found): Mega funziona! Il problema è interno all'app, probabilmente nella logica di rendering. Prosegui con il Passaggio due.
  - Se Toolbox fallisce (stato NotFound o altro): Il problema riguarda il servizio di localizzazione stesso. Analizza approfonditamente nella sezione successiva.
Usare la simulazione su PC (se disponibile EIF)
- Se hai registrato dati EIF per questa scena, riproducili nell'editor Unity su PC usando lo strumento session.
- Osserva il risultato:
  - Se la riproduzione ha successo (stato Found): Il problema è nel tuo codice o nell'ambiente specifico del dispositivo.
  - Se la riproduzione fallisce (stato NotFound o altro): Il problema riguarda il servizio di localizzazione stesso. Analizza nella sezione successiva.

Passaggio due: controlla la logica di rendering e contenuti interni all'app

Se il Passaggio uno conferma che Mega funziona, il problema è nel codice. Controlla questi punti:

I contenuti sono sotto il nodo corretto?:
- Hai posizionato correttamente gli oggetti 3D sotto i nodi MegaBlocks > Block_* generati automaticamente?
- Verifica la gerarchia tra contenuti e nodi Block per assicurarti che il rendering avvenga nella posizione corretta.
Il Block Root di MegaTracker è impostato correttamente?:
- Espandi AR Session e controlla che Block Root in Mega Tracker punti al nodo MegaBlocks generato.
I nodi MegaBlocks sono stati modificati?:
- Assicurati di non aver rinominato i nodi Block_* o modificato alcun valore nelle proprietà local transform.
L'ascolto degli eventi è corretto?:
- Hai modificato la logica di callback di MegaTracker?
- Il tuo codice istanzia o mostra i contenuti virtuali solo dopo l'evento di stato Found?
Rendering del visore e trasparenza:
- I tuoi oggetti virtuali sono oscurati? Controlla la coda di rendering e gli Shader.
- Su dispositivi VST (video see-through), verifica che il rendering sia correttamente sovrapposto al flusso video.
- Su dispositivi OST (optical see-through), controlla che i contenuti non siano illeggibili a causa di troppa luce ambientale.
Problemi intrinseci ai contenuti:
- Il prefab istanziato ha problemi? Es: modelli mancanti, errori negli Shader, scala a zero. Prova a posizionare manualmente lo stesso oggetto nella scena per verificare.

Analisi delle cause comuni di fallimento della localizzazione e suggerimenti

Se nel Passaggio uno Mega Toolbox fallisce, risolvi i problemi di localizzazione. Ecco cause comuni e soluzioni:

Causa uno: mappa e ambiente non corrispondono
L'ambiente fisico è cambiato significativamente rispetto alla mappatura, l'area non è stata coperta, o la mappa è errata.
Suggerimenti:
- Assicurati che la mappa caricata corrisponda allo spazio fisico attuale.
- Se l'ambiente è stato modificato (es. ristrutturazioni), riacquisisci e rigenera la mappa.
- Se l'area problematica non era coperta, aggiorna la mappa con acquisizioni supplementari.
Causa due: ambiente di inizializzazione scarso
Avvio dell'app in aree con pochi dettagli (es. pareti lisce, pavimento).
Suggerimenti:
- Guida l'utente ad avviare l'app in aree ricche di dettagli.
- Fornisci istruzioni chiare nell'UI, es. "Alza il telefono e guardati intorno".
Causa tre: problemi di rete o servizio
Latenza di rete che causa timeout, malfunzionamenti del servizio, o superamento dei limiti di concorrenza. Segnala eventuali problemi al team.
Causa quattro: limite delle capacità dell'algoritmo
La localizzazione Mega si basa su algoritmi avanzati, ma ha dei limiti. In caso di fallimenti persistenti in specifici scenari, segnalaci il problema con screen recording o dati EIF per aiutarci a migliorare.

Nota importante: la localizzazione Mega richiede tempo, solitamente 1-2 secondi. Fattori come congestione di rete, concorrenza elevata o surriscaldamento del dispositivo possono aumentare questo tempo. Progetta un'interfaccia di caricamento chiara (es. "Localizzazione in corso...") per gestire le aspettative dell'utente.

Nota

La prima localizzazione è solitamente più lenta delle successive (caricamento contenuti). È normale.
Movimenti rapidi del dispositivo possono causare perdita di localizzazione. Guida l'utente a muovere il dispositivo con stabilità.

Riepilogo e best practice

Verifica sempre prima con strumenti esterni: restringe rapidamente il problema a "localizzazione" o "rendering".
Gestisci le aspettative dell'utente: comunica tramite UI che la localizzazione richiede tempo e guida verso ambienti adatti.
Controlla la logica dei contenuti: assicurati che binding e impostazioni siano corretti.
Usa i log: log nei punti chiave (eventi, stato) aiutano a individuare problemi logici nel codice.

Con questa diagnosi sistematica, dovresti risolvere la maggior parte dei problemi di "contenuto non visualizzato". Se il problema persiste, prepara dati EIF e log e inviaci una segnalazione dettagliata tramite Segnalazione problemi.