Guía para desarrolladores de Cloud Anchors para Android (Kotlin/Java)

Obtén información para usar anclas de Cloud en tus propias apps.

Requisitos previos

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

Si es la primera vez que usas los anclas de Cloud, haz lo siguiente:

• Asegúrate de comprender cómo funcionan las anclas y las anclas de Cloud.
• Lee la guía de inicio rápido de Cloud Anchors para conocer los requisitos del sistema, la configuración y las instrucciones de instalación.

Habilita la API de ARCore

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

Habilita las funciones de ancla de Cloud en la configuración de la sesión

Una vez que se haya habilitado la función de Cloud Anchors en tu app, habilita las funciones de Cloud Anchors en la configuración de la sesión de RA de tu app para que pueda comunicarse con la API de ARCore:

Config config = new Config(session);
config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED);
session.configure(config);

val config = Config(session)
config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED
session.configure(config)

Aloja un Cloud Anchor

El hosting comienza con una llamada a hostCloudAnchorAsync(). ARCore subirá datos visuales, posiciones del dispositivo y la posición de la ancla a la API de ARCore. Luego, la API procesa esta información para construir un mapa de características 3D y, en última instancia, muestra un ID de Cloud Anchor único para la ancla al dispositivo.

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

Tu app debe seguir estos pasos para completar el alojamiento de un ancla de Cloud:

1. Llama a hostCloudAnchorAsync().
2. Espera a la devolución de llamada o verifica continuamente el estado de Future hasta que se complete.
3. Verifica el estado del resultado para determinar si la operación se realizó correctamente o interpreta el código de error si falló.
4. Comparte el ID de Cloud Anchor resultante con otros clientes y úsalo para resolver el Cloud Anchor con resolveCloudAnchorAsync().

Verifica la calidad de la asignación de puntos de referencia

Session.FeatureMapQuality indica la calidad de los puntos del entorno que ARCore ve en los últimos segundos desde una posición de cámara determinada. Por lo general, los Cloud Anchors alojados con funciones de mayor calidad se resuelven con mayor precisión. Usa Session.estimateFeatureMapQualityForHosting() para obtener una estimación de la calidad del mapa de características para una posición de cámara determinada.

Cómo resolver un ancla alojada anteriormente

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

Puedes iniciar resoluciones para varios anclas de Cloud en secuencia. Se pueden realizar hasta 40 operaciones simultáneas de Cloud Anchor a la vez.

Cancela una operación o quita un ancla de Cloud

Llama a cancel() para cancelar una operación pendiente de Cloud Anchor. Llama a detach() para quitar de la app un ancla de Cloud ya resuelta.

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

Usa Anchor.CloudAnchorState para verificar el estado del resultado de la operación de alojamiento o resolución, incluidos los errores.

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:

Prácticas recomendadas para lograr una buena experiencia del usuario

Instruye a los usuarios a hacer lo siguiente para garantizar una buena experiencia en tu app:

• Espera unos segundos después de que comience la sesión antes de intentar alojar un ancla (colocando un objeto, etcétera). Esto le da tiempo al seguimiento para estabilizarse.
• Cuando selecciones una ubicación para alojar el ancla, intenta encontrar un área con características visuales que se puedan distinguir fácilmente entre sí. Para obtener mejores resultados, evita las superficies reflectantes o las que carecen de características visuales, como las paredes blancas sin ningún elemento.

• Mantén la cámara enfocada en el centro de interés y mueve el dispositivo alrededor de él para asignar el entorno desde diferentes ángulos y mantener aproximadamente la misma distancia física mientras lo haces. Esto ayudará a capturar más datos visuales y a 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 las anclas de Cloud.

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 Anchors.
• Las apps compiladas con el SDK de ARCore 1.11.0 o versiones anteriores no pueden alojar ni resolver anclas de Cloud debido a que el SDK usa una API de ARCore anterior y obsoleta.

¿Qué sigue?

• Crea una app de Cloud Anchors con el codelab de Cloud Anchors de ARCore con Cloud Anchors persistentes.
• Obtén información para alojar y resolver anclas de Cloud a través de dos apps de ejemplo en la guía de inicio rápido de anclas de Cloud.
• Administra Cloud Anchors fuera de tu app de ARCore con la API de Cloud Anchors Management.
• Consulta la documentación de referencia de Android para obtener más formas de usar ARCore en tu app.