Creación y localización de delimitadores mediante Azure Spatial Anchors en C++/WinRT

• Unity
• Objective-C
• Swift
• Android Java
• C++/NDK
• C++/WinRT

Azure Spatial Anchors permite compartir delimitadores entre diferentes dispositivos de todo el mundo. Admite varios entornos de desarrollo diferentes. En este artículo, se examinará en profundidad cómo usar el SDK de Azure Spatial Anchors, en C++/WinRT, para:

• Configurar y administrar correctamente una sesión de Azure Spatial Anchors.
• Crear y establecer propiedades en los anclajes locales.
• Cargarlos en la nube.
• Localizar y eliminar los anclajes espaciales en la nube.

Requisitos previos

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

• Ha leído completamente Introducción a Azure Spatial Anchors.
• Ha completado uno de los inicios rápidos en 5 minutos.
• Conocimiento básico sobre C++ y Windows Runtime APIs.

Inicialización de la sesión

El punto de entrada principal del SDK es la clase que representa la sesión. Normalmente declarará un campo en la clase que administra la vista y la sesión de AR nativa.

Obtenga más información sobre la clase CloudSpatialAnchorSession.

    CloudSpatialAnchorSession m_cloudSession{ nullptr };

    m_cloudSession = CloudSpatialAnchorSession();

Configuración de la autenticación

Para acceder al servicio, deberá proporcionar una clave de cuenta, un token de acceso o un token de autenticación de Microsoft Entra. También puede leer más información al respecto en la página Concepto de autenticación.

Claves de cuenta

Las claves de cuenta son una credencial que permite que la aplicación se autentique con el servicio Azure Spatial Anchors. Las claves de cuenta están pensadas para ayudarle a empezar a trabajar rápidamente, sobre todo durante la fase de desarrollo de integración de la aplicación con Azure Spatial Anchors. Para usar las claves de cuenta, debe insertarlas en las aplicaciones cliente durante el desarrollo. A medida que avance en el desarrollo, se recomienda encarecidamente que cambie a un mecanismo de autenticación que sea de nivel de producción, compatible con tokens de acceso, o a la autenticación de usuario de Microsoft Entra. Para obtener una clave de cuenta para el desarrollo, visite su cuenta de Azure Spatial Anchors y vaya a la pestaña "Claves".

Obtenga más información sobre la clase SessionConfiguration.

    auto configuration = m_cloudSession.Configuration();
    configuration.AccountKey(LR"(MyAccountKey)");

Tokens de acceso

Los tokens de acceso son un método más sólido para autenticarse con Azure Spatial Anchors, sobre todo al preparar la aplicación para una implementación de producción. En resumen, este enfoque consiste en configurar un servicio back-end con el que la aplicación cliente se pueda autenticar de forma segura. El servicio de back-end se comunica con AAD en tiempo de ejecución y con el servicio de token seguro de Azure Spatial Anchors para solicitar un token de acceso. Después, este token se entrega a la aplicación cliente y se usa en el SDK para autenticarse con Azure Spatial Anchors.

    auto configuration = m_cloudSession.Configuration();
    configuration.AccessToken(LR"(MyAccessToken)");

Si no se ha establecido un token de acceso, debe controlar el evento TokenRequired o implementar el método tokenRequired en el protocolo de delegado.

Puede controlar el evento de forma sincrónica mediante el establecimiento de la propiedad en los argumentos del evento.

Obtenga más información sobre el delegado TokenRequiredDelegate.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AccessToken(LR"(MyAccessToken)");
    });

Si tiene que ejecutar un trabajo asincrónico en el controlador, puede aplazar el establecimiento del token. Para ello, solicite un objeto deferral y complételo, como se indica en el ejemplo siguiente.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) args.AccessToken(myToken);
            deferral.Complete();
        });
    });

Autenticación de Microsoft Entra

Azure Spatial Anchors también permite que las aplicaciones se autentiquen con tokens de usuario de Microsoft Entra ID (Active Directory). Por ejemplo, puede usar tokens de Microsoft Entra para realizar la integración con Azure Spatial Anchors. Si una empresa mantiene usuarios en Microsoft Entra ID, puede proporcionar un token de usuario de Microsoft Entra en el SDK de Azure Spatial Anchors. De este modo, podrá autenticarse directamente en el servicio de Azure Spatial Anchors para una cuenta que forme parte del mismo inquilino de Microsoft Entra.

    auto configuration = m_cloudSession.Configuration();
    configuration.AuthenticationToken(LR"(MyAuthenticationToken)");

