Leitfaden zur Fehlersuche bei fehlgeschlagener Mega-Lokalisierung

Mega basiert auf fortgeschrittenen visuellen Lokalisierungsalgorithmen, die über die Cloud nach Mega Blocks suchen und über visuelle Merkmalsabgleiche eine hochpräzise Lokalisierung berechnen. In der Praxis können falsche Konfigurationen, Umgebungsänderungen oder Netzwerkschwankungen dazu führen, dass die Lokalisierung fehlschlägt.

Dieses Dokument hilft Ihnen dabei, den Lokalisierungsstatus schnell einzuordnen, zwischen „normalem Warten“ und „anormalem Fehler“ zu unterscheiden und anhand von Konfiguration, Umgebung und Dienst die Ursache zügig einzugrenzen.

Lokalisierungsablauf

Sie müssen im Zielbereich Mapping-Daten erfassen, einen Mega Block erzeugen, den bereits rekonstruierten Mega Block zur Lokalisierungsbibliothek hinzufügen und die Verfügbarkeit der Lokalisierungsbibliothek prüfen.

Innerhalb des vom Mega Block abgedeckten Bereichs, bei gutem Licht, ausreichend Textur und normalem Netzwerk, ist die Lokalisierung normalerweise innerhalb weniger Sekunden erfolgreich. Nach erfolgreicher Lokalisierung werden Position und Pose des aktuellen Geräts im Mega Block zurückgegeben.

Lokalisierungsstatus erkennen

Wenn Sie Mega Toolbox zur Prüfung des Lokalisierungsergebnisses verwenden, können Sie den Status direkt ansehen.
Wenn Sie Unity-Entwickler sind und die Lokalisierung fehlschlägt, können Sie die auf dem Bildschirm zurückgegebenen Details MegaTrackerLocalizationStatus ansehen. Wenn diese Informationen nicht angezeigt werden, aktivieren Sie die Diagnoseinformationen.

Mögliche Werte von MegaTrackerLocalizationStatus:

Constant	Value	Description
UnknownError	0	Unbekannter Fehler
Found	1	Block gefunden
NotFound	2	Kein Block gefunden
RequestTimeout	3	Anfragezeitüberschreitung (mehr als 1 Minute)
RequestIntervalTooLow	4	Anfrageintervall zu kurz
QpsLimitExceeded	5	QPS-Grenze überschritten
WakingUp	6	Dienst wird gerade aufgeweckt
MissingSpotVersionId	7	SpotVersionId fehlt, möglicherweise nicht gesetzt
ApiTokenExpired	8	API-Token abgelaufen

Lösungen für die obigen Ausnahmen:

Anfragezeitüberschreitung: Prüfen und beheben Sie die Netzwerkbedingungen. Falls nötig, können Sie das Anfrage-Timeout MegaRequestTimeParameters.Timeout erhöhen. Eine schlechte Netzsituation wirkt sich jedoch auch auf die Trackingqualität aus, daher sollte das Netzwerk möglichst verbessert werden.
Anfrageintervall zu kurz: Erhöhen Sie das Anfrageintervall.
Verbindungs- oder Übertragungsfehler: Prüfen und beheben Sie die Netzwerkbedingungen.
QPS-Grenze überschritten: Kontaktieren Sie das EasyAR-Business-Team, um die QPS-Kapazität zu erweitern.
Dienst wird gerade aufgeweckt: Das System wird gerade aufgeweckt, bitte warten Sie eine Weile und versuchen Sie es erneut.
SpotVersionId fehlt: Bitte konfigurieren Sie SpotVersionId.
API-Token abgelaufen: Generieren Sie im EasyAR-Administrationsportal ein neues API-Token.

Für UnknownError gibt es meist zwei Fälle:

Verbindungs- oder Übertragungsfehler
Der Dienst hat einen Fehler zurückgegeben

Für UnknownError können Sie die Detailinformationen über MegaLocalizationResponse.ErrorMessage abrufen.

Häufige Fehlerkategorien

Entsprechend dem zurückgegebenen Status und den beobachteten Symptomen lassen sich häufige Probleme in drei Kategorien einteilen: Konfigurationsprobleme, Umgebungsfaktoren und der Dienst selbst.

Konfigurationsprobleme

Solche Probleme treten typischerweise in der Integrationsphase auf und äußern sich dadurch, dass der Dienst überhaupt nicht startet.

Lizenzbezogen

Wenn während Entwicklung oder Test im Protokoll oder auf dem Bildschirm Probleme wie License oder Invalid Key erscheinen, kann die Ursache eine nicht passende AppID/BundleID, eine abgelaufene Lizenz oder ein unpassendes Paket sein. Prüfen Sie Ihre Lizenzeinstellungen anhand der folgenden Tabelle.

