Guía de solución de problemas de localización de Mega

Mega se basa en algoritmos avanzados de localización visual, logrando una localización de alta precisión mediante la recuperación de Mega Block en la nube y el cálculo de la correspondencia de características visuales. Por lo tanto, durante el uso real, diversos factores como errores de configuración, cambios ambientales o fluctuaciones de la red pueden provocar fallos de localización.

Este documento tiene como objetivo ayudarle a determinar rápidamente el estado de la localización, distinguir entre "espera normal" y "error anómalo", y realizar un diagnóstico rápido basado en tres categorías principales: configuración, entorno y servicio.

Proceso de localización

Necesita recopilar datos de cartografía en el área objetivo y construir un Mega Block, agregar el Mega Block ya reconstruido a la biblioteca de localización y verificar que la biblioteca de localización sea utilizable.

En áreas cubiertas por Mega Blocks ya construidos, con buena iluminación ambiental, características abundantes y red estable, la localización generalmente se completa en segundos. Tras una localización exitosa, se devuelve la posición y orientación actuales del dispositivo dentro del Mega Block.

Determinar el estado de localización

• Si utiliza Mega Toolbox para verificar los resultados de localización, puede consultar directamente el estado de localización

  

• Si es desarrollador de Unity y experimenta fallos de localización, puede ver en pantalla la información específica devuelta MegaTrackerLocalizationStatus. Si no aparece esta información, debe activar la información de diagnóstico.

  

Posibles valores de MegaTrackerLocalizationStatus

Constante	Valor	Descripción
UnknownError	0	Error desconocido
Found	1	Localizado en Block
NotFound	2	No se localizó en Block
RequestTimeout	3	Tiempo de espera de solicitud excedido (más de 1 minuto)
RequestIntervalTooLow	4	Intervalo de solicitud demasiado corto
QpsLimitExceeded	5	Excede el límite de QPS
WakingUp	6	Servicio en proceso de despertar
MissingSpotVersionId	7	Falta SpotVersionId, posiblemente no configurado
ApiTokenExpired	8	Token de API caducado

Soluciones para las excepciones anteriores:

• Tiempo de espera de solicitud: Verifique y repare la red. Si es necesario, aumente el tiempo de espera MegaRequestTimeParameters.Timeout, pero una red deficiente afectará el seguimiento. Resuelva los problemas de red.
• Intervalo de solicitud demasiado corto: Reduzca la frecuencia de solicitudes.
• Error de conexión o transmisión: Verifique y repare la red.
• Excede el límite de QPS: Contacte al equipo comercial de EasyAR para ampliar la capacidad de QPS.
• Servicio en proceso de despertar: El sistema se está iniciando. Espere un momento y reintente.
• Falta SpotVersionId: Configure el SpotVersionId.
• Token de API caducado: Regenere el token de API en el panel de EasyAR.

UnknownError comúnmente tiene dos causas:

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

Para UnknownError, consulte detalles a través de MegaLocalizationResponse.ErrorMessage.

Clasificación y solución de errores comunes

Según el estado y los fenómenos devueltos por la ubicación, los problemas comunes se pueden clasificar en las siguientes tres categorías: problemas de configuración, factores ambientales, servicio mismo.

Problemas de configuración

Este tipo de problemas suele ocurrir en la fase de desarrollo de integración, manifestándose como un servicio que no se inicia en absoluto.

Licencia relacionada

Si durante el desarrollo o las pruebas encuentra mensajes en los registros o en pantalla como License, Invalid Key u otros problemas similares, las posibles causas incluyen: AppID/BundleID no coincidente, licencia caducada, plan no correspondiente, etc. Revise la configuración de su licencia según la siguiente tabla.

Error	Solución
Invalid Key: No matched Bundle ID	El Bundle ID no coincide con la clave de licencia. Modifique cualquiera de los dos para que coincidan
Invalid Key: No matched Package Name	El Bundle ID no coincide con la clave de licencia. Modifique cualquiera de los dos para que coincidan
Invalid Key: License does not apply to current variant	Se utilizó el SDK del paquete empresarial con una clave de licencia no empresarial, o viceversa
Invalid Key: License for an old version does not apply	La versión de la licencia es demasiado antigua. Cree una nueva licencia
Invalid Key: Invalid format	Formato de licencia incorrecto, por ejemplo, no se copió completa
Invalid Key: Server verification failed	La licencia fue eliminada o no tiene permisos de uso en dispositivos. Si es para gafas de realidad virtual, contacte al departamento comercial para agregar permisos
License does not apply to eyewear	La licencia no puede usarse en gafas de realidad virtual. Cambie a una licencia xr
License is expired	La licencia ha caducado

