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 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:

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 una Cloud Anchor

Hosting comienza con una llamada a hostCloudAnchorAsync(). ARCore subirá datos visuales, poses del dispositivo y la pose 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 que se realice la devolución de llamada o revisa el estado Future de forma continua 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. Puede haber hasta 40 operaciones de Cloud Anchor simultáneas 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 una Cloud Anchor 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). De esta forma, el seguimiento tendrá tiempo para estabilizarse.
• Cuando selecciones una ubicación para 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 entrenada en el centro de interés y mueve el dispositivo alrededor de ese centro 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 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 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?

• Crea una app de Cloud Anchors con el codelab de Cloud Anchors de ARCore con Cloud Anchors persistentes.
• Explica cómo 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 descubrir más formas de usar ARCore en tu app.