Fehler	Lösung
Invalid Key: No matched Bundle ID	Bundle ID und Lizenzschlüssel passen nicht zusammen. Passen Sie einen der beiden Werte an, sodass sie übereinstimmen.
Invalid Key: No matched Package Name	Bundle ID und Lizenzschlüssel passen nicht zusammen. Passen Sie einen der beiden Werte an, sodass sie übereinstimmen.
Invalid Key: License does not apply to current variant	Sie verwenden ein Enterprise-SDK mit einer Nicht-Enterprise-Lizenz oder umgekehrt.
Invalid Key: License for an old version does not apply	Die Lizenzversion ist zu alt. Erstellen Sie bitte eine neue Lizenz.
Invalid Key: Invalid format	Das Lizenzformat ist fehlerhaft, zum Beispiel wurde es nicht vollständig kopiert.
Invalid Key: Server verification failed	Die Lizenz wurde gelöscht oder hat keine Geräteberechtigung. Bei Headset-Nutzung wenden Sie sich bitte an den Vertrieb, um die Berechtigung hinzuzufügen.
License does not apply to eyewear	Die Lizenz kann nicht auf einem Headset verwendet werden. Bitte wechseln Sie zu einer XR-Lizenz.
License is expired	Die Lizenz ist abgelaufen.

Beachten Sie außerdem, dass Trial-Lizenzen bestimmte Einschränkungen haben. Die Verwendung der kostenpflichtigen EasyAR-Sense-Version und des kostenpflichtigen EasyAR-Mega-Dienstes kann dieses Problem lösen. Wenn Sie bereits die kostenpflichtige Version von EasyAR Sense verwenden, können Sie diese Hinweise ignorieren oder aus dem Sample entfernen.

Abnormale Kamerabilder

Wenn während der Entwicklung oder des Tests einer EasyAR-Mega-Anwendung schwarze Bildschirme, Abstürze oder kein Kamerabild auftreten, gehen Sie bitte systematisch wie folgt vor und sammeln Sie Informationen.

Versuchen Sie zunächst, das Problem selbst zu beheben

Wenn Sie mit Unity entwickeln und testen, stellen Sie sicher, dass unter AR Session (EasyAR) -> Inspector der Diagnostics Controller (Script) aktiviert ist.
Prüfen Sie die Inhalte auf dem Bildschirm oder in den Protokollen und achten Sie auf eindeutige Meldungen in der UI.
In den meisten Fällen sind Fehlermeldungen selbsterklärend. Wenn auf dem Bildschirm oder im Protokoll die Ursache bereits genannt wird, beheben Sie das Problem entsprechend. Beispiel: cameraDevice.openWithPreferredType fail (die Kamera muss geprüft werden).
Wenn eine Meldung „nicht unterstützt“ erscheint (z. B. das Gerät unterstützt ARCore oder eine andere Funktion nicht), ist das eine normale Einschränkung und muss nicht weiter untersucht werden.

Wenn Sie das Problem nicht selbst beheben können

Prüfen Sie zunächst anhand der vorhandenen Informationen, ob Sie das Problem selbst lösen können. Wenn nicht, stellen Sie bitte zur schnellen Eingrenzung durch EasyAR detaillierte und reproduzierbare technische Informationen bereit. Beschreiben Sie nicht nur das Symptom „schwarzer Bildschirm“. Folgende Informationen sollten enthalten sein:

Vollständige Protokolle: Unity oder Sense
Bildschirmfoto oder Bildschirmaufnahme: der komplette Bildschirm im Zustand mit schwarzem Bild, Diagnoseinformationen bitte sichtbar mit aufnehmen
Detaillierte Geräteinformationen: Gerätemodell (z. B. iPhone 15, HUAWEI P40), Systemversion (z. B. iOS 17.1, Android 14), EasyAR-Sense-Version, EasyAR-Sense-Unity-Plugin-Version, Unity-Version usw.

Dauerhaftes NotFound außerhalb des Einsatzorts

Entwickler testen im Büro mit einem Simulator oder einer Aufnahme, können aber nie eine Lokalisierung erreichen. Möglicherweise ist MegaLocationInputMode auf Onsite gesetzt, obwohl nicht vor Ort gearbeitet wird. Wählen Sie im Entwicklungsprozess entsprechend dem Mega-Positionsinputmodus den richtigen Modus:

