Guida alla risoluzione dei problemi di localizzazione Mega

Mega si basa su algoritmi avanzati di localizzazione visiva e realizza una localizzazione ad alta precisione tramite recupero dei Mega Block nel cloud e calcolo della corrispondenza delle feature visive. Nell'uso reale, diversi fattori come errori di configurazione, cambiamenti dell'ambiente o fluttuazioni di rete possono causare il fallimento della localizzazione.

Questo documento ha lo scopo di aiutarvi a determinare rapidamente lo stato della localizzazione, distinguere tra "attesa normale" ed "errore anomalo" ed eseguire una diagnosi rapida in base a tre categorie di fattori: configurazione, ambiente e servizio.

Flusso di localizzazione

Dovete raccogliere dati di mappatura nell'area obiettivo e costruire un Mega Block, quindi aggiungere il Mega Block ricostruito alla libreria di localizzazione e verificare che la libreria di localizzazione sia disponibile.

Nell'area coperta dal Mega Block già costruito, con buona illuminazione ambientale, feature ricche e rete normale, la localizzazione di solito riesce entro pochi secondi. Dopo la localizzazione riuscita, vengono restituite posizione e posa correnti del dispositivo nel Mega Block.

Determinare lo stato della localizzazione

• Se usate Mega Toolbox per verificare i risultati della localizzazione, potete vedere direttamente lo stato di localizzazione

  

• Se siete sviluppatori Unity e non riuscite a localizzare, potete vedere sullo schermo le informazioni specifiche restituite dalla localizzazione, MegaTrackerLocalizationStatus. Se queste informazioni non sono presenti sullo schermo, dovete attivare le informazioni diagnostiche.

  

Valori possibili di MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Errore sconosciuto
Found	1	Localizzato al Block
NotFound	2	Block non localizzato
RequestTimeout	3	Timeout della richiesta (oltre 1 minuto)
RequestIntervalTooLow	4	Intervallo di richiesta troppo breve
QpsLimitExceeded	5	QPS oltre il limite
WakingUp	6	Il servizio si sta risvegliando
MissingSpotVersionId	7	SpotVersionId mancante, forse non impostato
ApiTokenExpired	8	API Token scaduto

Soluzioni per le anomalie sopra indicate:

• Timeout della richiesta: controllare e correggere la situazione di rete. Se necessario, aumentare il tempo di timeout della richiesta MegaRequestTimeParameters.Timeout; tuttavia, una cattiva rete influisce anche sull'effetto del tracking, quindi è necessario risolvere il più possibile il problema di rete
• Intervallo di richiesta troppo breve: ridurre l'intervallo di richiesta
• Connessione o trasmissione non riuscita: controllare e correggere la situazione di rete
• QPS oltre il limite: contattare il team commerciale EasyAR per aumentare la capacità QPS
• Il servizio si sta risvegliando: il sistema è in fase di risveglio; attendere un po' prima di riprovare
• SpotVersionId mancante: configurare SpotVersionId
• API Token scaduto: rigenerare l'API Token nella console di gestione EasyAR

UnknownError presenta spesso due situazioni

• Connessione o trasmissione non riuscita
• Il servizio restituisce un'eccezione

Per UnknownError, potete ottenere informazioni dettagliate tramite MegaLocalizationResponse.ErrorMessage

Troubleshooting per categorie di errori comuni

In base allo stato e al fenomeno restituiti dalla localizzazione, i problemi comuni possono essere divisi nelle seguenti tre categorie: problemi di configurazione, fattori ambientali e servizio stesso.

Problemi di configurazione

Questo tipo di problema si verifica di solito nella fase di sviluppo e integrazione, e si manifesta con l'impossibilità totale di avviare il servizio.

Relativi alla License

Se durante lo sviluppo o il test, nel log o sullo schermo compaiono problemi come License, Invalid Key, le possibili cause includono: AppID/BundleID non corrispondente, License scaduta, piano non compatibile, ecc. Controllate le impostazioni della vostra License secondo la tabella seguente.

Errore	Soluzione
Invalid Key: No matched Bundle ID	Bundle ID e license key non corrispondono; modificare uno dei due affinché corrispondano
Invalid Key: No matched Package Name	Package Name e license key non corrispondono; modificare uno dei due affinché corrispondano
Invalid Key: License does not apply to current variant	È stato usato l'SDK del pacchetto enterprise con una license key non enterprise, oppure è stato usato un SDK non enterprise con una license key enterprise
Invalid Key: License for an old version does not apply	La versione della license è troppo vecchia; creare una nuova license
Invalid Key: Invalid format	Il formato della license è errato, ad esempio non è stata copiata interamente
Invalid Key: Server verification failed	La license è stata eliminata o non ha permesso di utilizzo sul dispositivo. Per l'uso su headset, contattare il commerciale per aggiungere il permesso
License does not apply to eyewear	La license non può essere usata su eyewear; sostituirla con una xr license
License is expired	La license è scaduta

