Guida alla risoluzione dei problemi di localizzazione Mega

Mega realizza una localizzazione ad alta precisione attraverso un avanzato algoritmo di localizzazione visiva, il recupero Mega Block basato su cloud e il calcolo di corrispondenza delle caratteristiche visive. Pertanto, durante l'uso effettivo, vari fattori come errori di configurazione, cambiamenti ambientali o fluttuazioni di rete potrebbero causare un fallimento della localizzazione.

Questo documento mira ad aiutarti a valutare rapidamente lo stato di localizzazione, distinguere tra "attesa normale" ed "errore anomalo", e a effettuare una diagnosi rapida basata su tre categorie principali di fattori: configurazione, ambiente e servizio.

Processo di posizionamento

È necessario raccogliere i dati di mappatura nell'area di destinazione, costruire il Mega Block, aggiungere il Mega Block già ricostruito alla libreria di localizzazione e verificare la disponibilità della libreria di localizzazione.

All'interno dell'area coperta da un Mega Block già costruito, con buona illuminazione ambientale, caratteristiche abbondanti e rete normale, il posizionamento di solito riesce in pochi secondi. Una volta posizionato con successo, verrà restituita la posizione corrente del dispositivo nel Mega Block e l'orientamento.

Verifica dello stato di localizzazione

• Se utilizzi Mega Toolbox per verificare il risultato della localizzazione, puoi visualizzare direttamente lo stato di localizzazione

  

• Se sei uno sviluppatore Unity e riscontri problemi di localizzazione, puoi controllare lo specifico messaggio restituito MegaTrackerLocalizationStatus sullo schermo. Se non visualizzato, attiva le informazioni di diagnostica.

  

I possibili valori di MegaTrackerLocalizationStatus

Costante	Valore	Descrizione
UnknownError	0	Errore sconosciuto
Found	1	Block localizzato
NotFound	2	Nessun Block localizzato
RequestTimeout	3	Timeout della richiesta (superati 1 minuto)
RequestIntervalTooLow	4	Intervallo tra le richieste troppo breve
QpsLimitExceeded	5	Limite QPS superato
WakingUp	6	Il servizio è in fase di avvio
MissingSpotVersionId	7	SpotVersionId mancante, probabilmente non impostato
ApiTokenExpired	8	API Token scaduto

Soluzioni per le eccezioni sopra:

• Timeout della richiesta: Verifica e risolvi i problemi di rete. Se necessario, aumenta il timeout della richiesta MegaRequestTimeParameters.Timeout. Tuttavia, una rete scadente influisce negativamente sul tracking, risolvi prioritariamente i problemi di rete.
• Intervallo tra le richieste troppo breve: Riduci la frequenza delle richieste.
• Connessione o trasmissione fallita: Verifica e risolvi i problemi di rete.
• Limite QPS superato: Contatta il team commerciale EasyAR per aumentare la capacità QPS.
• Il servizio è in fase di avvio: Il sistema è in fase di avvio, attendi prima di riprovare.
• SpotVersionId mancante: Configura lo SpotVersionId.
• API Token scaduto: Rigenera l'API Token nel pannello di gestione EasyAR.

UnknownError è solitamente dovuto a due situazioni:

• Connessione o trasmissione fallita
• Risposta anomala del servizio

Per UnknownError, dettagli aggiuntivi sono disponibili tramite MegaLocalizationResponse.ErrorMessage.

Classificazione degli errori comuni

In base allo stato e ai fenomeni restituiti dal posizionamento, i problemi comuni possono essere suddivisi nelle seguenti tre categorie: problemi di configurazione, fattori ambientali, il servizio stesso.

Problemi di configurazione

Questi problemi si verificano solitamente durante la fase di integrazione dello sviluppo e si manifestano con l'impossibilità completa di avviare il servizio.

Informazioni sulla license

Se durante lo sviluppo o i test, nei log o sugli schermi appaiono messaggi relativi a License, Invalid Key o problemi simili, le possibili cause includono: mancata corrispondenza tra AppID/BundleID, scadenza della License, piano tariffario non conforme, ecc. Si prega di verificare le impostazioni della propria License confrontandole con la tabella seguente.

Errore	Soluzione
Invalid Key: No matched Bundle ID	Il Bundle ID non corrisponde alla license key. Modificarne uno dei due per farli corrispondere.
Invalid Key: No matched Package Name	Il Bundle ID non corrisponde alla license key. Modificarne uno dei due per farli corrispondere.
Invalid Key: License does not apply to current variant	Utilizzo dell'SDK per pacchetti enterprise con una license key non enterprise, o viceversa.
Invalid Key: License for an old version does not apply	La license è troppo vecchia. Creare una nuova license.
Invalid Key: Invalid format	Formato della license errato, ad esempio non copiata completamente.
Invalid Key: Server verification failed	License eliminata o senza permessi per il dispositivo. Se utilizzata su dispositivi indossabili, contattare il reparto commerciale per aggiungere i permessi.
License does not apply to eyewear	La license non può essere utilizzata su dispositivi indossabili. Utilizzare una license xr.
License is expired	La license è scaduta.