Al igual que sucede con los tokens de acceso, si no se ha establecido un token de Microsoft Entra, debe controlar el evento TokenRequired o implementar el método tokenRequired en el protocolo de delegado.

Puede controlar el evento de forma sincrónica mediante el establecimiento de la propiedad en los argumentos del evento.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AuthenticationToken(LR"(MyAuthenticationToken)");
    });

Si tiene que ejecutar un trabajo asincrónico en el controlador, puede aplazar el establecimiento del token. Para ello, solicite un objeto deferral y complételo, como se indica en el ejemplo siguiente.

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) args.AuthenticationToken(myToken);
            deferral.Complete();
        });
    });

Configuración de la sesión

Invoque Start() para permitir que la sesión procese datos del entorno.

Para controlar los eventos que genere la sesión, asocie un controlador de eventos.

Obtenga más información sobre el método Start.

    m_cloudSession.Start();

Suministro de fotogramas a la sesión

La sesión de anclaje espacial funciona mediante la asignación del espacio en torno al usuario. Esto ayuda a determinar dónde se encuentran los delimitadores. Las plataformas móviles (iOS y Android) requieren una llamada a la fuente de la cámara para obtener fotogramas de la biblioteca de AR de la plataforma nativa. En cambio, HoloLens examina constantemente el entorno, por lo que no hay ninguna necesidad de realizar una llamada concreta, como en las plataformas móviles.

Obtenga más información sobre el método ProcessFrame.

    m_cloudSession->ProcessFrame(ar_frame_);

Envío de comentarios al usuario

Puede escribir código para controlar el evento actualizado de la sesión. Este evento se desencadena cada vez que la sesión mejora su capacidad de reconocimiento del entorno. Esto le permite hacer lo siguiente:

• Usar la clase UserFeedback para proporcionar comentarios al usuario cuando el dispositivo se mueve y la sesión actualiza su capacidad de reconocimiento del entorno. Para ello:
• Determine en qué momento hay suficientes datos espaciales de seguimiento para crear anclajes espaciales, lo que se puede determinar con ReadyForCreateProgress o RecommendedForCreateProgress. Una vez que ReadyForCreateProgress sea superior a 1, tendremos suficientes datos para guardar un anclaje espacial de la nube, aunque se recomienda esperar hasta que RecommendedForCreateProgress sea superior a 1 para hacerlo.

Obtenga más información sobre el delegado SessionUpdatedDelegate.

    m_sessionUpdatedToken = m_cloudSession.SessionUpdated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        auto status = args.Status();
        if (status.UserFeedback() == SessionUserFeedback::None) return;
        m_feedback = LR"(Feedback: )" + FeedbackToString(status.UserFeedback()) + LR"( -)" +
            LR"( Recommend Create=)" + FormatPercent(status.RecommendedForCreateProgress() * 100.f);
    });

Creación de un anclaje espacial de la nube

Para crear un anclaje espacial de la nube, primero es preciso crear un anclaje en el sistema de realidad aumentada de la plataforma y, luego, crear otro equivalente en la nube. Para ello, use el método CreateAnchorAsync().

Obtenga más información sobre la clase CloudSpatialAnchor.

    // Initialization
    SpatialStationaryFrameOfReference m_stationaryReferenceFrame = nullptr;
    HolographicDisplay defaultHolographicDisplay = HolographicDisplay::GetDefault();
    SpatialLocator spatialLocator = defaultHolographicDisplay.SpatialLocator();
    m_stationaryReferenceFrame = spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

    // Create a local anchor, perhaps by positioning a SpatialAnchor a few meters in front of the user
    SpatialAnchor localAnchor{ nullptr };
    PerceptionTimestamp timestamp = PerceptionTimestampHelper::FromHistoricalTargetTime(DateTime::clock::now());
    SpatialCoordinateSystem currentCoordinateSystem = m_attachedReferenceFrame.GetStationaryCoordinateSystemAtTimestamp(timestamp);
    SpatialPointerPose pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, timestamp);

    // Get the gaze direction relative to the given coordinate system.
    const float3 headPosition = pose.Head().Position();
    const float3 headDirection = pose.Head().ForwardDirection();

    // The anchor is positioned two meter(s) along the user's gaze direction.
    constexpr float distanceFromUser = 2.0f; // meters
    const float3 gazeAtTwoMeters = headPosition + (distanceFromUser * headDirection);

    localAnchor = SpatialAnchor::TryCreateRelativeTo(currentCoordinateSystem, gazeAtTwoMeters);

    // If the user is placing some application content in their environment,
    // you might show content at this anchor for a while, then save when
    // the user confirms placement.
    CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);
    m_feedback = LR"(Created a cloud anchor with ID=)" + cloudAnchor.Identifier();