Inoltre, dovete notare che la versione di prova della License ha alcune limitazioni. Usare la versione a pagamento di EasyAR Sense e il servizio EasyAR Mega a pagamento può risolvere questo problema. Se state già usando la versione a pagamento di EasyAR Sense, potete ignorare o rimuovere direttamente il testo relativo dal sample.

Anomalie dell'immagine della camera

Durante lo sviluppo o il test di un'app EasyAR Mega, se si verificano problemi anomali come schermo nero, crash o assenza dell'immagine della camera, seguite i passaggi seguenti per troubleshooting sistematico e raccolta delle informazioni.

1. Provare a risolvere autonomamente

• Se usate Unity per sviluppo e test, assicuratevi che in AR Session (EasyAR) -> Inspector sia selezionato Diagnostics Controller (Script) per attivare le informazioni diagnostiche.

  

• Controllate il contenuto visualizzato sullo schermo o nel log e verificate se nell'UI sono presenti prompt testuali chiari.

• Nella maggior parte dei casi, i messaggi di errore sono autoesplicativi. Se il messaggio sullo schermo o il log indica già la causa dell'errore, potete risolverlo in base alla causa specifica. Ad esempio: cameraDevice.openWithPreferredType fail (è necessario controllare se la camera è disponibile).

• Se viene indicato "non supportato" (ad esempio il dispositivo non supporta ARCore o altre funzionalità), si tratta di una limitazione normale e non servono ulteriori verifiche.

2. Impossibile risolvere autonomamente

   Provate prima a risolvere autonomamente in base alle informazioni disponibili. Se non riuscite a risolvere il problema, per aiutare il personale EasyAR a individuarlo rapidamente, fornite informazioni tecniche dettagliate e riproducibili; evitate di descrivere solo fenomeni come "schermo nero". Le informazioni consigliate includono:

• Log completo: Unity o Sense
• Screenshot o registrazione schermo: schermata completa durante lo schermo nero; se sono presenti informazioni diagnostiche, assicuratevi che siano visibili e acquisite nello screenshot.
• Informazioni dettagliate sul dispositivo: modello del dispositivo (ad esempio iPhone 15, HUAWEI P40), versione del sistema (ad esempio iOS 17.1, Android 14), versione di EasyAR Sense, versione di EasyAR Sense Unity Plugin, versione di Unity, ecc.

Non in esecuzione sul posto, NotFound continuo

Gli sviluppatori usano simulatori o registrazioni schermo in ufficio per testare, ma non riescono mai a localizzare. Una possibile causa è che la modalità MegaLocationInputMode sia impostata su Onsite, mentre l'esecuzione non avviene sul posto. Durante lo sviluppo è necessario scegliere la modalità corretta in base alla modalità di input posizione di Mega:

Constant	Value	Description
Onsite	0	Modalità di input per l'uso sul posto; i dati di posizione sono di solito ottenuti dal dispositivo e inseriti in Mega, normalmente gestiti internamente da FrameFilter
Simulator	1	Modalità di input per l'uso remoto; i dati di posizione devono essere simulati come dati sul posto e inseriti in Mega tramite l'interfaccia corrispondente (opzionale)
FramePlayer	2	Modalità di input quando si usa FramePlayer. Questa modalità è in sola lettura

Causati da fattori ambientali

Questo tipo di problema si manifesta con il servizio normale, ma la localizzazione restituisce continuamente NotFound.

NotFound continuo quando si inquadra una parete bianca o il pavimento

Quando l'immagine della camera contiene grandi aree di pareti bianche, vetro o pavimenti in tinta unita, lo stato restituisce continuamente NotFound.

Motivo: la localizzazione visiva dipende dalle feature di texture. Nelle aree a texture debole non è possibile estrarre feature point.

Soluzione: è un fenomeno normale; occorre spostare la camera verso un'area ricca di texture per l'avvio.

Sul posto e con texture ricche, ma NotFound continuo

L'utente è sul posto e inquadra un'area con texture, ma non riesce a localizzare per molto tempo.

Possibili cause:

• Cambiamenti della scena: l'ambiente sul posto (ad esempio ristrutturazioni, sostituzione di poster, forte variazione di illuminazione) è troppo diverso dalla scena al momento della mappatura.
• Raccolta non coperta: la posizione dell'utente supera l'area coperta dalla raccolta di mappatura originale.

Soluzioni:

• Spostarsi nell'area del percorso raccolto originariamente e riprovare.
• Se la scena ha subito cambiamenti permanenti e significativi, è necessario raccogliere di nuovo i dati e aggiornare il Block.

Causati dal servizio stesso

Block appena aggiunto, WakingUp continuo

Subito dopo aver configurato la libreria di localizzazione o appena avviata, lo stato del servizio mostra WakingUp o NotFound per un periodo prolungato. Questo accade perché il servizio Mega ha un meccanismo di cold start e al primo caricamento deve risvegliarsi dallo storage freddo. Mantenete la rete stabile, attendete 10~30 secondi e riprovate.

Il servizio restituisce un'eccezione

