Guía de resolución de fallos de localización de Mega

Mega se basa en algoritmos avanzados de localización visual y consigue localización de alta precisión mediante la recuperación de Mega Block en la nube y el cálculo por coincidencia de características visuales. Por ello, durante el uso real, errores de configuración, cambios del entorno, fluctuaciones de red y otros factores pueden provocar fallos de localización.

Este documento tiene como objetivo ayudarle a determinar rápidamente el estado de localización, distinguir entre "espera normal" y "error anómalo", y realizar un diagnóstico rápido a partir de tres tipos de factores: configuración, entorno y servicio.

Proceso de localización

Debe recopilar datos de mapeo en el área objetivo y construir Mega Block, añadir el Mega Block reconstruido a la biblioteca de localización y confirmar que la biblioteca de localización está disponible.

En el área cubierta por el Mega Block ya construido, con buena iluminación ambiental, características abundantes y red normal, por lo general la localización puede completarse correctamente en unos segundos. Tras una localización correcta, se devuelve la posición y la pose actuales del dispositivo dentro del Mega Block.

Determinar el estado de localización

• Si usa Mega Toolbox para verificar el resultado de localización, puede ver directamente el estado de localización.

  

• Si es desarrollador Unity y no se puede localizar, puede ver en pantalla la información concreta devuelta por la localización, MegaTrackerLocalizationStatus. Si esta información no aparece en pantalla, debe activar la información de diagnóstico.

  

Valores posibles de MegaTrackerLocalizationStatus

Constant	Value	Description
UnknownError	0	Error desconocido
Found	1	Localizado en el Block
NotFound	2	No se localizó el Block
RequestTimeout	3	Tiempo de espera de solicitud agotado (más de 1 minuto)
RequestIntervalTooLow	4	Intervalo de solicitud demasiado corto
QpsLimitExceeded	5	QPS supera el límite
WakingUp	6	El servicio se está activando
MissingSpotVersionId	7	Falta SpotVersionId; es posible que no se haya configurado
ApiTokenExpired	8	API Token caducado

Soluciones para las anomalías anteriores:

• Tiempo de espera de solicitud agotado: revise y corrija la red. Si es necesario, puede aumentar el tiempo de espera de solicitud MegaRequestTimeParameters.Timeout; sin embargo, una red deficiente también afectará al efecto de seguimiento, por lo que conviene resolver primero el problema de red.
• Intervalo de solicitud demasiado corto: reduzca el intervalo de solicitud.
• Fallo de conexión o transmisión: revise y corrija la red.
• QPS supera el límite: contacte con el equipo comercial de EasyAR para ampliar la capacidad de QPS.
• El servicio se está activando: el sistema se está activando; espere un tiempo y vuelva a intentarlo.
• Falta SpotVersionId: configure SpotVersionId.
• API Token caducado: vuelva a generar el API Token en el panel de administración de EasyAR.

UnknownError suele tener dos causas frecuentes:

• Fallo de conexión o transmisión
• Respuesta anómala del servicio

Para UnknownError, puede obtener información detallada mediante MegaLocalizationResponse.ErrorMessage.

Clasificación y diagnóstico de errores comunes

Según el estado y el fenómeno devueltos por la localización, los problemas comunes pueden dividirse en tres categorías: problemas de configuración, factores del entorno y el propio servicio.

Problemas de configuración

Este tipo de problema suele aparecer durante la fase de integración de desarrollo y se manifiesta como imposibilidad total de iniciar el servicio.

Relacionados con License

Si durante el desarrollo o las pruebas el log o la pantalla muestran problemas como License o Invalid Key, las posibles causas incluyen AppID/BundleID no coincidente, License caducada o plan no compatible. Compare con la siguiente tabla para revisar la configuración de License.

Error	Solución
Invalid Key: No matched Bundle ID	Bundle ID y license key no coinciden; modifique cualquiera de ellos para que coincidan
Invalid Key: No matched Package Name	Bundle ID y license key no coinciden; modifique cualquiera de ellos para que coincidan
Invalid Key: License does not apply to current variant	Se usa el SDK del paquete empresarial con una license key no empresarial, o se usa un SDK no empresarial con una license key empresarial
Invalid Key: License for an old version does not apply	La versión de la license es demasiado antigua; debe crear una nueva license
Invalid Key: Invalid format	El formato de la license es incorrecto; por ejemplo, no se copió completa
Invalid Key: Server verification failed	La license se ha eliminado o no tiene permiso de uso en el dispositivo. Si se usa en visor, contacte con el equipo comercial para añadir permisos
License does not apply to eyewear	La license no puede usarse en visores; cambie a una xr license
License is expired	La license ha caducado

