Guide de dépannage des échecs de localisation de mega

Mega repose sur un algorithme avancé de localisation visuelle, utilisant la recherche de blocs Mega dans le cloud et la correspondance des caractéristiques visuelles pour calculer une localisation haute précision. Par conséquent, dans la pratique, diverses raisons telles que des erreurs de configuration, des changements environnementaux ou des fluctuations réseau peuvent entraîner des échecs de localisation.

Ce document vise à vous aider à évaluer rapidement l'état de la localisation, à distinguer une "attente normale" d'une "erreur anormale", et à effectuer un diagnostic rapide en fonction des trois principales catégories de facteurs : la configuration, l'environnement et le service.

Processus de localisation

Vous devez collecter des données de cartographie dans la zone cible, construire un Mega Block, ajouter le Mega Block déjà reconstruit à la bibliothèque de localisation, et vérifier la disponibilité de la bibliothèque de localisation.

Dans les zones couvertes par un Mega Block déjà construit, avec un bon éclairage environnemental, riche en caractéristiques et un réseau normal, la localisation réussit généralement en quelques secondes. Une fois localisé avec succès, le système retournera la position actuelle de l'appareil dans le Mega Block ainsi que son orientation.

Déterminer l'état de localisation

Si vous utilisez Mega Toolbox pour vérifier les résultats de localisation, vous pouvez directement consulter l'état de localisation
Si vous êtes développeur Unity et rencontrez des problèmes de localisation, vous pouvez consulter les informations détaillées MegaTrackerLocalizationStatus à l'écran. Si ces informations n'apparaissent pas, activez les informations de diagnostic.

Valeurs possibles de MegaTrackerLocalizationStatus

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

Solutions pour ces exceptions :

Délai d'attente dépassé : Vérifiez et corrigez le réseau. Si nécessaire, augmentez le délai d'attente (MegaRequestTimeParameters.Timeout). Un réseau instable impacte le suivi, privilégiez une résolution réseau.
Intervalle entre requêtes trop court : Augmentez l'intervalle entre les requêtes.
Échec de connexion/transmission : Vérifiez et corrigez le réseau.
Limite QPS dépassée : Contactez l'équipe commerciale EasyAR pour augmenter la capacité QPS.
Service en démarrage : Le système démarre, réessayez après un délai.
SpotVersionId manquant : Configurez le SpotVersionId.
API Token expiré : Régénérez l'API Token dans l'admin EasyAR.

L'erreur UnknownError a généralement deux causes :

Échec de connexion ou de transmission
Réponse anormale du service

Pour UnknownError, consultez les détails via MegaLocalizationResponse.ErrorMessage

Classification des erreurs courantes

En fonction de l'état et des symptômes renvoyés par le positionnement, les problèmes courants peuvent être classés en trois catégories : problèmes de configuration, facteurs environnementaux et service lui-même.

Problèmes de configuration

Ce type de problème se produit généralement lors de la phase de développement et d'intégration, se manifestant par une incapacité totale du service à démarrer.

Licence associée

Si lors du développement ou des tests, les journaux ou messages à l'écran indiquent des problèmes liés à Licence, Clé invalide, etc., les causes possibles incluent : une incompatibilité AppID/BundleID, une licence expirée, un forfait non conforme, etc. Veuillez vérifier vos paramètres de licence en vous référant au 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 les faire correspondre.
Invalid Key: No matched Package Name	Le Bundle ID ne correspond pas à la clé de licence. Modifiez l'un ou l'autre pour les faire correspondre.
Invalid Key: License does not apply to current variant	Utilisation du SDK entreprise avec une clé de licence non-entreprise, ou utilisation du SDK standard avec une clé de licence entreprise.
Invalid Key: License for an old version does not apply	La version de la licence est trop ancienne. Créez une nouvelle licence.
Invalid Key: Invalid format	Format de licence incorrect (ex: copie incomplète).
Invalid Key: Server verification failed	Licence supprimée ou sans autorisation d'utilisation sur l'appareil. Pour un casque, contactez le service commercial pour ajouter les droits.
License does not apply to eyewear	La licence ne peut pas être utilisée sur un casque. Utilisez une licence xr.
License is expired	Licence expirée.

De plus, notez que les licences d'essai présentent certaines limitations. L'utilisation d'EasyAR Sense version payante et des services EasyAR Mega payants résout ce problème. Si vous utilisez déjà EasyAR Sense en version payante, vous pouvez ignorer ou supprimer directement le texte concerné depuis l'exemple.

Anomalie de l'image de la caméra

Lors du développement ou du test d'une application EasyAR Mega, si des problèmes tels qu'un écran noir, des plantages ou l'absence d'image de la caméra surviennent, suivez ces étapes pour diagnostiquer et collecter systématiquement les informations.

Tentative de résolution autonome