Inoltre, si noti che le versioni di prova della License presentano alcune limitazioni. L'utilizzo della versione a pagamento di EasyAR Sense e dei servizi a pagamento EasyAR Mega risolve questo problema. Se si sta già utilizzando la versione a pagamento di EasyAR Sense, è possibile ignorare o rimuovere direttamente dal campione il testo relativo.

Anomalie della fotocamera

Durante lo sviluppo o il test di applicazioni EasyAR Mega, se si verificano problemi come schermo nero, crash, assenza di immagini dalla fotocamera o altre anomalie, seguire sistematicamente i passaggi seguenti per individuare e raccogliere informazioni.

1. Tentare di risolvere autonomamente

• Se si utilizza Unity per lo sviluppo o i test, assicurarsi di aver selezionato Diagnostics Controller (Script) in AR Session (EasyAR) -> Inspector per attivare le informazioni diagnostiche.

  

• Controllare il contenuto visualizzato sullo schermo o nei log, verificando se ci sono chiari messaggi testuali nell'interfaccia utente.

• Nella maggior parte dei casi, i messaggi di errore sono autoesplicativi. Se lo schermo o i log indicano la causa dell'errore, è possibile risolvere in base alla causa specifica. Ad esempio: cameraDevice.openWithPreferredType fail (è necessario verificare se la fotocamera è disponibile).

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

2. Impossibilità di risolvere autonomamente

   Si prega di tentare prima una risoluzione autonoma basandosi sulle informazioni disponibili. Se non è possibile risolvere autonomamente, per aiutare il personale EasyAR a individuare rapidamente il problema, fornire necessariamente informazioni tecniche dettagliate e riproducibili. Evitare di descrivere solo il fenomeno, come "schermo nero". Si consiglia di includere nel feedback:

• Log completi: Unity o Sense
• Screenshot o registrazione dello schermo: schermata completa durante lo schermo nero. Se sono presenti informazioni diagnostiche, assicurarsi che siano visibili e acquisirne uno 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 in loco, continuo NotFound

Gli sviluppatori utilizzano simulatori o registrazioni dello schermo per i test in ufficio, ma non riescono a individuare il problema. Una possibile causa è che la modalità MegaLocationInputMode sia impostata su Onsite, ma l'esecuzione non avviene in loco. È necessario selezionare la modalità corretta durante lo sviluppo, in base alla modalità di input della posizione Mega:

Costante	Valore	Descrizione
Onsite	0	Modalità di input per l'uso in loco. I dati di posizione vengono generalmente acquisiti dal dispositivo e inseriti in Mega, solitamente gestita internamente da FrameFilter
Simulator	1	Modalità di input per l'uso remoto. I dati di posizione devono essere simulati come dati in loco e inseriti in Mega tramite l'interfaccia corrispondente (opzionale)
FramePlayer	2	Modalità di input quando si utilizza FramePlayer. Questa modalità è di sola lettura

Fattori ambientali che causano

Questo tipo di problema si manifesta con il servizio funzionante normalmente, ma la localizzazione continua a restituire NotFound.

Persistente notFound quando si punta verso pareti bianche o superfici uniformi

Quando l'inquadratura della camera mostra ampie superfici come pareti bianche, vetri o terreni monocromatici, lo stato restituirà persistentemente NotFound.

Motivo: il posizionamento visivo si basa sulle caratteristiche tessiturali. Le aree a bassa tessitura non consentono l'estrazione di punti caratteristici.

Soluzione: questo è un comportamento normale. È necessario spostare la camera verso aree ricche di dettagli tessiturali per l'avvio.

In loco con texture ricche, ma persistente NotFound

L'utente è presente sul posto e rivolto verso un'area con texture, ma non riesce a stabilire il tracciamento dopo un lungo periodo.

Possibili cause:

• Modifiche ambientali: L'ambiente attuale (es. ristrutturazione, sostituzione di poster, cambiamenti estremi nell'illuminazione) presenta differenze significative rispetto alla scena durante la creazione della mappa.
• Area non coperta: La posizione in cui si trova l'utente è al di fuori della zona coperta durante la raccolta iniziale dei dati per la mappa.

Soluzioni:

• Spostarsi nella zona percorso originariamente coperta durante la raccolta dati e riprovare.
• Se l'ambiente ha subito modifiche permanenti e sostanziali, è necessario raccogliere nuovamente i dati e aggiornare il Block.

Causato dal servizio stesso

Blocco appena aggiunto, continua wakingup

Quando si configura appena la libreria di localizzazione o quando questa viene avviata, lo stato del servizio mostra WakingUp o rimane a lungo NotFound. Poiché il servizio Mega incorpora un meccanismo di cold-start, il caricamento iniziale richiede la riattivazione dal cold storage. Mantenere la rete stabile e riprovare dopo 10~30 secondi.

Servizio restituisce eccezione