Constant	Value	Description
Onsite	0	Eingabemodus für den Einsatz vor Ort. Positionsdaten werden normalerweise vom Gerät bezogen und an Mega übergeben. Typischerweise wird dies intern von FrameFilter verarbeitet.
Simulator	1	Eingabemodus für die Fernnutzung. Positionsdaten müssen als Vor-Ort-Daten simuliert und über die entsprechenden Schnittstellen an Mega übergeben werden (optional).
FramePlayer	2	Eingabemodus bei Verwendung von `FramePlayer`. Dieser Modus ist schreibgeschützt.

Durch Umgebungsfaktoren verursacht

Solche Probleme zeigen sich darin, dass der Dienst normal läuft, die Lokalisierung aber dauerhaft NotFound zurückgibt.

Dauerhaft NotFound auf weißer Wand oder Boden

Wenn die Kamera auf große weiße Wände, Glasflächen oder einfarbige Böden zeigt, wird dauerhaft NotFound zurückgegeben.

Ursache: Visuelle Lokalisierung benötigt Texturmerkmale. In Bereichen mit schwacher Textur können keine Merkmalsstellen extrahiert werden.

Lösung: Das ist ein normales Verhalten. Bewegen Sie die Kamera in einen Bereich mit reichhaltigerer Textur und starten Sie dort.

Vor Ort, aber texturreicher Bereich und dennoch dauerhaft NotFound

Sie befinden sich vor Ort, zeigen auf einen texturierten Bereich, erhalten aber über längere Zeit keine erfolgreiche Lokalisierung.

Mögliche Ursachen:

Szenenänderung: Die reale Umgebung vor Ort (z. B. Renovierung, neue Poster, starke Lichtänderungen) unterscheidet sich zu stark von der Erfassungssituation.
Erfassungsabdeckung fehlt: Der Standort des Benutzers liegt außerhalb des ursprünglich erfassten Mapping-Bereichs.

Lösung:

Bewegen Sie sich in den bei der Erfassung abgedeckten Routenbereich.
Wenn sich die Szene dauerhaft stark verändert hat, müssen Sie die Karte neu erfassen und den Block aktualisieren.

Durch den Dienst selbst verursacht

Gerade hinzugefügter Block, dauerhaft WakingUp

Unmittelbar nach der Konfiguration der Lokalisierungsbibliothek oder beim Start der Bibliothek wird der Dienststatus als WakingUp oder über längere Zeit NotFound angezeigt. Da Mega einen Cold-Start-Mechanismus besitzt, muss die erste Ladung aus dem kalten Speicher aufgeweckt werden. Halten Sie das Netzwerk stabil und versuchen Sie es nach 10 bis 30 Sekunden erneut.

Dienst gibt einen Fehler zurück

Https status	Status code	Ursache
200	21	QPS-Limit überschritten
200	1040 x	Parameter, Bibliothek oder Kartendaten sind fehlerhaft; siehe die konkrete Meldung
200	4000 x	Fehler auf Algorithmus-Ebene; siehe die konkrete Meldung
401	-	Authentifizierung fehlgeschlagen; siehe die konkrete Meldung
404	-	Der Pfad in der URL ist falsch
50x	-	Serverseitiger Programmfehler

Lösungen bei Dienstfehlern:

Bei QPS-Limit: Kontaktieren Sie das EasyAR-Business-Team, um die QPS-Kapazität zu erweitern.
Bei Authentifizierungsfehlern: Lösen Sie das Problem anhand der konkreten Meldung. Häufige Ursachen sind große Abweichungen der Gerätezeit von der Standardzeit oder fehlende CLS-Berechtigungen des API Keys.
In anderen Fällen: Bitte melden Sie das Problem an das EasyAR-Team.

Fehler melden

Wenn sich das Problem nach den obigen Prüfungen nicht lösen lässt, sammeln Sie bitte die folgenden Informationen und melden Sie sie dem EasyAR-Supportteam.

Informationen zu `Mega Localisation Service` exportieren

Klicken Sie im Editor-Tool des betroffenen Block-Knotens auf die Schaltfläche Diagnosis Info, um die Diagnoseinformationen des Mega Blocks zu exportieren. Die Mega Block Diagnoseinformationen enthalten nur den Mega Block und Informationen zur Lokalisierungsbibliothek, keine anderen sensiblen Daten.

Das exportierte Dateiformat sollte Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json sein.

Melden Sie sich im Mega Studio von Unity mit Ihrem Konto an, wählen Sie die Lokalisierungsbibliothek mit der fehlerhaften Lokalisierung aus und klicken Sie auf die unten gezeigte Schaltfläche Export des Mega Localisation Service. Der Mega Localisation Service enthält nur den Mega Block und Informationen zur Lokalisierungsbibliothek, keine anderen sensiblen Daten.

Mega Service Export

Das exportierte Dateiformat sollte MegaStudio_ServiceInfo_<username>_YY-MM-DD_HH-MM-SS.json sein.

