Guía para desarrolladores de Cloud Anchors en el NDK de Android (C)

Aprende a usar Cloud Anchors en tus propias apps.

Requisitos previos

Asegúrate de comprender los conceptos fundamentales de RA y cómo configurar una sesión de ARCore antes de continuar.

Si es la primera vez que usas Cloud Anchors, asegúrate de comprender cómo funcionan las anclas y las Cloud Anchors.

Habilita la API de ARCore

Antes de usar Cloud Anchors en tu app, primero debes habilitar la API de ARCore en la aplicación.

Habilita las capacidades de Cloud Anchor en la configuración de la sesión

Una vez que se habilite la funcionalidad de Cloud Anchors en tu app, habilita sus capacidades en la configuración de sesiones de RA de la app para que pueda comunicarse con la API de ARCore:

// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);

// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);

// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
                            AR_CLOUD_ANCHOR_MODE_ENABLED);

// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);

Aloja una Cloud Anchor

Hosting comienza con una llamada a ArSession_hostCloudAnchorAsync(). ARCore subirá datos visuales, poses de dispositivos y posiciones de anclas a la API de ARCore. Luego, la API procesa esta información para construir un mapa de atributos 3D y, en última instancia, mostrará un ID de Cloud Anchor único para el ancla en el dispositivo.

También puedes extender la vida útil de una ancla alojada con la API de Cloud Anchor Management de ARCore.

Tu app debe seguir estos pasos para completar el hosting de una Cloud Anchor:

  1. Llama a ArSession_hostCloudAnchorAsync().
  2. Espera la devolución de llamada o verifica continuamente el estado Future hasta que termines.
  3. Cómo verificar el estado del resultado para determinar si la operación se realizó correctamente o interpretar el código de error si falló.
  4. Compartir el ID de Cloud Anchor resultante con otros clientes y usarlo para resolver el problema con Cloud Anchor ArSession_resolveCloudAnchorAsync()

Comprobar la calidad de la asignación de los puntos del atributo

ArFeatureMapQuality indica la calidad de los puntos del componente que ARCore detectó en los segundos anteriores desde una pose de cámara determinada. Por lo general, las Cloud Anchors alojadas con funciones de mayor calidad se resuelven con mayor precisión. Usa ArSession_estimateFeatureMapQualityForHosting() para obtener una estimación de la calidad del mapa de atributos para una postura de cámara determinada.

Valor Descripción
INSUFFICIENT La calidad de los puntos de características identificados a partir de la pose en los segundos anteriores es baja. Este estado indica que es probable que ARCore tenga más dificultades para resolver Cloud Anchor. Alienta al usuario a mover el dispositivo para que la posición deseada de Cloud Anchor que desee alojar se pueda ver desde diferentes ángulos.
SUFFICIENT Es probable que la calidad de los puntos de atributos identificados a partir de la pose en los segundos anteriores sea suficiente para que ARCore resuelva correctamente una Cloud Anchor, aunque es probable que se reduzca la precisión de la postura resuelta. Alienta al usuario a mover el dispositivo para que la posición deseada de Cloud Anchor que desee alojar se pueda ver desde diferentes ángulos.
GOOD La calidad de los puntos de atributos identificados a partir de la pose en los segundos anteriores probablemente sea suficiente para que ARCore resuelva correctamente una Cloud Anchor con un alto grado de precisión.

Resolver un ancla alojada previamente

Llama a ArSession_resolveCloudAnchorAsync() para resolver una Cloud Anchor alojada. La API de ARCore compara periódicamente las características visuales de la escena con el mapa de atributos 3D del ancla para determinar la posición y la orientación del usuario en relación con el ancla. Cuando encuentra una coincidencia, la API muestra la pose del Cloud Anchor alojado.

Puedes iniciar soluciones para múltiples Cloud Anchors en secuencia. Puede haber hasta 40 operaciones de Cloud Anchor simultáneas a la vez.