Https status	Status code	Motivo
200	21	QPS supera il limite
200	1040x	Parametri, libreria o dati mappa non corretti, vedere la descrizione specifica del messaggio
200	4000x	Errore a livello algoritmo, vedere la descrizione specifica
401	-	Autenticazione fallita, vedere la descrizione specifica del messaggio
404	-	Percorso inserito nell'URL non corretto
50x	-	Errore del programma server

Metodi di risoluzione per eccezioni del servizio:

• Si verifica limitazione QPS: contattare il personale commerciale EasyAR per l'espansione QPS
• Si verifica autenticazione fallita: risolvere in base alla descrizione specifica del messaggio, problemi comuni includono una deviazione eccessiva dell'ora del dispositivo dall'ora standard, API Key senza autorizzazione CLS, ecc.
• Altri casi: si prega di segnalarli al personale EasyAR per la risoluzione

Segnalazione di problemi

Se non è possibile risolvere il problema dopo i controlli sopra indicati, procedi come segue per raccogliere informazioni e fornire feedback al team di supporto tecnico EasyAR.

Esportare le informazioni del servizio di localizzazione Mega

Accedi al tuo account in Mega Studio di Unity, seleziona la libreria di localizzazione con anomalie e individua il pulsante Esporta del servizio di localizzazione Mega mostrato nell'immagine sottostante. Il file esportato dovrebbe essere nel formato MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. Il servizio di localizzazione Mega contiene esclusivamente informazioni sui Mega Block e sulla libreria di localizzazione, senza includere altre informazioni sensibili.

Registrazione di file EIF

Se incontri problemi durante i test sul telefono, utilizza Toolbox per registrare file EIF dal telefono

Se incontri problemi durante i test con i headset, utilizza Toolbox per registrare file EIF dagli headset

Se incontri problemi nella tua applicazione, puoi registrare file EIF utilizzando la tua applicazione

Quando utilizzi i mini-programmi WeChat, puoi utilizzare registrazione di file EIF tramite mini-programma

Registrare il fenomeno problematico con dispositivi come telefoni, occhiali, etc.

Nel campo della realtà aumentata, le descrizioni testuali spesso non trasmettono informazioni accurate, e la comprensione può variare notevolmente da persona a persona. Allo stesso tempo, le registrazioni dello schermo durante l'esecuzione sono informazioni estremamente utili, permettendo a voi e al personale di EasyAR di stabilire una comprensione comune. È possibile utilizzare funzionalità integrate di dispositivi come telefoni, occhiali, etc., o affidarsi a software di terze parti per la registrazione. È importante notare che il processo di registrazione dello schermo generalmente influisce sulle prestazioni in esecuzione; l'efficacia del tracking e le prestazioni potrebbero risentirne.

Nota

Prima di registrare lo schermo, si consiglia di fare riferimento al corrispondente Sample durante l'esecuzione e visualizzare alcune necessarie informazioni di debug sullo schermo. Oltre a fornire la registrazione, dovreste fornire i dati EIF corrispondenti al periodo della registrazione.

Segnalazione problemi di sviluppo unity

Se durante lo sviluppo con Unity si verificano problemi anomali, è necessario verificare di aver completato i seguenti 4 controlli.

1. Aver provato la versione più recente di EasyAR Sense Unity Plugin. Le nuove versioni includono solitamente correzioni di bug e nuove funzionalità. Si consiglia di aggiornare prima alla versione più recente.
2. Aver consultato la documentazione di sviluppo di EasyAR e la Guida Mega. La documentazione fornisce spesso spiegazioni per situazioni specifiche.
3. Aver esaminato i log di sistema e di Unity. Si consiglia di fornire i log completi quando si richiede assistenza.
4. Aver tentato di replicare il problema in un progetto Unity vuoto o all'interno degli esempi (Sample).

Se, nonostante aver completato i 4 controlli sopra elencati, il problema persiste, è possibile fornire informazioni complete seguendo la procedura indicata di seguito in EasyAR Sense Unity Plugin. Ciò consentirà al team tecnico EasyAR di analizzare e risolvere il problema.

1. In Unity -> EasyAR -> Sense, selezionare Domanda

   

2. Nella sezione Domanda è necessario 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 incollare il risultato nel campo sottostante.
     
   • Selezionare tutte le funzionalità EasyAR utilizzate quando si è verificato il problema (selezione multipla consentita).
   • Confermare di aver completato i 4 controlli sopra elencati. Si consiglia di descrivere come replicare il problema negli esempi (Sample).
   • Fare clic sulla funzione di copia in alto a destra.
     
     All'apertura della finestra Domanda, le informazioni nella parte inferiore potrebbero non essere completamente visibili. Saranno visualizzate solo dopo aver selezionato l'ambiente e le funzionalità utilizzate.
     

3. Fare clic su Vai a EasyAR Q&A in basso per inviare le informazioni copiate al supporto ufficiale EasyAR, oppure fornirle direttamente a un membro del personale EasyAR.