Creación y localización de anclajes mediante Azure Spatial Anchors en Objective-C

• 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 Objective-C, 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 de Objective-C.
• Conocimiento básico de ARKit.

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 ASACloudSpatialAnchorSession.

    ASACloudSpatialAnchorSession *_cloudSession;
    // In your view handler
    _cloudSession = [[ASACloudSpatialAnchorSession alloc] init];

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 ASASessionConfiguration.

    _cloudSession.configuration.accountKey = @"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.

    _cloudSession.configuration.accessToken = @"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 método de protocolo tokenRequired.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        args.accessToken = @"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.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) 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.

    _cloudSession.configuration.authenticationToken = @"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.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        args.authenticationToken = @"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.

    - (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
        ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
        [myGetTokenAsync callback:^(NSString *myToken) {
            if (myToken) args.authenticationToken = myToken;
            [deferral complete];
        }];
    }

Configuración de la biblioteca

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

Para controlar los eventos generados por la sesión, establezca la propiedad delegate de la sesión en un objeto, como la vista. Este objeto debe implementar el protocolo SSCCloudSpatialAnchorSessionDelegate.

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

    _cloudSession.session = self.sceneView.session;
    _cloudSession.delegate = self;
    [_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.

    [_cloudSession processFrame:_sceneView.session.currentFrame];

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 método de protocolo sessionUpdated.

    - (void)sessionUpdated:(ASACloudSpatialAnchorSession *)cloudSession :(ASASessionUpdatedEventArgs *)args {
        ASASessionStatus *status = [args status];
        if (status.userFeedback == ASASessionUserFeedbackNone) return;
        _feedback = [NSString
            stringWithFormat:@"Feedback: %@ - Recommend Create=%.0f%%",
            FeedbackToString(status.userFeedback),
            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 ASACloudSpatialAnchor.

    // Create a local anchor, perhaps by hit-testing and creating an ARAnchor
    NSArray<ARHitTestResult *> *hits = [_sceneView.session.currentFrame hitTest:CGPointMake(0.5, 0.5) types:ARHitTestResultTypeEstimatedHorizontalPlane];
    if ([hits count] == 0) return;
    // The hitTest method sorts the resulting list by increasing distance from the camera
    // The first hit result will usually be the most relevant when responding to user input
    ARAnchor *localAnchor = [[ARAnchor alloc] initWithTransform:hits[0].worldTransform];
    [_sceneView.session addAnchor:localAnchor];

    // 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.
    ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
    cloudAnchor.localAnchor = localAnchor;
    [_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        if (error) {
            _feedback = [NSString stringWithFormat:@"Save Failed:%@", error.localizedDescription];
            return;
        }
        _feedback = [NSString stringWithFormat:@"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 getSessionStatusWithCompletionHandler.

    [_cloudSession getSessionStatusWithCompletionHandler:^(ASASessionStatus *value, NSError *error) {
        if (error) {
            _feedback = [NSString stringWithFormat:@"Session status error:%@", error.localizedDescription];
            return;
        }
        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 la propiedad appProperties.

    ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
    cloudAnchor.localAnchor = localAnchor;
    cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
    [_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        // ...
    });

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 updateAnchorProperties.

    ASACloudSpatialAnchor *anchor = /* locate your anchor */;
    [anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
    [_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
        if (error) _feedback = [NSString stringWithFormat:@"Updating Properties Failed:%@", error.localizedDescription];
    }];

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 updateAnchorProperties.

    [_cloudSession getAnchorProperties:@"anchorId" withCompletionHandler:^(SCCCloudSpatialAnchor *anchor, NSError *error) {
        if (error) {
            _feedback = [NSString stringWithFormat:@"Getting Properties Failed:%@", error.localizedDescription];
            return;
        }
        if (anchor) {
            [anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
            [_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
                // ...
            }];
        }
    }];

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 la propiedad expiration.

    int secondsInAWeek = 60 * 60 * 24 * 7;
    NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) secondsInAWeek];
    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.

    ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
    criteria.identifiers = @[ @"id1", @"id2", @"id3" ];
    [_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 método de protocolo anchorLocated.

    - (void)anchorLocated:(ASACloudSpatialAnchorSession *)cloudSession :(ASAAnchorLocatedEventArgs *)args {
        ASALocateAnchorStatus status = [args status];
        switch (status) {
        case ASALocateAnchorStatusLocated: {
            ASACloudSpatialAnchor *foundAnchor = [args anchor];
            // Go add your anchor to the scene...
        }
            break;
        case ASALocateAnchorStatusAlreadyTracked:
            // This anchor has already been reported and is being tracked
            break;
        case ASALocateAnchorStatusNotLocatedAnchorDoesNotExist:
            // 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 ASALocateAnchorStatusNotLocated:
            // 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 deleteAnchor.

    [_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
        // 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.

    [_cloudSession stop];

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

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

    [_cloudSession reset];

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

    _cloudSession = NULL;

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