Azure Spatial Anchors en Unreal

  • Artículo

Azure Spatial Anchors es un servicio de Microsoft Mixed Reality, que permite que los dispositivos de realidad aumentada detecten, compartan y conserven puntos de anclaje en el mundo físico. En la documentación siguiente se proporcionan instrucciones para integrar el servicio de Azure Spatial Anchors en un proyecto de Unreal. Si busca más información, consulte el servicio de Azure Spatial Anchors.

Nota:

Unreal Engine 4.26 ahora tiene complementos para la compatibilidad con ARKit y ARCore si usa iOS o Android como destino.

Importante

Los anclajes locales se almacenan en el dispositivo, mientras que los Azure Spatial Anchors se almacenan en la nube. Si tiene pensado almacenar los anclajes localmente en un dispositivo, hay un documento de Anclajes espaciales locales que puede guiarle por el proceso. Tenga en cuenta que puede tener anclajes locales y de Azure en el mismo proyecto sin que existan conflictos.

Requisitos previos

Para completar esta guía, asegúrese de tener:

Obtención de información de cuenta de Azure Spatial Anchors

Antes de usar Azure Spatial Anchors en un proyecto, debe:

  • Crear un recurso de anclajes espaciales y copiar los campos de la cuenta que se enumeran a continuación. Estos valores se usan para autenticar a los usuarios con la cuenta de la aplicación:
    • Id. de cuenta
    • Clave de cuenta

Para obtener más información, consulte los documentos de autenticación de Azure Spatial Anchors.

Nota:

Azure Spatial Anchors en Unreal 4.25 no admite tokens de autenticación de Azure AD, pero la compatibilidad con esta funcionalidad estará disponible en una versión posterior.

Habilitación de funcionalidades y permisos

HoloLens

Abra Configuración del proyecto HoloLens y habilite la funcionalidad Cliente de Internet:

Configuración del proyecto de HoloLens con funcionalidades resaltadas

Android

Para que una aplicación Android muestre un cuadro de diálogo de permisos y permita funcionalidades de ubicación, debe llamar a la función Solicitar permisos de Android antes de intentar iniciar la sesión de Azure Spatial Anchor:

Solicitar una función de permisos de Android

Cree una variable local para los permisos de entrada y rellénela con:

  • android.permission.ACCESS_WIFI_STATE
  • android.permission.CHANGE_WIFI_STATE
  • android.permission.INTERNET
  • android.permission.BLUETOOTH
  • android.permission.BLUETOOTH_ADMIN
  • android.permission.ACCESS_COARSE_LOCATION
  • android.permission.ACCESS_FINE_LOCATION
  • android.permission.CAMERA

Establecer permisos de Android

Por último, abra Configuración del proyecto Android y establezca los mismos permisos en el campo Permisos adicionales en Empaquetado avanzado de APK:

Configuración del proyecto APK de Android

iOS

Para compilar una aplicación para iOS, deberá usar Unreal en un equipo Mac. Para empaquetar con una cuenta de desarrollador de Apple, abra Configuración de proyecto iOS, y desplácese hacia abajo hasta la sección Compilación. Active la casilla Firma automática y rellene el id. de equipo de IOS con su id. de equipo.

Para encontrar el id. de equipo, inicie sesión en developer.apple.com, vaya a la pestaña Pertenencia y busque Id. de equipo.

Para mostrar un cuadro de diálogo de permisos y permitir que el dispositivo iOS acceda a la información de la ubicación, debe llamar a las funciones Init Location Services y Start Location Services antes de intentar iniciar la sesión de Azure Spatial Anchor:

Iniciar los servicios de ubicación de iOS

Adición de complementos de Azure Spatial Anchors

Sugerencia

Al usar Azure Spatial Anchors para Unreal, hay un complemento de Azure Spatial Anchors y un complemento específico de la plataforma (WMR, ARKit, ARCore, OpenXR). Solo debe tener habilitado un complemento específico de la plataforma a la vez.