Https status	Status code	Motivo
200	21	QPS oltre il limite
200	1040 x	Parametri, libreria o dati mappa non corretti; vedere la descrizione del messaggio specifico
200	4000 x	Errore a livello di algoritmo; vedere la descrizione specifica
401	-	Autenticazione non riuscita; vedere la descrizione del messaggio specifico
404	-	Percorso nell'URL inserito in modo errato
50x	-	Errore del programma server

Soluzioni in caso di eccezione del servizio:

• Limite QPS: contattare il team commerciale EasyAR per aumentare la capacità QPS
• Autenticazione non riuscita: risolvere in base alla descrizione specifica del messaggio. Problemi comuni includono deviazione eccessiva tra l'ora del dispositivo e l'ora standard, API Key senza permesso CLS, ecc.
• Altri casi: segnalare al personale EasyAR per la risoluzione

Feedback sul problema

Se dopo il troubleshooting sopra il problema non è ancora risolto, raccogliete le informazioni seguenti e inviatele al team di supporto tecnico EasyAR.

Esportare le informazioni di Mega Location Service

• Sviluppo Unity, versione plugin >= 4003
• Sviluppo Unity, versione plugin 4.7 - 4002
• Sviluppo mini-program
• Altri scenari d'uso di Mega Studio

Nello strumento editor del nodo block che state usando, fate clic sul pulsante Diagnosis Info mostrato nella figura seguente per esportare le informazioni diagnostiche del Mega Block. Le Informazioni diagnostiche Mega Block contengono solo informazioni sul Mega Block e sulla libreria di localizzazione, e non contengono altre informazioni sensibili.

Il formato del file esportato deve essere Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Registrare il file EIF

Se riscontrate problemi durante il test su telefono, usate Toolbox per registrare un file EIF del telefono

Se riscontrate problemi durante il test su occhiali, usate Toolbox per registrare un file EIF degli occhiali

Se il problema si verifica nella vostra applicazione, potete usare la vostra applicazione per registrare un file EIF

Quando usate un mini-program WeChat, potete usare mini-program per registrare un file EIF

Registrare il fenomeno del problema usando telefoni, occhiali e altri dispositivi

Nel campo AR, le descrizioni testuali spesso non riescono a trasmettere informazioni precise e ogni persona può interpretarle in modo molto diverso. Allo stesso tempo, una registrazione dello schermo durante l'esecuzione è un'informazione molto utile, perché consente a voi e al personale EasyAR di costruire una comprensione condivisa. Potete usare le funzioni integrate di telefoni, occhiali e altri dispositivi, oppure software di terze parti per registrare. Va notato che durante la registrazione dello schermo, in generale, l'effetto di esecuzione può essere influenzato; tracking e prestazioni possono risentirne.

Nota

Prima della registrazione, si consiglia di fare riferimento al Sample corrispondente durante l'esecuzione e visualizzare sullo schermo alcune informazioni Debug necessarie. Oltre alla registrazione dello schermo, dovete fornire anche i dati EIF corrispondenti al periodo della registrazione.

Feedback sui problemi di sviluppo Unity

Se incontrate problemi anomali durante lo sviluppo Unity, dovete verificare uno per uno se avete completato i 4 controlli seguenti.

1. Avete già provato l'ultima versione di EasyAR Sense Unity Plugin. Le nuove versioni di solito includono correzioni di bug e nuove funzionalità; si consiglia di aggiornare prima all'ultima versione e riprovare
2. Avete già letto la documentazione di sviluppo EasyAR e la guida Mega, che spesso contengono spiegazioni per determinate situazioni
3. Avete già letto i log di sistema e di Unity; quando ponete domande è consigliato fornire il log completo
4. Avete già provato a riprodurre il problema in un progetto Unity vuoto, nel Sample

Se avete completato i 4 controlli sopra ma non riuscite ancora a risolvere il problema, potete fornire informazioni complete in EasyAR Sense Unity Plugin seguendo il flusso qui sotto, affinché il personale tecnico EasyAR possa analizzare e risolvere il problema.

1. In Unity -> EasyAR -> Sense selezionate Question

   

2. In Question dovete fornire le seguenti informazioni

   • Selezionare l'ambiente di esecuzione in cui si verifica il problema, è possibile selezionare un solo ambiente
   • Copiare le informazioni del dispositivo: in EasyAR Session, impostare DiagnosticsController.DumpSession su Log, copiare l'output di un frame e inserirlo nel campo sottostante
   • Selezionare tutte le funzionalità EasyAR usate quando si è verificato il problema, supporta selezione multipla
   • Confermare di aver completato i 4 controlli sopra; quando si pone la domanda è consigliato descrivere come riprodurre il problema nel Sample
   • Fare clic sulla funzione di copia nell'angolo in alto a destra Quando la finestra Question viene aperta per la prima volta, le informazioni in basso non sono visualizzate completamente; saranno mostrate dopo aver selezionato ambiente e funzionalità usate.

3. Fate clic su Go to EasyAR Q&A in basso per inviare ufficialmente le informazioni copiate a EasyAR, oppure inviatele direttamente al personale EasyAR