Además, debe tener en cuenta que las licencias de versión de prueba tienen ciertas limitaciones. El uso de EasyAR Sense en su versión de pago y los servicios de pago de EasyAR Mega pueden resolver este problema. Si ya está utilizando la versión de pago de EasyAR Sense, puede ignorar o eliminar directamente el texto relevante de la muestra.

Problemas con la imagen de la cámara

Durante el desarrollo o las pruebas de una aplicación EasyAR Mega, si experimenta problemas como pantalla negra, cierres inesperados, ausencia de imagen de la cámara u otras anomalías, siga sistemáticamente estos pasos para investigar y recopilar información.

1. Intente resolverlo usted mismo

• Si está desarrollando o probando con Unity, asegúrese de haber marcado Diagnostics Controller (Script) en AR Session (EasyAR) -> Inspector para habilitar la información de diagnóstico.
• Revise el contenido mostrado en pantalla o en los registros (logs), comprobando si hay mensajes de texto explícitos en la UI.
• En la mayoría de los casos, los mensajes de error son autoexplicativos. Si la información en pantalla o en los registros ya indica la causa del problema, puede solucionarlo en función de la causa específica. Por ejemplo: cameraDevice.openWithPreferredType fail (necesita verificar si la cámara está disponible).
• Si aparece un mensaje de "no compatible" (por ejemplo, dispositivo no compatible con ARCore u otra característica), se trata de una limitación normal; no requiere mayor investigación.

2. Si no puede resolverlo usted mismo

   Por favor, intente resolverlo primero con la información disponible. Si no puede resolverlo usted mismo, para ayudar al personal de EasyAR a localizar rápidamente el problema, proporcione información técnica detallada y reproducible. Evite describir solo el fenómeno, como "pantalla negra". Se recomienda incluir en la retroalimentación:

• Registros (logs) completos: Unity o Sense.
• Captura de pantalla o grabación de video: La pantalla completa durante la pantalla negra. Si hay información de diagnóstico visible, asegúrese de capturarla.
• Información detallada del dispositivo: Modelo del dispositivo (p. ej., iPhone 15, HUAWEI P40), versión del sistema operativo (p. ej., 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 in situ, continua NotFound

Los desarrolladores utilizan simuladores o grabaciones de pantalla para pruebas en la oficina, pero no logran identificar la causa. La posible razón es que el modo MegaLocationInputMode esté configurado como Onsite, pero la ejecución no se realiza in situ. Es necesario seleccionar el modo correcto durante el desarrollo según el modo de entrada de ubicación Mega:

Constante	Valor	Descripción
Onsite	0	Modo de entrada para uso in situ. Los datos de ubicación normalmente se obtienen del dispositivo y se ingresan en Mega, generalmente procesados internamente por FrameFilter
Simulator	1	Modo de entrada para uso remoto. Los datos de ubicación deben simularse como datos in situ e ingresarse en Mega a través de la interfaz correspondiente (opcional)
FramePlayer	2	Modo de entrada al usar FramePlayer. Este modo es de solo lectura

Causado por factores ambientales

Este tipo de problema se manifiesta como un servicio que funciona normalmente, pero la localización devuelve continuamente NotFound.

Persistente NotFound en paredes blancas grandes, suelo

Cuando la imagen de la cámara muestra grandes áreas de paredes blancas, vidrio o suelo liso, el estado devuelve continuamente NotFound.

Causa: El posicionamiento visual depende de características de textura. Las áreas con textura débil no pueden extraer puntos característicos.

Solución: Esto es normal. Es necesario mover la cámara hacia un área con textura rica para iniciar.

En el sitio y rica en textura, pero continua notfound

La persona está en el sitio, frente a un área con textura, pero no logra localizarse después de un tiempo prolongado.

Causas posibles:

• Cambios en la escena: El entorno actual (como renovaciones, cambio de carteles, variaciones drásticas de iluminación) difiere significativamente de la escena durante el mapeo.
• Área no cubierta: La posición donde está parado el usuario excede el área cubierta durante la captura inicial para el mapeo.

Soluciones:

• Muévase a las áreas de la ruta originalmente capturada e intente nuevamente.
• Si la escena ha sufrido cambios permanentes y significativos, será necesario volver a capturar y actualizar el Block.

Causado por el servicio mismo

Recién añadido Block, estado WakingUp persistente

Cuando acabas de configurar la biblioteca de ubicación o la acabas de iniciar, el estado del servicio muestra WakingUp o NotFound durante un período prolongado. Esto se debe a que el servicio Mega tiene un mecanismo de arranque en frío. La primera carga requiere despertarlo desde el almacenamiento frío. Mantén la red funcionando sin problemas, espera de 10~30 segundos y vuelve a intentarlo.

Servicio devuelve excepción

Estado Https	Código de estado	Razón
200	21	QPS excede el límite
200	1040x	Parámetro, base o datos de mapa incorrectos, ver descripción específica del mensaje
200	4000x	Error a nivel de algoritmo, ver descripción específica
401	-	Autenticación fallida, ver descripción específica del mensaje
404	-	Ruta en la URL ingresada incorrecta
50x	-	Error del programa del servidor

Método de solución para excepciones de servicio:

• Si aparece límite de QPS: contactar al compañero de negocios de EasyAR para la expansión de QPS
• Si falla la autenticación: resolver según la descripción específica del mensaje, problemas comunes incluyen desviación excesiva de la hora del dispositivo respecto a la hora estándar, falta de permisos CLS para la API Key, etc.
• Otros casos: por favor, informar al personal de EasyAR para su solución

Reporte de problemas

Si el problema persiste después de seguir los pasos anteriores, por favor, siga los siguientes pasos para recopilar información y proporcionársela al equipo de soporte técnico de EasyAR.

Exportar información de servicio de localización Mega

Inicie sesión en su cuenta en Mega Studio de Unity, seleccione la biblioteca de localización con anomalías y busque el botón de exportación del servicio de localización Mega que se muestra en la imagen a continuación. El formato del archivo que exporte debe ser MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json. El servicio de localización Mega solo incluye información de Mega Block y de la biblioteca de localización, sin contener otra información confidencial.

Grabar archivos EIF

Si encuentra problemas al realizar pruebas en un teléfono móvil, utilice Toolbox para grabar archivos EIF del teléfono móvil

Si encuentra problemas al realizar pruebas con gafas, utilice Toolbox para grabar archivos EIF de las gafas

Si encuentra problemas en su propia aplicación, puede grabar archivos EIF usando su aplicación

Al usar mini-programas de WeChat, puede grabar archivos EIF con el mini-programa

Grabar problemas usando dispositivos como teléfonos móviles o gafas

En el campo de la realidad aumentada (AR), la descripción textual suele ser incapaz de transmitir información precisa, y la interpretación de cada persona puede variar enormemente. Al mismo tiempo, una grabación de pantalla durante la ejecución es información extremadamente útil, ya que permite establecer un entendimiento común entre usted y el personal de EasyAR. Puede utilizar las funciones integradas de dispositivos como teléfonos móviles o gafas, o recurrir a software de terceros para realizar la grabación. Es importante tener en cuenta que el proceso de grabación de pantalla generalmente afecta el rendimiento en tiempo de ejecución; tanto la eficacia del seguimiento como el rendimiento podrían verse afectados.

Nota

Antes de grabar la pantalla, se recomienda mostrar en la pantalla información de depuración (debug) necesaria durante la ejecución, haciendo referencia a la muestra (Sample) correspondiente. Junto con la grabación de pantalla proporcionada, también debe proporcionar los datos EIF correspondientes durante el período de grabación.

Problemas de desarrollo de unity

Si encuentra problemas inusuales al desarrollar con Unity, debe verificar paso a paso si ha completado las siguientes 4 comprobaciones.

1. Ya ha probado la última versión de EasyAR Sense Unity Plugin. Las nuevas versiones suelen incluir correcciones de errores y nuevas funciones. Se recomienda actualizar primero a la última versión.
2. Ya ha leído la documentación de desarrollo de EasyAR y la guía de Mega. La documentación suele contener explicaciones para diversas situaciones.
3. Ya ha revisado los registros del sistema y de Unity. Se recomienda proporcionar registros completos al plantear preguntas.
4. Ya ha intentado reproducir el problema en un proyecto vacío de Unity o dentro de las muestras (Sample).

Si después de completar estas 4 comprobaciones aún no puede resolver su problema, puede proporcionar información completa en EasyAR Sense Unity Plugin siguiendo el siguiente proceso para que el equipo técnico de EasyAR lo analice y solucione.

1. En Unity -> EasyAR -> Sense, seleccione Preguntar

   

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

   • Seleccione el entorno de ejecución problemático. Solo se admite seleccionar un entorno.
   • Copie la información del dispositivo. En EasyAR Session, establezca DiagnosticsController.DumpSession en Log. Copie la salida de un fotograma y pegue el resultado a continuación.
     
   • Seleccione todas las funciones de EasyAR que utilizó cuando surgió el problema. Se admite selección múltiple.
   • Confirme que ha completado las 4 comprobaciones anteriores. Se recomienda describir cómo reproducir el problema en las muestras (Sample) al preguntar.
   • Haga clic en el botón Copiar en la esquina superior derecha.
     
     Al abrir la ventana Preguntar, la información inferior puede no mostrarse completamente. Deberá seleccionar el entorno y las funciones utilizadas para que se muestre.
     

3. Haga clic en Ir a preguntas y respuestas de EasyAR para enviar la información copiada al equipo oficial de EasyAR, o comuníquese directamente con el personal de EasyAR.