Cancela una operación o quita una Cloud Anchor

Llama a ArFuture_cancel() para cancelar una operación pendiente de Cloud Anchor. Llama a ArAnchor_detach() para detener el seguimiento y olvidar una Cloud Anchor que ya esté resuelta. Las referencias al ancla se deben liberar por separado llamando a ArAnchor_release().

Verifica el estado del resultado de una operación de Cloud Anchor

Usa ArCloudAnchorState para verificar el estado del resultado de la operación de hosting o resolución, incluidos los errores.

Valor Descripción
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND No se pudo resolver porque la API de ARCore no pudo encontrar el ID de Cloud Anchor proporcionado.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED El hosting falló porque el servidor no pudo procesar correctamente el conjunto de datos para el ancla en cuestión. Vuelve a intentarlo cuando el dispositivo haya recopilado más datos del entorno.
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE No se pudo acceder a la API de ARCore. Esto puede suceder por varios motivos. Es posible que el dispositivo esté en modo de avión o que no tenga una conexión a Internet que funcione. Es posible que se haya agotado el tiempo de espera de la solicitud enviada al servidor sin respuesta. Es posible que haya una mala conexión de red, falta de disponibilidad de DNS, problemas de firewall o cualquier otro problema que pueda afectar la capacidad del dispositivo para conectarse a la API de ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL Una tarea de hosting o resolución para esta ancla finalizó con un error interno. La app no debería intentar recuperarse de este error.
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED Consulta Soluciona problemas con la autorización de la API de ARCore.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW No se pudo resolver Cloud Anchor porque la versión del SDK que se usó para resolver el ancla es más reciente que la versión que se usó para alojarla y no es compatible con ella.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD No se pudo resolver Cloud Anchor porque la versión del SDK que se usó para resolver el ancla es antigua y no es compatible con la versión que se usó para alojarla.
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED La aplicación agotó la cuota de solicitudes asignada al proyecto de Google Cloud determinado. Debes solicitar una cuota adicional para la API de ARCore para tu proyecto en Google Developers Console.
AR_CLOUD_ANCHOR_STATE_SUCCESS Se completó correctamente una tarea de hosting o de resolución para esta ancla.

Cuotas de API para solicitudes de host y resolución

La API de ARCore tiene las siguientes cuotas para el ancho de banda de solicitudes:

Tipo de cuota Máximo Duración Se aplica a
Cantidad de anclas ilimitados N/A proyecto
Solicitudes host ancla 30 minuto Dirección IP y proyecto
Solicitudes resolve ancla 300 minuto Dirección IP y proyecto

Prácticas recomendadas para una buena experiencia del usuario

Indícales a los usuarios que hagan lo siguiente para garantizar una buena experiencia en tu app:

  • Espera unos segundos después de que comience la sesión para intentar alojar un ancla (colocando un objeto, etcétera) De esta forma, el seguimiento tendrá tiempo para estabilizarse.
  • Cuando selecciones una ubicación donde alojar al ancla, intenta encontrar un área con características visuales que se distingan fácilmente entre sí. Para obtener mejores resultados, evita las superficies reflectantes o las que no tengan características visuales, como paredes blancas en blanco.

  • Mantén la cámara colocada en el centro de interés y mueve el dispositivo. centro de interés para mapear el entorno desde diferentes ángulos y mantener más o menos la misma distancia física. Esto ayudará a capturar más datos visuales y hará que la resolución sea más sólida.

  • Asegúrate de que haya suficiente iluminación en el entorno real mientras alojas y resuelves Cloud Anchors.

Política de baja

  • Las apps compiladas con el SDK de ARCore 1.12.0 o versiones posteriores están cubiertas por la política de baja de la API de Cloud Anchor.
  • Las apps compiladas con el SDK 1.11.0 o versiones anteriores de ARCore no pueden alojar ni resolver Cloud Anclas debido a que el SDK usa una API de ARCore antigua y obsoleta.

¿Qué sigue?