Dépannage des problèmes de localisation Mega

Mega s’appuie sur des algorithmes avancés de localisation visuelle. La localisation haute précision est obtenue par recherche cloud de Mega Block et résolution par correspondance de caractéristiques visuelles. En usage réel, des erreurs de configuration, des changements d’environnement ou des fluctuations réseau peuvent provoquer un échec de localisation.

Ce document vous aide à juger rapidement l’état de localisation, à distinguer un « attente normale » d’une « erreur anormale », et à diagnostiquer rapidement les causes possibles selon trois grandes catégories : configuration, environnement et service.

Flux de localisation

Vous devez capturer les données de cartographie dans la zone cible, construire un Mega Block, ajouter le Mega Block reconstruit au dépôt de localisation, puis confirmer que le dépôt de localisation est utilisable.

Dans une zone déjà couverte par un Mega Block construit, avec un bon éclairage, beaucoup de détails et un réseau normal, la localisation réussit généralement en quelques secondes. Une fois la localisation réussie, la position et la pose actuelles de l’appareil dans le Mega Block sont retournées.

Juger l’état de localisation

• Si vous utilisez Mega Toolbox pour vérifier les résultats de localisation, vous pouvez consulter directement l’état de localisation

  

• Si vous êtes développeur Unity et qu’aucune localisation n’est possible, vous pouvez consulter à l’écran les informations exactes renvoyées par MegaTrackerLocalizationStatus. Si elles n’apparaissent pas à l’écran, il faut activer les informations de diagnostic.

  

Valeurs possibles de MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Erreur inconnue
Found	1	Block localisé
NotFound	2	Aucun Block localisé
RequestTimeout	3	Délai de requête dépassé (plus d’1 minute)
RequestIntervalTooLow	4	Intervalle de requête trop court
QpsLimitExceeded	5	Limite QPS dépassée
WakingUp	6	Service en cours de réveil
MissingSpotVersionId	7	SpotVersionId manquant, probablement non configuré
ApiTokenExpired	8	API Token expiré

Solutions aux exceptions ci-dessus :

• Délai de requête dépassé : vérifiez et corrigez l’état du réseau ; si nécessaire, augmentez le délai de requête MegaRequestTimeParameters.Timeout, mais un mauvais réseau affectera aussi la qualité du suivi, il faut donc autant que possible résoudre le problème réseau
• Intervalle de requête trop court : réduisez l’intervalle de requête
• Échec de connexion ou de transmission : vérifiez et corrigez l’état du réseau
• Limite QPS dépassée : contactez l’équipe commerciale EasyAR pour augmenter la capacité QPS
• Service en cours de réveil : le système se réveille, veuillez attendre un moment puis réessayer
• SpotVersionId manquant : veuillez configurer SpotVersionId
• API Token expiré : régénérez l’API Token dans le backend de gestion EasyAR

UnknownError correspond généralement à deux cas :

• échec de connexion ou de transmission
• réponse anormale du service

Pour UnknownError, vous pouvez obtenir des informations détaillées via MegaLocalizationResponse.ErrorMessage.

Dépannage par catégories d’erreurs courantes

Selon l’état renvoyé et les symptômes, les problèmes courants peuvent être divisés en trois catégories : configuration, environnement et service lui-même.

Problèmes de configuration

Ces problèmes surviennent généralement pendant l’intégration au développement et se manifestent par un service qui ne démarre pas du tout.

Lié à la licence

Si, pendant le développement ou les tests, les journaux ou l’écran affichent des problèmes comme License ou Invalid Key, les causes possibles sont : AppID/BundleID non concordants, licence expirée, formule incompatible, etc. Veuillez vérifier votre configuration de licence à l’aide du tableau ci-dessous.

Erreur	Solution
Invalid Key: No matched Bundle ID	Le Bundle ID ne correspond pas à la clé de licence ; modifiez l’un ou l’autre pour qu’ils correspondent
Invalid Key: No matched Package Name	Le Bundle ID ne correspond pas à la clé de licence ; modifiez l’un ou l’autre pour qu’ils correspondent
Invalid Key: License does not apply to current variant	Le SDK utilisé est celui d’un package entreprise mais la clé de licence n’est pas une licence entreprise, ou inversement
Invalid Key: License for an old version does not apply	La version de la licence est trop ancienne ; recréez une nouvelle licence
Invalid Key: Invalid format	Le format de la licence est incorrect, par exemple si la copie n’est pas complète
Invalid Key: Server verification failed	La licence a été supprimée ou ne dispose pas des droits d’utilisation de l’appareil ; pour un casque, contactez le service commercial pour ajouter l’autorisation
License does not apply to eyewear	La licence ne peut pas être utilisée sur un casque ; remplacez-la par une licence XR
License is expired	La licence a expiré