HoloLens

Para habilitar los complementos de Azure Spatial Anchors en el editor de Unreal:

  1. Haga clic en Editar Complementos y busque Azure Spatial Anchors y Azure Spatial Anchors para WMR.
  2. Active la casilla Enabled (Habilitado) en ambos complementos para permitir el acceso a las bibliotecas de planos técnicos de Azure Spatial Anchors en la aplicación.

Captura de pantalla de los complementos de Spatial Anchors en el editor de Unreal

Una vez hecho esto, reinicie Unreal Editor para que los cambios de los complementos surtan efecto. El proyecto ahora está listo para usar Azure Spatial Anchors.

Android

Para habilitar los complementos de Azure Spatial Anchors en el editor de Unreal:

  1. Haga clic en Editar Complementos y busque Azure Spatial Anchors y Azure Spatial Anchors para ARCore.
  2. Active la casilla Enabled (Habilitado) en ambos complementos para permitir el acceso a las bibliotecas de planos técnicos de Azure Spatial Anchors en la aplicación.

Complementos de Android en el editor Unreal

Una vez hecho esto, reinicie Unreal Editor para que los cambios de los complementos surtan efecto. El proyecto ahora está listo para usar Azure Spatial Anchors.

iOS

Para habilitar los complementos de Azure Spatial Anchors en el editor de Unreal:

  1. Haga clic en Editar Complementos y busque Azure Spatial Anchors y Azure Spatial Anchors para ARKit.
  2. Active la casilla Enabled (Habilitado) en ambos complementos para permitir el acceso a las bibliotecas de planos técnicos de Azure Spatial Anchors en la aplicación.

Complementos de iOS ASA en el editor Unreal

  1. Busque también Servicios de ubicación móvil y Servicios de ubicación móvil: implementación de IOS.
  2. Active la casilla Habilitado en ambos complementos para permitir que el dispositivo iOS acceda a la ubicación actual.

Complementos de ubicación de iOS en el editor Unreal

Una vez hecho esto, reinicie Unreal Editor para que los cambios de los complementos surtan efecto. El proyecto ahora está listo para usar Azure Spatial Anchors.

Inicio de una sesión en Spatial Anchors

Una sesión de Azure Spatial Anchors permite que las aplicaciones cliente se comuniquen con el servicio de Azure Spatial Anchors. Deberá crear e iniciar una sesión de Azure Spatial Anchors para crear, conservar y compartir Azure Spatial Anchors:

  1. Abra el plano técnico del Pawn (Peón) que está usando en la aplicación.
  2. Agregue dos variables de cadena para Account ID (ID. de cuenta) y Account Key (Clave de cuenta) y, a continuación, asigne los valores correspondientes de la cuenta de Azure Spatial Anchors para autenticar la sesión.

Captura de pantalla del panel de detalles con el identificador, la clave y el tipo de variable de la cuenta de Azure Spatial Anchors resaltados

Para iniciar una sesión de Azure Spatial Anchors:

  1. Compruebe que se está ejecutando una AR Session (Sesión de AR) en la aplicación de HoloLens, ya que la sesión de Azure Spatial Anchors no puede iniciarse mientras no se esté ejecutando una sesión de AR. Si no tiene una configurada, cree un recurso de AR Session.
  2. Agregue el evento personalizado Start Azure Spatial Anchors Session (Iniciar sesión de Azure Spatial Anchors) y configúrelo como se muestra en la captura de pantalla siguiente.
    • Al crear una sesión no se inicia la sesión de manera predeterminada, lo que le permite configurar la sesión para la autenticación en el servicio de Azure Spatial Anchors.