Mega Service Export

Das exportierte Dateiformat sollte Mega_Report_Service_<username>_<appid>_YY-MM-DD_HH-MM-SS.json oder MegaStudio_ServiceInfo_<username>_YY-MM-DD_HH-MM-SS.json sein.

Mega Service Export

Das exportierte Dateiformat sollte Mega_Report_Service_<username>_<appid>_YY-MM-DD_HH-MM-SS.json oder MegaStudio_ServiceInfo_<username>_YY-MM-DD_HH-MM-SS.json sein.

EIF-Datei aufzeichnen

Wenn Sie auf dem Telefon testen und auf Probleme stoßen, verwenden Sie bitte das Toolbox-Tool zum Aufzeichnen einer Telefon-EIF-Datei.

Wenn Sie auf einer Brille testen und Probleme auftreten, verwenden Sie bitte das Toolbox-Tool zum Aufzeichnen einer Brillen-EIF-Datei.

Wenn das Problem in Ihrer eigenen Anwendung auftritt, können Sie in Ihrer Anwendung eine EIF-Datei aufzeichnen.

Bei der Verwendung von WeChat Mini Program können Sie eine EIF-Datei im Mini-Programm aufzeichnen.

Problemverhalten mit Telefon, Brille und anderen Geräten aufzeichnen

Im AR-Bereich ist es oft schwer, ein Problem nur mit Worten präzise zu beschreiben. Gleichzeitig ist eine Laufzeit-Bildschirmaufnahme sehr nützlich, weil sie Ihnen und dem EasyAR-Team ein gemeinsames Verständnis ermöglicht. Sie können die eingebaute Aufnahmefunktion des Geräts oder Drittanbieter-Software verwenden. Beachten Sie dabei, dass die Aufnahme die Laufzeitqualität beeinflussen kann; Trackingqualität und Leistung können darunter leiden.

Anmerkung

Es wird empfohlen, vor der Aufnahme während der Laufzeit die entsprechenden Samples zu verwenden und notwendige Debug-Informationen auf dem Bildschirm anzuzeigen. Reichen Sie bei einer Bildschirmaufnahme bitte auch die dazugehörigen EIF-Daten ein.

Rückmeldung zu Unity-Entwicklungsproblemen

Wenn Sie bei der Unity-Entwicklung auf Probleme stoßen, prüfen Sie bitte einzeln, ob die folgenden vier Punkte erfüllt sind:

Sie haben bereits die neueste Version des EasyAR Sense Unity Plugin ausprobiert. Neue Versionen enthalten normalerweise Bugfixes und neue Funktionen. Ein Update ist der erste empfohlene Schritt.
Sie haben die EasyAR-Dokumentation und den Mega-Leitfaden gelesen. Dort werden viele Situationen bereits beschrieben.
Sie haben die System- und Unity-Protokolle gelesen. Es wird empfohlen, bei einer Anfrage die vollständigen Protokolle bereitzustellen.
Sie haben versucht, das Problem in einem leeren Unity-Projekt im Sample zu reproduzieren.

Wenn Sie diese vier Prüfungen abgeschlossen haben und das Problem weiterhin nicht lösen können, können Sie im EasyAR Sense Unity Plugin nach dem folgenden Ablauf vollständige Informationen bereitstellen, damit das EasyAR-Team Ihr Problem analysieren und lösen kann.

Wählen Sie in Unity -> EasyAR -> Sense Fragen stellen
In Fragen stellen müssen Sie die folgenden Informationen angeben:
- Wählen Sie die Laufzeitumgebung mit dem Problem aus; es kann nur eine Umgebung ausgewählt werden
- Kopieren Sie die Geräteinformationen, setzen Sie in EasyAR Session DiagnosticsController.DumpSession auf Log, kopieren Sie eine Ausgabezeile und tragen Sie sie unten ein
- Wählen Sie alle EasyAR-Funktionen aus, die beim Problem verwendet wurden; Mehrfachauswahl wird unterstützt
- Bestätigen Sie, dass die obigen vier Prüfungen abgeschlossen wurden; es wird empfohlen, zu beschreiben, wie sich das Problem im Sample reproduzieren lässt
- Klicken Sie auf das Kopiersymbol oben rechts Wenn Sie das Fenster Fragen stellen gerade geöffnet haben, werden die Informationen unten nicht vollständig angezeigt. Sie müssen erst die verwendete Umgebung und die Funktionen auswählen.
Klicken Sie auf Zu EasyAR Q&A gehen und senden Sie die kopierten Informationen an den offiziellen EasyAR-Kanal oder direkt an das EasyAR-Team.