Como ya se ha indicado, para intentar crear un anclaje espacial de la nube es preciso tener suficientes datos del entorno capturados, lo que significa que el valor de ReadyForCreateProgress debe ser superior a 1, aunque se recomienda esperar hasta que el valor de RecommendedForCreateProgress esté por encima de 1 para hacerlo.

Obtenga más información sobre el método GetSessionStatusAsync.

    SessionStatus status = co_await m_cloudSession.GetSessionStatusAsync();
    if (value.RecommendedForCreateProgress() < 1.0f) return;
    // Issue the creation request ...

Establecimiento de las propiedades

Puede optar por agregar algunas propiedades al guardar los anclajes espaciales de la nube, como el tipo de objeto que se está guardando o propiedades básicas, por ejemplo, si debe habilitarse para la interacción. Esto puede ser útil tras la detección, ya que le permite representar el objeto de inmediato para el usuario, por ejemplo, un marco de imagen con contenido en blanco. Después, una descarga diferente en segundo plano obtiene otros detalles de estado, como la imagen que se va a mostrar en el marco.

Obtenga más información sobre el método AppProperties.

    CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    auto properties = m_cloudAnchor.AppProperties();
    properties.Insert(LR"(model-type)", LR"(frame)");
    properties.Insert(LR"(label)", LR"(my latest picture)");
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);

Actualización de propiedades

Para actualizar las propiedades de un delimitador, se usa el método UpdateAnchorProperties(). Si dos o más dispositivos intentan actualizar las propiedades del mismo delimitador al mismo tiempo, se usa un modelo de simultaneidad optimista, lo que significa que la primera escritura tendrá prioridad. En todas las demás se producirá un error de "simultaneidad", es decir, será necesario actualizar las propiedades antes de intentarlo de nuevo.

Obtenga más información sobre el método UpdateAnchorPropertiesAsync.

    CloudSpatialAnchor anchor = /* locate your anchor */;
    anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
    co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);

No se puede actualizar la ubicación de un delimitador una vez que se ha creado en el servicio. Debe crear otro delimitador y eliminar el antiguo para realizar un seguimiento de una nueva posición.

Si no necesita localizar un delimitador para actualizar sus propiedades, puede usar el método GetAnchorPropertiesAsync(), que devuelve un objeto CloudSpatialAnchor con propiedades.

Obtenga más información sobre el método GetAnchorPropertiesAsync.

    CloudSpatialAnchor anchor = co_await m_cloudSession.GetAnchorPropertiesAsync(LR"(anchorId)");
    if (anchor != nullptr)
    {
        anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
        co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);
    }

Configurar expiración

También es posible configurar el delimitador para que expire automáticamente en el futuro en una fecha determinada. Cuando expira un delimitador, ya no se encontrará ni se actualizará. La expiración solo se puede establecer cuando se crea el anclaje, antes de guardarlo en la nube. No es posible actualizarla más adelante, Si no se establece ninguna expiración durante la creación del anclaje, este solo expirará cuando se elimine manualmente.

Obtenga más información sobre el método Expiration.

    const int64_t oneWeekFromNowInHours = 7 * 24;
    const DateTime oneWeekFromNow = DateTime::clock::now() + std::chrono::hours(oneWeekFromNowInHours);
    cloudAnchor.Expiration(oneWeekFromNow);

Búsqueda de un anclaje espacial de la nube