Plano técnico del evento personalizado de inicio de sesión de Azure Spatial Anchors

  1. Configure la sesión de Azure Spatial Anchors para proporcionar el identificador de cuenta, la clave de cuenta, el dominio de cuenta y la configuración de la localización del curso. Todas las casillas deben estar habilitadas en la configuración de localización del curso para que el servicio de anclaje espacial de Azure pueda usar datos de sensor para buscar anclajes.

Plano técnico de la función de sesión de configuración con el id. de cuenta y la clave agregada

  1. Inicie la sesión de Azure Spatial Anchors, lo que permite a la aplicación crear y ubicar los Azure Spatial Anchors.

Plano técnico de la función de inicio de sesión de Azure Spatial Anchors

Se recomienda limpiar los recursos de Azure Spatial Anchors en el plano técnico Event Graph (Gráfico de eventos) cuando ya no use el servicio:

  1. Detenga la sesión de Azure Spatial Anchors. La sesión ya no estará en ejecución, pero sus recursos asociados seguirán existiendo en el complemento de Azure Spatial Anchors.

Plano técnico del evento personalizado de detención de sesiones de Azure Spatial Anchors y función de detención de sesión

  1. Destruya la sesión de Azure Spatial Anchors para limpiar los recursos de la sesión de Azure Spatial Anchors aún conocidos por el complemento de Azure Spatial Anchors.

Plano técnico de la función de destrucción de sesión

El plano técnico Event Graph (Gráfico de eventos) debe ser similar a la siguiente captura de pantalla:

Plano técnico del gráfico de eventos completo de la configuración de la sesión de Azure Spatial Anchors

Creación de un anclaje

Una instancia de Azure Spatial Anchors representa un lugar del mundo físico en el espacio de la aplicación de realidad aumentada, que fija el contenido de la realidad aumentada a ubicaciones físicas. Los Azure Spatial Anchors también se pueden compartir entre distintos usuarios. Este uso compartido permite que el contenido de la realidad aumentada dibujado en diferentes dispositivos se coloque en la misma ubicación del mundo físico.

Para crear un nuevo Azure Spatial Anchor:

  1. Compruebe que haya una sesión de Azure Spatial Anchors en ejecución. La aplicación no puede crear o conservar un Azure Spatial Anchor cuando no se está ejecutando ninguna sesión de Azure Spatial Anchors.

Plano técnico del evento personalizado de creación de una instancia de Azure Spatial Anchor

  1. Cree u obtenga un Scene Component (Componente de escena) de Unreal cuya ubicación deba conservarse.
    • En la imagen siguiente, el componente Scene Component Needing Anchor se usa como variable. Se necesita un componente de escena de Unreal para establecer una transformación del mundo de la aplicación para un AR Pin (Marca de AR) y Azure Spatial Anchor.

Plano técnico del evento personalizado de creación de una instancia de Azure Spatial Anchors con el componente de la escena

Para construir y guardar un Azure Spatial Anchor para un componente de escena de Unreal:

  1. Llame al Pin Component (Componente de marca) para el componente de escena de Unreal y especifique la World Transform (Transformación de mundos) del componente de escena como la transformación de mundos que se usa para AR Pin (Marca de AR).
    • Unreal realiza un seguimiento de los puntos de AR en el espacio de la aplicación mediante AR Pins (Marcas de AR), que se usan para crear un Azure Spatial Anchor. En Unreal, una AR Pin (Marca de AR) es análoga a SpatialAnchor en HoloLens.

Plano técnico del componente de la escena conectado a la función de anclaje de componentes

  1. Llame a Create Cloud Anchor (Crear anclaje de nube) con la AR Pin (Marca de AR) recién creada.
    • Create Cloud Anchor crea un Azure Spatial Anchor de forma local, pero no en el servicio de Azure Spatial Anchors. Los parámetros del Azure Spatial Anchor, como una fecha de expiración, se pueden establecer antes de crear el Azure Spatial Anchor con el servicio.