Veuillez aussi noter que les licences d’essai ont certaines limites ; l’utilisation d’une version payante d’EasyAR Sense et du service payant EasyAR Mega peut résoudre ce problème. Si vous utilisez déjà la version payante d’EasyAR Sense, vous pouvez ignorer ce message ou supprimer directement le texte concerné de l’exemple.

Image caméra anormale

Pendant le développement ou les tests d’une application EasyAR Mega, si vous rencontrez un écran noir, un crash, l’absence d’image caméra ou d’autres anomalies, veuillez suivre les étapes ci-dessous pour un diagnostic systématique et la collecte d’informations.

1. Essayer de résoudre soi-même

• Si vous utilisez Unity pour le développement et les tests, assurez-vous que Diagnostics Controller (Script) est coché dans AR Session (EasyAR) -> Inspector afin d’activer les informations de diagnostic.

  

• Vérifiez le contenu affiché à l’écran ou dans les logs, et voyez si le texte de l’UI donne une indication claire.

• Dans la plupart des cas, les messages d’erreur sont auto-explicatifs. Si l’écran ou les logs indiquent déjà la cause, vous pouvez corriger en conséquence. Par exemple : cameraDevice.openWithPreferredType fail (il faut vérifier si la caméra est disponible).

• Si le message indique « non pris en charge » (par exemple l’appareil ne prend pas en charge ARCore ou une autre fonctionnalité), il s’agit d’une limitation normale et aucun autre diagnostic n’est nécessaire.

2. Impossible de résoudre soi-même

   Veuillez d’abord essayer de résoudre le problème avec les informations existantes. Si ce n’est pas possible, afin d’aider l’équipe EasyAR à localiser rapidement le problème, fournissez impérativement des informations techniques précises et reproductibles, et évitez de vous limiter à une simple description du type « écran noir ». Les informations à fournir devraient inclure :

• Journaux complets : Unity ou Sense
• Captures d’écran ou enregistrement vidéo : écran complet en cas d’écran noir ; si des informations de diagnostic sont présentes, veillez à ce qu’elles soient visibles
• Informations détaillées sur l’appareil : modèle (par exemple iPhone 15, Huawei P40), version système (par exemple iOS 17.1, Android 14), version d’EasyAR Sense, version du plugin Unity EasyAR Sense, version de Unity, etc.

NotFound continu hors site

Le développeur teste dans un bureau avec un simulateur ou une vidéo enregistrée, mais la localisation reste impossible. Une cause possible est que le mode MegaLocationInputMode est réglé sur Onsite, alors que l’exécution n’a pas lieu sur site. Selon le mode d’entrée de position Mega, vous devez choisir le mode correct pendant le développement :

Constant	Value	Description
Onsite	0	Mode d’entrée pour l’usage sur site, où les données de position proviennent généralement de l’appareil et sont envoyées à Mega, en général traitées à l’intérieur de FrameFilter
Simulator	1	Mode d’entrée pour l’usage à distance, où les données de position doivent être simulées comme des données sur site et envoyées à Mega via l’interface correspondante (optionnel)
FramePlayer	2	Mode d’entrée utilisé lors de l’usage de FramePlayer. Ce mode est en lecture seule

Problèmes causés par l’environnement

Ce type de problème se manifeste lorsque le service fonctionne normalement mais que la localisation renvoie en continu NotFound.

Face à un mur blanc ou au sol, NotFound continu

Lorsque l’image caméra montre une grande surface de mur blanc, de verre ou de sol uni, l’état reste en NotFound.

Cause : la localisation visuelle dépend de caractéristiques de texture. Les zones pauvres en texture ne permettent pas d’extraire des points caractéristiques.

Solution : c’est un phénomène normal ; il faut déplacer la caméra vers une zone riche en texture pour démarrer.

Sur site et dans une zone riche en texture, mais NotFound continu

Vous êtes sur site, face à une zone texturée, mais la localisation reste impossible pendant longtemps.

Causes possibles :

• Changements de scène : l’environnement réel sur site (rénovation, changement d’affiche, forte variation de lumière, etc.) diffère trop de la scène lors de la cartographie.
• Capture incomplète : la position où se tient l’utilisateur dépasse la zone couverte par la cartographie d’origine.

Solutions :

• Déplacez-vous vers la zone du parcours capturée à l’origine et réessayez.
• Si la scène a subi un changement permanent majeur, il faut recapturer et mettre à jour le Block.

Problèmes liés au service

Block récemment ajouté, WakingUp continu

Après la configuration du dépôt de localisation ou son démarrage, l’état du service affiche WakingUp ou NotFound pendant longtemps. Comme le service Mega dispose d’un mécanisme de démarrage à froid, le premier chargement doit le réveiller depuis le stockage froid. Gardez le réseau disponible et réessayez après 10 à 30 secondes.

Réponse de service anormale

