El Creador de Geospatial de ARCore para Unity te permite obtener una vista previa del contenido de Geospatial en el editor de Unity mostrando los datos de Google Maps en un nuevo formato de mosaicos 3D. Esto te ayuda a visualizar dónde se colocará el contenido en el mundo real mientras compilas tu app.
El Creador de Geospatial está disponible como parte de las extensiones de ARCore para AR Foundation. En esta guía de inicio rápido, se muestra cómo usar el Creador de Geospatial en Unity para agregar contenido de RA geoespacial a la app de ejemplo de ARCore Geospatial.
Si tienes una app existente que te gustaría usar en lugar de la muestra de Geospatial, primero deberás seguir nuestra Guía para desarrolladores de Geospatial para Unity. Después de configurar tu app para usar la API de Geospatial, salta al paso Agrega las dependencias requeridas que se encuentra más abajo y continúa desde allí.
Requisitos previos
Sigue "Comienza a usar las extensiones de ARCore para AR Foundation" para configurar tu entorno de Unity y crear experiencias de RA.
Si bien las extensiones de ARCore admiten versiones anteriores de Unity, el Creador de Geospatial requiere Unity 2021.3 o una versión posterior.
Autorización mediante la API
Deberás configurar el acceso a la API para usar la API de ARCore Geospatial y la API de Google Map Tiles.
API de Map Tiles de Google Maps
La API de Map Tiles proporciona una representación fotorrealista en 3D de las ubicaciones admitidas. Usaremos estos mosaicos en el editor de Unity para obtener una vista previa del área alrededor de tu escena de RA.
Consulta la página de la API de Map Tiles para habilitar la API y obtener más información sobre Map Tiles.
API de ARCore Geospatial
Tu app usa la API de ARCore Geospatial en el tiempo de ejecución para crear anclajes geospatiales y, luego, interactuar con ellos.
Para habilitar las APIs de Geospatial, configura la API de ARCore en tu aplicación. Puedes usar los métodos de autorización sin clave (recomendado) o con clave de API.
Extiende la app de ejemplo de Geospatial
En esta guía, te mostraremos cómo usar el Creador de Geospatial para agregar contenido geoespacial a la app de ejemplo de ARCore Geospatial.
Configura la muestra de Geospatial
Primero, familiarízate con la app de ejemplo de Geospatial de ARCore. En un proyecto nuevo de Unity, abre Unity Package Manager y selecciona el paquete de ARCore Extensions. En el panel de detalles del Administrador de paquetes, expande Samples y, luego, importa la muestra de Geospatial a tu proyecto de Unity.
Antes de ejecutar la app, debes habilitar la funcionalidad de ARCore y Geospatial en tu proyecto. Usa Edit > Project Settings…. > XR Plug-in Management. Marca las casillas correspondientes para habilitar el proveedor del complemento de ARCore para Android o el proveedor del complemento de ARKit para iOS.
Luego, en Edit > Project Settings… > XR Plug-in Management, abre el panel ARCore Extensions. Asegúrate de que la opción "Geospatial" esté marcada (no es necesario que habilites Geospatial Creator todavía) y, luego, ingresa tus credenciales de la API. Consulta la documentación "Habilita la API de Geospatial de Unity" para Android y iOS para obtener más detalles.
Hay algunos otros parámetros de configuración del reproductor específicos de la plataforma que se requieren para cualquier app de Unity que use ARCore. Consulta la sección Configura los parámetros del reproductor de nuestra documentación para conocer los cambios necesarios.
En este punto, no hay ningún objeto del juego en tu escena, excepto los que se requieren para ejecutar la muestra geoespacial. Este es un buen momento para compilar y ejecutar la app. Si se configuró correctamente, en el tiempo de ejecución, la app mostrará la vista de la cámara del dispositivo. A medida que te muevas, la precisión geoespacial que se muestra en la parte superior de la pantalla comenzará a mejorar. Si presionas la pantalla, crearás anclajes geoespaciales que persistirán en su ubicación original mientras te mueves.
A continuación, te mostraremos cómo usar el Creador de Geospatial para crear y visualizar contenido de RA sofisticado desde el editor de Unity. Este contenido aparecerá en tu app en ubicaciones específicas de latitud y longitud en el mundo.
Agrega las dependencias necesarias
El Creador de Geospatial usa un paquete de Unity de terceros llamado Cesium para renderizar las Google Map Tiles en la ventana Scene del editor de Unity. Antes de habilitar las funciones de Geospatial Creator, agreguemos el paquete de Cesium a tu proyecto.
Te recomendamos que instales la versión más reciente del paquete Cesium for Unity desde la página de GitHub de Cesium:
- Descarga la versión más reciente del
.tgzprecompilado de Cesium para Unity desde su página de versiones de GitHub. La versión recomendada actual del paquete Cesium for Unity es la 1.1.0. - Abre Unity Package Manager haciendo clic en el menú "Window" de Unity y, luego, selecciona "Package Manager".
- Haz clic en el ícono "+" y elige "Add package from tarball".
- Selecciona el archivo .tgz de Cesium para Unity que descargaste en el paso 1.
- Es posible que se te solicite que instales dependencias adicionales, como Text Mesh Pro.
Habilita Geospatial Creator
Ya puedes habilitar Geospatial Creator:
- En el diálogo Build Settings, asegúrate de que la plataforma seleccionada sea "Android" o "iOS". Por el momento, las funciones de Geospatial Creator no están disponibles para otras plataformas.
- Navega a Project Settings > XR Plug-in Management > ARCore Extensions.
- Si no configuraste tus claves de API de ARCore para Android o iOS en un paso anterior, asegúrate de hacerlo ahora.
- Habilita los botones de activación "Geospatial" y "Geospatial Creator". Después de hacer clic para habilitar el botón de activación de Geospatial Creator, se mostrará un asistente no modal para confirmar que tu proyecto es compatible con Geospatial Creator.
- Haz clic en "Finalizar" en el asistente.
Después de terminar el asistente, Unity activará una compilación de tus secuencias de comandos. Espera a que se complete la recompilación antes de continuar. (Si la plataforma que seleccionaste no es "Android" ni "iOS", cambia a una de ellas ahora).
Cómo agregar un origen del Creador de Geospatial con Map Tiles
Tu escena necesita exactamente un objeto "Geospatial Creator Origin". Este objeto se usa como punto de referencia para convertir los valores de latitud, longitud y altitud del mundo real en coordenadas del juego de Unity.
Para agregar un Geospatial Creator Origin a tu escena, selecciona Game Object > XR > Geospatial Creator Origin. El objeto recién creado requiere una referencia geográfica, que vincula una latitud, una longitud y una altitud específicas a la posición del origen en las coordenadas del juego. En el panel Inspector de tu Geospatial Creator Origin, agrega una referencia geográfica haciendo clic en el botón Add Cesium Georeference Component.
Además de ser el punto de referencia para tus objetos de RA, el objeto CesiumGeoreference agrega un objeto Cesium 3D Tileset a la escena. Este objeto renderizará las Google Map Tiles en la vista de escena del editor, lo que te permitirá visualizar exactamente en qué lugar del mundo aparecerá tu contenido de RA. Hay un campo en el inspector de Geospatial Creator Origin para agregar la clave de la API de Map Tiles que configuraste anteriormente. Después de configurar esta clave, deberías ver que se cargan las tarjetas del mapa en la vista de escena.
Ahora cambia los campos de latitud, longitud y altura para que se ubiquen cerca de donde quieres que aparezca el contenido de RA en tu app.
La vista de escena en el editor ahora debería mostrar los mosaicos del mapa en la latitud y longitud especificadas de tu origen. En el tiempo de ejecución, suponemos que tu app usará la cámara de RA, por lo que Geospatial Creator ya configuró el objeto Cesium 3D Map Tileset con la etiqueta "EditorOnly". Por este motivo, las tarjetas no se descargarán ni renderizarán durante el tiempo de ejecución en tu juego. Esto se puede cambiar desde el inspector del objeto Cesium3DTileset. Para obtener más información sobre los objetos Georeference y 3D Tileset de Cesium, consulta la documentación de Cesium para Unity.
Cómo agregar y colocar un anclaje de Geospatial Creator
Ahora puedes colocar contenido de RA en tu escena. Haz clic en GameObject > XR > Geospatial Creator Anchor para agregar un anclaje a la jerarquía de tu escena. En el inspector del ancla, puedes especificar una latitud, una longitud y una altura exactas. La transformación del objeto se actualizará de inmediato a la posición correcta en tu escena, y podrás ver exactamente en qué lugar del mundo aparecerá el objeto.
A medida que ajustas la latitud y la longitud de la ancla, elige un lugar cercano para que puedas validar que se encuentra en el lugar correcto durante el tiempo de ejecución. Cuando configuras la altitud de un anclaje de Geospatial Creator, tienes tres opciones:
- Terreno coloca el ancla a nivel del suelo en la latitud y longitud especificadas. El sistema de posicionamiento visual determina el nivel del suelo en el tiempo de ejecución. Si no conoces las APIs de Geospatial de ARCore, "Terreno" es una buena opción, ya que el ancla se resolverá directamente en el suelo con un alto grado de precisión vertical. El campo "Desplazamiento de altitud" te permite posicionar el ancla por encima o por debajo del nivel del suelo en una cantidad fija, en metros. Por ejemplo, si especificas un desplazamiento de "1.0", el ancla "flotará" un metro por encima del terreno.
- Techo coloca el ancla en relación con la parte superior de cualquier estructura en la latitud y longitud determinadas. Al igual que el anclaje de terreno, el campo "Desplazamiento de altitud" te permite mover el anclaje hacia arriba o hacia abajo en relación con la posición del techo, en metros.
- WGS84 coloca el ancla en una altitud absoluta específica, en metros, según el sistema de coordenadas WGS84. Colocar el objeto de esta manera puede requerir algunas pruebas y errores, ya que una altura de "0" en WSG84 no necesariamente indica el nivel medio del mar y puede no coincidir con la altitud de un GPS. Además, si bien la latitud y la longitud de las tarjetas 3D renderizadas son muy precisas, intentar colocar el objeto a nivel del suelo usando las tarjetas 3D como referencia podría generar un error de altura de hasta varios metros.
Para obtener más información sobre los diferentes tipos de anclas geoespaciales de ARCore, consulta la Guía para desarrolladores de Geospatial.
Tanto los anclajes de terreno como los de azotea tienen un campo WGS84 Altitude. Este valor solo se usa en el modo Editor para establecer la altura del objeto en la vista de escena. Las alturas del terreno y de los techos se determinan solo en el tiempo de ejecución, por lo que el campo WGS84 Altitude te permite visualizar el ancla a una altura específica mientras desarrollas la app. El campo WGS84 Altitude se ignora en el tiempo de ejecución para las anclas de terreno y de techo.
Agrega geometría a la fijación
Si compilas y ejecutas la app ahora, no verás el anclaje en la app habilitada para AR, ya que no hay geometría adjunta. Agreguemos una primitiva 3D simple a la fijación: En la jerarquía de la escena, haz clic con el botón derecho en tu objeto AR Geospatial Creator Anchor. En el menú contextual, elige Objeto 3D > Cubo. Deberías ver un cubo gris en la vista de la escena como hijo del ancla. Si decides mover la posición o la rotación del objeto en el editor, te recomendamos que muevas el objeto Anchor raíz en lugar de la primitiva Cube secundaria. Esto ayudará a reducir el error en la traducción de latitud y longitud a coordenadas del juego.
Por supuesto, también puedes agregar geometría más compleja y componentes y elementos secundarios arbitrarios a la ancla.
Compila y ejecuta tu app
Es hora de ver tu ancla en el mundo real. Intenta compilar y ejecutar tu app, y luego muévete a la ubicación en la que esperas ver el cubo. ¿Está ahí? ¡Felicitaciones! Ya puedes crear experiencias de RA más complejas con el Creador geoespacial.
Si tienes algún problema, consulta la Guía de solución de problemas.
Ahora es un buen momento para agregar anclajes de AR Geospatial Creator adicionales con diferentes geometrías. Intenta experimentar con varios anclajes de azotea y terreno, y sus desplazamientos. Agrega secuencias de comandos para animar los objetos o habilitar interacciones con ellos.
Información sobre las anclas de Geospatial Creator y la clase ARGeospatialAnchor
Cuando se crean experiencias de RA interactivas y complejas, es útil comprender la relación entre las anclas de Geospatial Creator y la clase ARGeospatialAnchor de C# de ARCore:
Un ARGeospatialAnchor solo se puede crear en el tiempo de ejecución invocando una de las funciones en ARAnchorManager, y solo se pueden crear una vez que se estabilizó la sesión de RA. Se puede considerar que un anclaje de Geospatial Creator es un marcador de posición que existe en tu escena y espera a que la sesión de RA esté lista para resolver objetos ARGeospatialAnchor.
Una vez que la sesión esté lista, el marcador de posición llamará automáticamente a ARAnchorManager para crear y resolver el ARGeospatialAnchor.
Inmediatamente después de que se resuelva el anclaje de tiempo de ejecución, el anclaje de Geospatial Creator en la jerarquía de la escena se adjuntará como hijo al nuevo GameObject.
Esto significa que cualquier componente o elemento secundario del anclaje de Geospatial Creator se convertirá en subcomponente o nieto del nuevo objeto ARGeospatialAnchor GameObject. Por ejemplo, el transform de una primitiva de geometría adjunta al anclaje de Geospatial Creator heredará el transform del ARGeospatialAnchor y, por lo tanto, se colocará en la ubicación esperada en la sesión de RA del entorno de ejecución.
Si necesitas identificar objetos ARGeospatialAnchor específicos en el tiempo de ejecución, puedes buscar en la escena objetos cuya propiedad name coincida con el anclaje creado con Geospatial Creator. Si se inicializa la sesión de RA, el parent de ese objeto será el objeto ARGeospatialAnchor correspondiente.
Solución de problemas
¿Por qué se mueve mi ancla?
Es posible que notes, en especial cuando se inicia la app por primera vez, que el ancla puede parecer que se "desvía" lentamente o incluso que salta varios metros de forma abrupta. Esto ocurre cuando la sesión del VPS aún está determinando y perfeccionando la ubicación precisa de la cámara. A medida que la precisión horizontal y vertical mejora en varios fotogramas, el ancla se vuelve a dibujar en una ubicación más precisa, lo que da la ilusión de movimiento. Es posible que desees renderizar el objeto de manera diferente (o no renderizarlo en absoluto) hasta que la precisión de la ubicación alcance un umbral determinado. Para ello, puedes consultar la propiedad ARCoreEarthManager.CameraGeospatialPose para determinar la precisión de la actualización del fotograma actual.
¿Por qué mi ancla aparece a la altitud incorrecta?
Cuando se usa el tipo de altitud "Manual" para los anclajes de Geospatial Creator, la altitud del anclaje se establecerá (en metros) según el WGS84. En una ubicación determinada, puede haber una discrepancia de hasta varios metros entre el nivel del suelo aparente que se muestra en los mosaicos del mapa y el nivel del suelo real según lo informa el Sistema de posicionamiento visual (VPS) de Google. Si una ancla geoespacial parece estar ubicada de forma incorrecta en el tiempo de ejecución, te recomendamos que valides la altura del VPS en persona con la superposición de depuración en la app de ejemplo. Luego, puedes cambiar la altitud en el editor de Unity para que coincida con la altura conocida del VPS en esa ubicación.
Los mosaicos del mapa no se renderizan correctamente en la vista de escena del editor
Si parece que Cesium3DTileset está cargando segmentos, pero se renderizan en magenta sólido en la vista de escena, agrega el paquete Shader Graph de Unity a tu proyecto. Cesium requiere este paquete, aunque los proyectos que usan el renderizador integrado de Unity no lo incluyen de forma predeterminada.
Para agregar Shader Graph, abre Unity Package Manager (Window > Package Manager). Asegúrate de estar explorando los paquetes disponibles en el registro de paquetes de Unity seleccionando "Packages: Unity Registry" en el menú desplegable que se encuentra en la parte superior de la ventana del Package Manager. Busca el paquete com.unity.shadergraph y, luego, instala la versión más reciente. Una vez que se cargue el paquete, los mosaicos 3D deberían volver a cargarse y renderizarse correctamente en la vista de escena.
La app muestra una pantalla negra en el tiempo de ejecución en lugar de la vista de la cámara
La canalización universal de renderización (URP) de Unity no está configurada para la cámara de RA de forma predeterminada. Si ves una pantalla negra en el tiempo de ejecución en lugar de la salida de la cámara, deberás agregar el AR Background Renderer Feature a cada renderizador de URP de tu escena.
Para agregar la función, busca "renderer" en tu proyecto. Para cada objeto de renderizador de URP, haz clic en el botón "Add Renderer Feature" en el Inspector y agrega el renderizador de fondo de RA.
¿Por qué las anclas colocadas lejos del origen parecen estar ubicadas de forma incorrecta?
La conversión de coordenadas WGS84 a coordenadas del juego de Unity está sujeta a errores debido a la precisión aritmética de punto flotante, que se puede minimizar si te aseguras de que el origen esté cerca de tus anclajes de RA. Las distancias superiores a 20 km pueden generar imprecisiones. Si tu experiencia de RA abarca distancias largas, te recomendamos que uses varias escenas, con un ancla única en cada una.