Plano técnico de la función de anclaje de componentes conectada a la función de creación de anclaje en la nube que devuelve ARPin

  1. Establezca la expiración del Azure Spatial Anchor. El parámetro Lifetime (Duración) de la función permite al desarrollador especificar en segundos cuánto tiempo debe el servicio mantener el anclaje.
    • Por ejemplo, una expiración de una semana tomaría un valor de 60 segundos x 60 minutos x 24 horas x 7 días = 604 800 segundos.

Plano técnico de la función de anclaje en la nube conectada a la función de establecimiento de la expiración con el valor de duración establecido en 604 800 segundos

Después de establecer los parámetros de los anclajes, declare el anclaje como listo para guardarse. En el ejemplo siguiente, el Azure Spatial Anchor recién creado se agrega a un conjunto de Azure Spatial Anchors que debe guardarse. Este conjunto se declara como variable para el plano técnico del Pawn (Peón).

Plano técnico del anclaje listo para guardarse en el establecimiento de la variable

Guardado de un anclaje

Después de configurar el Azure Spatial Anchor con sus parámetros, llame a Save Cloud Anchor (Guardar anclaje de nube). Save Cloud Anchor declara el anclaje en el servicio de Azure Spatial Anchors. Cuando la llamada a Save Cloud Anchor se realiza correctamente, el Azure Spatial Anchor está disponible para otros usuarios del servicio de Azure Spatial Anchors.

Plano técnico de la llamada a la función de guardado del anclaje en la nube

Nota:

Save Cloud Anchor es una función asincrónica y solo se puede llamar desde un evento de subproceso de juego, como EventTick. Es posible que Save Cloud Anchor no aparezca como una función de plano técnico en el plano técnico personalizado Functions (Funciones). Sin embargo, debe estar disponible en el editor de planos técnicos Event Graph (Gráfico de eventos) del Pawn (Peón).

En el ejemplo siguiente, el Azure Spatial Anchor se almacena en un conjunto durante una devolución de llamada del evento de entrada. Después, el elemento se guarda en EventTick. Se pueden necesitar varios intentos para guardar un Azure Spatial Anchor, en función de la cantidad de datos espaciales que se hayan creado en la sesión de Azure Spatial Anchors. Por eso es conveniente comprobar si la llamada de guardado se realizó correctamente.

Si el anclaje no se guarda, vuelva a agregarlo al conjunto de anclajes que todavía deben guardarse. Los EventTicks futuros intentarán guardar el anclaje hasta que se almacene correctamente.

Plano técnico que muestra como se vuelven a guardar los anclajes no guardados en el establecimiento de la variable

Una vez que se guarde el anclaje, la transformación de AR Pins (Marcas de AR) actúa como transformación de referencia para colocar contenido en la aplicación. Otros usuarios pueden detectar este anclaje y alinear el contenido de AR para diferentes dispositivos del mundo físico.

Eliminación de un anclaje

Puede eliminar los anclajes del servicio Azure Spatial Anchors llamando a Delete Cloud Anchor (Eliminar anclaje de nube).

Plano técnico de la llamada a la función de eliminación del anclaje en la nube

Nota:

Delete Cloud Anchor es una función latente y solo se puede llamar desde un evento de subproceso de juego, como EventTick. Es posible que Delete Cloud Anchor no aparezca como una función de plano técnico en el plano técnico personalizado Functions (Funciones). Sin embargo, debe estar disponible en el editor de planos técnicos Event Graph (Gráfico de eventos) del Pawn (Peón).

En el ejemplo siguiente, el anclaje está marcado para su eliminación en un evento de entrada personalizado. A continuación, se intenta la eliminación en EventTick. Si se produce un error en la eliminación del anclaje, agregue el Azure Spatial Anchor al conjunto de anclajes marcados para su eliminación y vuelva a intentarlo en EventTicks posteriores.

El plano técnico Event Graph (Gráfico de eventos) ahora debe ser similar a la siguiente captura de pantalla:

Plano técnico del gráfico de eventos completo para controlar los anclajes en la nube