Https status	Status code	Cause
200	21	Limite QPS dépassée
200	1040 x	Paramètres, dépôt ou données de carte incorrects, voir la description détaillée du message
200	4000 x	Erreur au niveau de l’algorithme, voir la description détaillée
401	-	Échec d’authentification, voir la description détaillée
404	-	Chemin incorrect dans l’URL
50x	-	Erreur du programme serveur

Solutions aux erreurs de service :

• Limite QPS : contactez l’équipe commerciale EasyAR pour augmenter la capacité QPS
• Échec d’authentification : corrigez selon la description du message ; les problèmes courants incluent un décalage trop important entre l’heure de l’appareil et l’heure standard, ou l’absence de permission CLS pour la clé API
• Autres cas : veuillez les signaler à l’équipe EasyAR

Retour d’informations

Si le problème persiste après les vérifications ci-dessus, suivez les étapes suivantes pour collecter les informations et les transmettre au support technique EasyAR.

Exporter les informations du service de localisation Mega

• Développement Unity, version du plugin >= 4003
• Développement Unity, version du plugin 4.7 - 4002
• Développement de mini-programme
• Autres usages de Mega Studio

Dans l’outil d’éditeur du nœud block utilisé, cliquez sur le bouton Diagnosis Info de l’image ci-dessous pour exporter les informations de diagnostic du Mega Block. Les informations de diagnostic Mega Block ne contiennent que le Mega Block et les informations de dépôt de localisation, sans autres informations sensibles.

Le format du fichier exporté doit être Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Enregistrer un fichier EIF

Si vous rencontrez un problème lors d’un test sur téléphone, utilisez Toolbox pour enregistrer un fichier EIF téléphone

Si vous rencontrez un problème lors d’un test sur lunettes, utilisez Toolbox pour enregistrer un fichier EIF lunettes

Si vous rencontrez un problème dans votre propre application, vous pouvez enregistrer un fichier EIF avec votre application

Pour les mini-programmes WeChat, vous pouvez utiliser l’enregistrement EIF pour mini-programme

Enregistrer les symptômes avec un téléphone, des lunettes ou un autre appareil

Dans le domaine AR, une description textuelle transmet rarement une information précise ; l’interprétation de chacun peut énormément varier. En même temps, l’enregistrement d’écran en cours d’exécution est une information très utile, car il permet à vous et à l’équipe EasyAR de partager la même compréhension. Vous pouvez utiliser les fonctions intégrées au téléphone ou aux lunettes, ou un logiciel tiers pour enregistrer. Notez que l’enregistrement d’écran affecte généralement le résultat d’exécution, et que la qualité du suivi comme les performances peuvent être impactées.

Note

Avant l’enregistrement d’écran, il est recommandé d’afficher à l’écran les informations de debug nécessaires en vous référant à l’exemple correspondant. En fournissant l’enregistrement, vous devez aussi fournir les données EIF correspondantes pendant l’enregistrement.

Retour d’un problème de développement Unity

Si vous rencontrez un problème anormal pendant le développement Unity, vérifiez successivement les 4 points suivants.

1. Avez-vous essayé la dernière version du plugin Unity EasyAR Sense ? Les nouvelles versions contiennent généralement des corrections de bugs et de nouvelles fonctions ; il est conseillé de commencer par mettre à jour
2. Avez-vous lu la documentation de développement EasyAR et le guide Mega ? La documentation contient souvent des explications de certains cas
3. Avez-vous consulté les journaux système et Unity ? Il est conseillé de fournir les journaux complets lors de la demande
4. Avez-vous essayé de reproduire le problème dans un projet Unity vide à partir d’un exemple ?

Si vous avez vérifié les 4 points ci-dessus et que le problème persiste, vous pouvez fournir toutes les informations via le plugin Unity EasyAR Sense selon la procédure ci-dessous, afin que les techniciens EasyAR analysent et résolvent le problème.

1. Dans Unity -> EasyAR -> Sense, choisissez Poser une question

   

2. Dans Poser une question, vous devez fournir les informations suivantes

   • Choisir l’environnement d’exécution en cause, un seul environnement à la fois
   • Copier les informations de l’appareil : dans EasyAR Session, réglez DiagnosticsController.DumpSession sur Log, copiez la sortie d’une frame et collez-la ci-dessous
   • Choisir toutes les fonctions EasyAR concernées par le problème, sélection multiple prise en charge
   • Confirmer que les 4 vérifications ci-dessus ont été effectuées, et il est recommandé de décrire comment reproduire le problème dans l’exemple
   • Cliquer sur la fonction de copie en haut à droite Quand la fenêtre Poser une question s’ouvre, les informations affichées en bas sont incomplètes ; elles n’apparaîtront qu’après avoir choisi l’environnement et les fonctions utilisées.

3. Cliquez sur Accéder à EasyAR Q&A ci-dessous pour transmettre les informations copiées au site officiel EasyAR, ou les envoyer directement à l’équipe EasyAR