Una de las principales razones para usar Azure Spatial Anchors es poder localizar un anclaje espacial en la nube previamente guardado. Para ello, usamos "Monitores". Solo se puede usar un monitor a la vez; no se admiten varios monitores. Hay varias maneras diferentes (también conocidas como Estrategias de búsqueda de anclajes) que un monitor puede localizar un delimitador espacial en la nube. Una estrategia no se puede usar en varios monitores a la vez.

• Busque delimitadores por identificador.
• Busque los delimitadores conectados a un delimitador ubicado previamente. Aquí puede obtener información sobre las relaciones de los delimitadores.
• Busque un delimitador mediante la relocalización general.

Nota

Cada vez que se encuentra un delimitador, Azure Spatial Anchors intenta usar los datos de entorno recopilados para aumentar la información visual del delimitador. Si tiene problemas para encontrar un delimitador, puede ser útil crear uno y, a continuación, colocarlo varias veces en diferentes ángulos y condiciones de iluminación.

Si va a buscar anclajes espaciales en la nube por identificador, podrá almacenar el identificador de anclaje espacial de la nube en el servicio back-end de la aplicación y hacer que todos los dispositivos que puedan autenticarse correctamente en él puedan acceder a él. For ver un ejemplo de esto, consulte Tutorial: Uso compartido de Spatial Anchors entre dispositivos.

Crear una instancia de un objeto AnchorLocateCriteria, establezca los identificadores que busca e invoque el método CreateWatcher en la sesión mediante su AnchorLocateCriteria.

Obtenga más información sobre el método CreateWatcher.

    AnchorLocateCriteria criteria = AnchorLocateCriteria();
    criteria.Identifiers({ LR"(id1)", LR"(id2)", LR"(id3)" });
    auto cloudSpatialAnchorWatcher = m_cloudSession.CreateWatcher(criteria);

Una vez creado el monitor, se desencadenará el evento AnchorLocated para cada delimitador solicitado. Este evento se desencadena cuando se encuentra un delimitador o si no puede encontrarse. Si se produce esta situación, el motivo se incluirá en el estado. Una vez procesados todos los delimitadores de un monitor, tanto si se encuentran como si no, se desencadenará el evento LocateAnchorsCompleted. Hay un límite de 35 identificadores por monitor.

Obtenga más información sobre el delegado AnchorLocatedDelegate.

    m_anchorLocatedToken = m_cloudSession.AnchorLocated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        switch (args.Status())
        {
            case LocateAnchorStatus::Located:
            {
                CloudSpatialAnchor foundAnchor = args.Anchor();
            }
                break;
            case LocateAnchorStatus::AlreadyTracked:
                // This anchor has already been reported and is being tracked
                break;
            case LocateAnchorStatus::NotLocatedAnchorDoesNotExist:
                // The anchor was deleted or never existed in the first place
                // Drop it, or show UI to ask user to anchor the content anew
                break;
            case LocateAnchorStatus::NotLocated:
                // The anchor hasn't been found given the location data
                // The user might in the wrong location, or maybe more data will help
                // Show UI to tell user to keep looking around
                break;
        }
    });

Eliminación de delimitadores

La eliminación de los anclajes que ya no se usan es una práctica recomendada que debe incluirse en las primeras fases del proceso de desarrollo para mantener limpios los recursos de Azure.

Obtenga más información sobre el método DeleteAnchorAsync.

    co_await m_cloudSession.DeleteAnchorAsync(cloudAnchor);
    // Perform any processing you may want when delete finishes

Pausa, restablecimiento o detención de la sesión

Para detener la sesión temporalmente, puede invocar Stop(). Si lo hace, se detendrán los monitores y el procesamiento de entorno, incluso si invoca ProcessFrame(). Puede invocar Start() para reanudar el procesamiento. Cuando se reanude, se conservarán los datos del entorno que ya se hayan capturado en la sesión.

Obtenga más información sobre el método Stop.

    m_cloudSession.Stop();

Para restablecer los datos del entorno que se han capturado en la sesión, puede invocar Reset().

Más información sobre el método Reset.

    m_cloudSession.Reset();

Para realizar correctamente una limpieza después de una sesión, libere todas las referencias.

    m_cloudSession = nullptr;

Pasos siguientes

En esta guía, ha aprendido a crear y localizar delimitadores mediante el SDK de Azure Spatial Anchors. Para obtener más información sobre las relaciones de los delimitadores, vaya a la guía siguiente.

Relaciones de delimitadores