Detección de anclajes preexistentes

Los anclajes existentes pueden ser creados por elementos del mismo nivel con el servicio de Azure Spatial Anchors:

  1. Obtenga un identificador de Azure Spatial Anchor para el anclaje que desea detectar.
    • Se puede obtener un identificador de anclaje para un anclaje creado por el mismo dispositivo en una sesión anterior de Azure Spatial Anchors. También se puede crear y compartir mediante dispositivos del mismo nivel que interactúen con el servicio de Azure Spatial Anchors.

Plano técnico del evento personalizado de almacenamiento del identificador de Azure Spatial Anchors con la función de obtención del identificador de la nube de Azure

  1. Agregue un componente AzureSpatialAnchorsEvent al plano técnico del Pawn (Peón).
    • Este componente le permite suscribirse a varios eventos de Azure Spatial Anchors, como los eventos a los que se llama cuando se detectan Azure Spatial Anchors.

Captura de pantalla de BP_Pawn abierto en el editor de plano técnico con los paneles de componentes y de detalles abiertos

  1. Suscríbase a ASAAnchor Located Delegate (Delegado detectado de ASAAnchor) para el componente AzureSpatialAnchorsEvent.
    • El delegado permite que la aplicación sepa cuándo se han encontrado nuevos anclajes asociados con la cuenta de Azure Spatial Anchors.
    • Con la devolución de llamada del evento, no se crearán de forma predeterminada AR Pins (Marcas de AR) para los Azure Spatial Anchors creados por pares mediante la sesión de Azure Spatial Anchors. Para crear una AR Pin (Marca de AR) para el Spatial Anchor de Azure detectado, los desarrolladores pueden llamar a Create ARPin Around Azure Cloud Spatial Anchor (Crear ARPin en función del anclaje espacial en la nube de Azure).

Plano técnico del evento para empezar a jugar conectado al delegado ubicado en ASAAnchor

Para buscar las instancias de Azure Spatial Anchors creadas por los elementos del mismo nivel mediante el servicio de Azure Spatial Anchors, la aplicación tendrá que crear un Monitor de Azure Spatial Anchors:

  1. Compruebe que haya una sesión de Azure Spatial Anchors en ejecución.
  2. Cree un AzureSpatialAnchorsLocateCriteria.
    • Puede especificar varios parámetros de ubicación, como la distancia desde el usuario o la distancia desde otro anclaje.
  3. Declare el identificador de Azure Spatial Anchors que busca en AzureSpatialAnchorsLocateCritieria.
  4. Llame a Create Watcher (Crear monitor).

Plano técnico del evento personalizado de inicio del monitor de Azure Spatial Anchors

Ahora, la aplicación comienza a buscar los Azure Spatial Anchors que conoce el servicio de Azure Spatial Anchors, lo que significa que los usuarios pueden localizar los Azure Spatial Anchors creados por sus pares.

Después de localizar el Azure Spatial Anchor, llame a Stop Watcher (Detener monitor) para detener Azure Spatial Anchors Watcher (Monitor de Azure Spatial Anchors) y limpie los recursos del monitor.

Plano técnico de la llamada a la función de detención del monitor

El plano técnico Event Graph (Gráfico de eventos) final ahora debe ser similar a la siguiente captura de pantalla:

Plano técnico del gráfico de eventos completo para controlar los eventos del delegado de anclaje

Siguiente punto de control de desarrollo

Si sigue el recorrido de desarrollo de Unreal que hemos diseñado, significa que ya se encuentra en proceso de explorar los bloques de compilación principales de MRTK. Desde aquí, puede continuar con el siguiente bloque de compilación:

Asignación espacial

O bien puede saltar a las funcionalidades y las API de la plataforma de realidad mixta:

Cámara de HoloLens

Puede volver a los puntos de control de desarrollo de Unreal en cualquier momento.

Pasos siguientes