Además, debe tener en cuenta que la License de la versión de prueba tiene algunas limitaciones. Usar la versión de pago de EasyAR Sense y el servicio EasyAR Mega de pago puede resolver este problema. Si ya está usando la versión de pago de EasyAR Sense, puede ignorar o eliminar directamente el texto correspondiente del sample.

Imagen de cámara anómala

Durante el desarrollo o las pruebas de una aplicación EasyAR Mega, si aparecen problemas como pantalla negra, cierre inesperado o ausencia de imagen de cámara, siga estos pasos para diagnosticar sistemáticamente y recopilar información.

1. Intentar resolverlo por su cuenta

• Si usa Unity para desarrollo y pruebas, asegúrese de haber marcado Diagnostics Controller (Script) en AR Session (EasyAR) -> Inspector para activar la información de diagnóstico.

  

• Revise el contenido mostrado en pantalla o en el log, y compruebe si hay un texto claro en la UI.

• En la mayoría de los casos, los mensajes de error se explican por sí mismos. Si la información en pantalla o el log ya indica la causa, puede resolverlo según esa causa. Por ejemplo: cameraDevice.openWithPreferredType fail (debe comprobar si la cámara está disponible).

• Si se indica "no compatible" (por ejemplo, el dispositivo no admite ARCore u otra función), se trata de una limitación normal y no requiere más diagnóstico.

2. No se puede resolver por su cuenta

   Primero intente resolverlo con la información disponible. Si no puede hacerlo, para ayudar al personal de EasyAR a localizar rápidamente el problema, asegúrese de proporcionar información técnica detallada y reproducible; no describa únicamente fenómenos como "pantalla negra". Se recomienda incluir:

• Log completo: Unity o Sense
• Captura de pantalla o grabación: pantalla completa durante la pantalla negra. Si hay información de diagnóstico, asegúrese de que sea visible y haga una captura.
• Información detallada del dispositivo: modelo del dispositivo (por ejemplo, iPhone 15, HUAWEi P40), versión del sistema (por ejemplo, iOS 17.1, Android 14), versión de EasyAR Sense, versión de EasyAR Sense Unity Plugin, versión de Unity, etc.

No se ejecuta en sitio y permanece en NotFound

El desarrollador prueba en la oficina con simulador o grabación de pantalla, pero nunca consigue localizar. Una posible causa es que el modo MegaLocationInputMode esté configurado como Onsite, aunque no se esté ejecutando en sitio. Debe elegir el modo correcto durante el desarrollo según el modo de entrada de posición de Mega:

Constant	Value	Description
Onsite	0	Modo de entrada para uso en sitio; los datos de posición suelen obtenerse del dispositivo e introducirse en Mega, normalmente gestionados internamente por FrameFilter
Simulator	1	Modo de entrada para uso remoto; los datos de posición deben simularse como datos de sitio e introducirse en Mega mediante la interfaz correspondiente (opcional)
FramePlayer	2	Modo de entrada al usar FramePlayer. Este modo es de solo lectura

Causado por factores del entorno

Este tipo de problema se manifiesta como servicio normal, pero la localización devuelve NotFound continuamente.

Apuntar a una pared blanca o al suelo y permanecer en NotFound

Cuando la imagen de cámara contiene grandes áreas de pared blanca, vidrio o suelo de color uniforme, el estado devolverá NotFound continuamente.

Causa: la localización visual depende de características de textura. En áreas con textura débil no se pueden extraer puntos de características.

Solución: es un fenómeno normal. Debe mover la cámara hacia un área con texturas abundantes para iniciar.

En sitio y con texturas abundantes, pero permanece en NotFound

La persona está en sitio y apunta a un área con textura, pero durante mucho tiempo no consigue localizar correctamente.

Posibles causas:

• Cambio de escena: el entorno del sitio (como reformas, cambio de carteles o cambios drásticos de iluminación) difiere demasiado de la escena en el momento del mapeo.
• Captura no cubierta: la posición donde está el usuario supera el rango cubierto por la captura y el mapeo originales.

Soluciones:

• Muévase al área de la ruta capturada originalmente e inténtelo.
• Si la escena ha sufrido cambios permanentes importantes, debe recopilar datos de nuevo y actualizar el Block.

Causado por el propio servicio

Block recién añadido y WakingUp continuo

Al configurar una biblioteca de localización o iniciar una biblioteca de localización, el estado del servicio muestra WakingUp o NotFound durante mucho tiempo. Esto ocurre porque el servicio Mega tiene un mecanismo de arranque en frío y necesita activarse desde almacenamiento frío en la primera carga. Mantenga la red estable, espere de 10 a 30 segundos y vuelva a intentarlo.

Respuesta anómala del servicio

Https status	Status code	Causa
200	21	QPS supera el límite
200	1040 x	Parámetros, biblioteca o datos de mapa incorrectos; consulte la descripción concreta del mensaje
200	4000 x	Error a nivel de algoritmo; consulte la descripción concreta
401	-	Autenticación fallida; consulte la descripción concreta del mensaje
404	-	La ruta en la URL es incorrecta
50x	-	Error del programa del servidor