Si vous utilisez Unity pour le développement ou les tests, assurez-vous d'avoir coché Diagnostics Controller (Script) dans AR Session (EasyAR) -> Inspector pour activer les informations de diagnostic.
Vérifiez le contenu affiché à l'écran ou dans les journaux, et recherchez des indications textuelles claires dans l'interface utilisateur (UI).
Dans la plupart des cas, les messages d'erreur sont auto-descriptifs. Si l'écran ou les journaux indiquent la cause de l'erreur, vous pouvez la résoudre en conséquence. Par exemple : cameraDevice.openWithPreferredType fail (vérifiez si la caméra est disponible).
Si le message indique "Non supporté" (par exemple, appareil non compatible avec ARCore ou d'autres fonctionnalités), il s'agit d'une limitation normale. Aucun diagnostic supplémentaire n'est nécessaire.

Résolution autonome impossible

Veuillez d'abord tenter de résoudre le problème avec les informations disponibles. Si vous ne parvenez pas à le résoudre seul, afin d'aider le support EasyAR à identifier rapidement la cause, il est essentiel de fournir des informations techniques détaillées et reproductibles. Évitez de simplement décrire le symptôme (par exemple, "écran noir"). Nous vous recommandons d'inclure dans votre rapport :

Des journaux complets : Unity ou Sense.
Une capture d'écran ou un enregistrement vidéo : l'écran complet lors du problème (écran noir). Si des informations de diagnostic sont visibles, assurez-vous de les capturer.
Des informations détaillées sur l'appareil : modèle (par exemple, iPhone 15, HUAWEI P40), version du système d'exploitation (par exemple, iOS 17.1, Android 14), version d'EasyAR Sense, version du plugin Unity EasyAR Sense, version d'Unity, etc.

Not Found en continu lors de l'exécution hors site

Les développeurs testent avec un simulateur ou un enregistrement d'écran au bureau, mais ne parviennent pas à localiser. La cause possible est que le mode MegaLocationInputMode est défini sur Onsite, mais l'exécution ne se fait pas sur site. Il est nécessaire de sélectionner le mode correct pendant le développement, en fonction du mode de saisie de la localisation Mega :

Constante	Valeur	Description
Onsite	0	Mode de saisie pour une utilisation sur site. Les données de localisation sont généralement obtenues à partir de l'appareil et saisies dans Mega, généralement traitées en interne par FrameFilter
Simulator	1	Mode de saisie pour une utilisation à distance. Les données de localisation doivent être simulées comme des données sur site et saisies dans Mega via l'interface correspondante (optionnel)
FramePlayer	2	Mode d'entrée lors de l'utilisation de `FramePlayer`. Ce mode est en lecture seule

Causés par des facteurs environnementaux

Ce type de problème se manifeste par un service normal, mais la localisation renvoie continuellement NotFound.

Sur un mur blanc, sol continu NotFound

Lorsque la caméra capture une grande surface de mur blanc, de verre ou de sol uni, l'état retournera continuellement NotFound.

Cause : Le positionnement visuel dépend des caractéristiques de texture. Les zones à texture faible ne permettent pas d'extraire des points caractéristiques.

Solution : Ceci est normal. Déplacez la caméra vers une zone présentant une texture riche pour l'initialisation.

Sur place et avec des textures riches, mais NotFound persistant

L'utilisateur est sur place, face à une zone texturée, mais ne parvient pas à se localiser avec succès pendant une période prolongée.

Causes possibles :

Changement de scène : L'environnement actuel (par exemple, rénovation, changement d'affiches, variation brutale de l'éclairage) présente des différences trop importantes par rapport à la scène lors de la création de la carte.
Couverture non acquise : La position où se trouve l'utilisateur dépasse la zone couverte lors de l'acquisition initiale pour la création de la carte.

Solutions :

Se déplacer vers les zones du parcours initialement acquises pour essayer.
Dans le cas où la scène a subi des changements permanents et majeurs, il est nécessaire de recréer et de mettre à jour le Block.

Le service lui-même provoqué

Bloc nouvellement ajouté, wakingup continu

Lorsque vous venez de configurer la bibliothèque de localisation ou de la démarrer, le statut du service affiche WakingUp ou reste NotFound pendant une période prolongée. Cela est dû au mécanisme de démarrage à froid du service Mega, qui nécessite un réveil depuis le stockage froid lors du premier chargement. Maintenez une connexion réseau stable, attendez 10 à 30 secondes et réessayez.

Service retourne une exception

Statut Https	Code de statut	Raison
200	21	QPS dépasse la limite
200	1040 x	Paramètres, bibliothèque ou données cartographiques incorrects, voir la description spécifique du message
200	4000 x	Erreur au niveau de l'algorithme, voir la description spécifique
401	-	Échec de l'authentification, voir la description spécifique du message
404	-	Chemin dans l'URL saisi incorrect
50x	-	Erreur du programme serveur

Méthodes de résolution en cas d'exception de service :

En cas de limitation QPS : Contactez l'équipe commerciale EasyAR pour une augmentation de la capacité QPS.
En cas d'échec d'authentification : Résolvez selon la description spécifique du message. Les problèmes courants incluent un écart 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 au personnel EasyAR pour résolution.

Problème de feedback

Si le problème persiste après les vérifications ci-dessus, veuillez collecter les informations comme suit et les transmettre à l'équipe d'assistance technique d'EasyAR.

Exporter les informations du service de localisation Mega

Connectez-vous à votre compte dans Mega Studio d'Unity, sélectionnez la bibliothèque de localisation présentant des anomalies, puis localisez le bouton d'exportation du service de localisation Mega comme indiqué dans l'image ci-dessous. Le format du fichier exporté doit être MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. Le service de localisation Mega contient uniquement les informations relatives au block Mega et à la bibliothèque de localisation, sans aucune autre information sensible.

Exporter les informations du service de localisation Mega

Enregistrement des fichiers EIF

Lors de tests sur téléphone mobile et que vous rencontrez des problèmes, veuillez utiliser la Toolbox pour enregistrer un fichier EIF à partir du téléphone

Lors de tests sur lunettes et que vous rencontrez des problèmes, veuillez utiliser la Toolbox pour enregistrer un fichier EIF à partir des lunettes

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

Lors de l'utilisation de Mini Program WeChat, vous pouvez utiliser la méthode pour enregistrer un fichier EIF via Mini Program

Utiliser des appareils tels que téléphones, lunettes, etc. pour enregistrer les phénomènes problématiques

Dans le domaine de la RA, les descriptions textuelles peinent souvent à transmettre des informations précises, et la compréhension de chacun peut varier considérablement. Parallèlement, les enregistrements d'écran lors de l'exécution sont des informations très utiles, vous permettant ainsi qu'au personnel d'EasyAR d'établir une compréhension commune. Vous pouvez utiliser les fonctions intégrées d'appareils comme des téléphones, des lunettes, etc., ou recourir à des logiciels tiers pour effectuer l'enregistrement. Il est important de noter que le processus d'enregistrement d'écran affecte généralement les performances d'exécution, tant l'effet de suivi que les performances peuvent être affectés.

Note

Avant l'enregistrement d'écran, il est recommandé, lors de l'exécution, de se référer à l'échantillon correspondant et d'afficher à l'écran certaines informations de débogage nécessaires. En fournissant l'enregistrement d'écran, vous devez également fournir les données EIF correspondantes à la période de cet enregistrement.

Problèmes de développement unity

Si vous rencontrez des problèmes inhabituels lors de votre développement avec Unity, vous devez vérifier systématiquement si vous avez effectué les 4 vérifications suivantes.

Vous avez essayé la dernière version d’EasyAR Sense Unity Plugin. Les nouvelles versions incluent généralement des corrections de bugs et de nouvelles fonctionnalités. Il est recommandé de d’abord mettre à jour vers la dernière version.
Vous avez lu la documentation de développement d’EasyAR et le guide Mega. La documentation contient généralement des explications sur certaines situations.
Vous avez consulté les journaux système et Unity. Il est conseillé de fournir les journaux complets lors de la question.
Vous avez essayé de reproduire le problème dans un projet Unity vide, ou dans l’exemple (Sample).

Si vous avez effectué ces 4 vérifications et que le problème persiste, vous pouvez suivre la procédure ci-dessous dans EasyAR Sense Unity Plugin pour fournir des informations complètes. Cela permettra aux techniciens d’EasyAR d’analyser et de résoudre votre problème.

Dans Unity -> EasyAR -> Sense, sélectionnez Poser une question
Dans Poser une question, vous devez fournir les informations suivantes :
- Sélectionnez l’environnement d’exécution problématique. Un seul environnement peut être sélectionné.
- Copiez les informations du périphérique. Dans EasyAR Session, définissez DiagnosticsController.DumpSession sur Log. Copiez la sortie d’une trame et collez le résultat ci-dessous.
- Sélectionnez toutes les fonctionnalités EasyAR utilisées lors du problème (sélection multiple possible).
- Confirmez avoir effectué les 4 vérifications ci-dessus. Il est recommandé de décrire comment reproduire le problème dans l’exemple (Sample).
- Cliquez sur la fonction de copie en haut à droite.
  
  Lors de l’ouverture initiale de la fenêtre Poser une question, les informations ci-dessous peuvent être incomplètes. Elles s’afficheront après avoir sélectionné l’environnement et les fonctionnalités.
Cliquez sur Accéder aux questions-réponses EasyAR ci-dessous pour transmettre les informations copiées à EasyAR officiel, ou contactez directement le personnel d’EasyAR.