Soluciones para anomalías del servicio:

• Si aparece límite de QPS: contacte con el equipo comercial de EasyAR para ampliar la capacidad de QPS.
• Si aparece fallo de autenticación: resuélvalo según la descripción concreta del mensaje. Los problemas frecuentes incluyen una desviación excesiva entre la hora del dispositivo y la hora estándar, o una API Key sin permiso CLS.
• Otros casos: informe al personal de EasyAR para resolverlo.

Comunicación de problemas

Si después del diagnóstico anterior el problema sigue sin resolverse, recopile información y envíela al equipo de soporte técnico de EasyAR siguiendo estos pasos.

Exportar información de Mega 定位服务

• Desarrollo Unity, versión de plugin >= 4003
• Desarrollo Unity, versión de plugin 4.7 - 4002
• Desarrollo de miniprogramas
• Otros escenarios de uso de Mega Studio

En la herramienta de editor del nodo block que utiliza, haga clic en el botón Diagnosis Info de la imagen siguiente para exportar la información de diagnóstico de Mega Block. La Mega Block 诊断信息 solo contiene información de Mega Block y de la biblioteca de localización, sin otra información sensible.

El formato del archivo exportado debe ser Mega_Report_Block_<blockID>_YY-MM-DD_HH-MM-SS.json.

Grabar archivo EIF

Si encuentra problemas durante las pruebas con teléfono móvil, use Toolbox para grabar archivos EIF de teléfono móvil.

Si encuentra problemas durante las pruebas con visor, use Toolbox para grabar archivos EIF de visor.

Si encuentra problemas en su propia aplicación, puede usar su aplicación para grabar archivos EIF.

Al usar miniprogramas de WeChat, puede usar miniprograma para grabar archivos EIF.

Grabar el fenómeno del problema con teléfono móvil, visor u otros dispositivos

En el campo de AR, las descripciones textuales suelen ser difíciles de transmitir con precisión y la interpretación de cada persona puede diferir mucho. Al mismo tiempo, la grabación de pantalla durante la ejecución es información muy útil y permite que usted y el personal de EasyAR tengan una comprensión común. Puede grabar con funciones integradas de teléfonos, visores u otros dispositivos, o con software de terceros. Tenga en cuenta que durante la grabación de pantalla normalmente se afecta el efecto de ejecución, y tanto el seguimiento como el rendimiento pueden verse influidos.

Nota

Antes de grabar la pantalla, se recomienda mostrar en pantalla durante la ejecución cierta información de Debug necesaria según el Sample correspondiente. Al proporcionar la grabación de pantalla, también debe proporcionar los datos EIF correspondientes al periodo grabado.

Comunicación de problemas de desarrollo Unity

Si durante el desarrollo con Unity encuentra algún problema anómalo, debe comprobar uno por uno si ha completado las siguientes 4 comprobaciones.

1. Ya ha probado la versión más reciente de EasyAR Sense Unity Plugin. Las nuevas versiones suelen incluir correcciones de bug y nuevas funciones, por lo que se recomienda actualizar primero a la versión más reciente.
2. Ya ha leído la documentación de desarrollo de EasyAR y la guía de Mega, donde normalmente se explican algunas situaciones.
3. Ya ha leído los logs del sistema y de Unity. Se recomienda proporcionar el log completo al hacer una pregunta.
4. Ya ha intentado reproducir el problema en un proyecto Unity vacío, dentro del Sample.

Si ya ha completado estas 4 comprobaciones y aun así no puede resolver el problema, puede proporcionar información completa en EasyAR Sense Unity Plugin siguiendo el flujo siguiente para que el personal técnico de EasyAR la analice y resuelva.

1. En Unity -> EasyAR -> Sense, seleccione 提问.

   

2. En 提问, debe proporcionar la siguiente información:

   • Seleccione el entorno de ejecución donde aparece el problema; solo se admite seleccionar un único entorno.
   • Copie la información del dispositivo. En EasyAR Session, establezca DiagnosticsController.DumpSession en Log, copie la salida de un frame y rellene el resultado abajo.
   • Seleccione todas las funciones de EasyAR que estaba usando cuando apareció el problema; se admite selección múltiple.
   • Confirme que ya ha completado las 4 comprobaciones anteriores. Se recomienda describir cómo reproducir el problema en el Sample al hacer la pregunta.
   • Haga clic en la función de copia de la esquina superior derecha. Al abrir la ventana 提问, la información inferior no se muestra completa; debe seleccionar el entorno y las funciones usadas para que se muestre.

3. Haga clic abajo en 前往 EasyAR 问答 para enviar la información copiada a EasyAR oficial, o envíela directamente al personal de EasyAR.