Como criar e localizar âncoras usando as Âncoras Espaciais do Azure no Unity

  • Artigo

Âncoras Espaciais do Azure permitem que você compartilhe âncoras no mundo entre diferentes dispositivos. É compatível com vários ambientes de desenvolvimento diferentes. Neste artigo, nós nos aprofundaremos em como usar o SDK das Âncoras Espaciais do Azure no Unity para:

  • Configurar e gerenciar corretamente uma sessão das Âncoras Espaciais do Azure.
  • Criar e definir propriedades em âncoras locais.
  • Fazer upload delas na nuvem.
  • Localizar e excluir âncoras espaciais na nuvem.

Pré-requisitos

Para concluir este guia, verifique se você:

Cross Platform

Inicializar a sessão

O ponto de entrada principal para o SDK é a classe que representa sua sessão. Normalmente, você vai declarar um campo na classe que gerencia sua exibição e a sessão do RA nativo.

Saiba mais sobre a classe CloudSpatialAnchorSession.

    CloudSpatialAnchorSession cloudSession;
    // In your view handler
    this.cloudSession = new CloudSpatialAnchorSession();

Configurar a autenticação

Para acessar o serviço, você precisa fornecer uma chave de conta, um token de acesso ou um token de autenticação do Microsoft Entra. Leia também mais sobre isso na página sobre o conceito de autenticação.

Chaves de conta

Chaves de conta são uma credencial que permite que o aplicativo seja autenticado no serviço Âncoras Espaciais do Azure. A finalidade pretendida das chaves de conta é ajudar você com uma rápida introdução. Especialmente durante a fase de desenvolvimento da integração do aplicativo às Âncoras Espaciais do Azure. Assim, você pode usar chaves de conta inserindo-as em seus aplicativos cliente durante o desenvolvimento. À medida que você avança além do desenvolvimento, é altamente recomendável migrar para um mecanismo de autenticação que seja de nível de produção, que dê suporte a tokens de acesso ou à autenticação de usuário do Microsoft Entra. Para obter uma chave de conta para desenvolvimento, visite a sua conta das Âncoras Espaciais do Azure e navegue até a guia "Chaves".

Saiba mais sobre a classe SessionConfiguration.

    this.cloudSession.Configuration.AccountKey = @"MyAccountKey";

Tokens de acesso

Tokens de acesso são um método mais robusto para autenticar com Âncoras Espaciais do Azure. Isso é válido especialmente à medida que você prepara seu aplicativo para uma implantação de produção. O resumo dessa abordagem é configurar um serviço de back-end com o qual seu aplicativo cliente possa se autenticar com segurança. O serviço de back-end interage com o AAD em runtime e com o serviço de token de Âncoras Espaciais do Azure para solicitar um token de acesso. Esse token é então entregue ao aplicativo cliente e usado no SDK para autenticar com as Âncoras Espaciais do Azure.

    this.cloudSession.Configuration.AccessToken = @"MyAccessToken";

Se um token de acesso não estiver definido, você deverá manipular o evento TokenRequired ou implementar o método tokenRequired no protocolo delegado.

Você pode manipular o evento de maneira síncrona definindo a propriedade nos argumentos do evento.

Saiba mais sobre o delegado TokenRequiredDelegate.

    this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
    {
        args.AccessToken = @"MyAccessToken";
    };

Se precisar executar o trabalho assíncrono em seu manipulador, você poderá adiar a configuração do token solicitando um objeto deferral e depois concluindo-o, como no exemplo a seguir.

    this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
    {
        var deferral = args.GetDeferral();
        string myToken = await MyGetTokenAsync();
        if (myToken != null) args.AccessToken = myToken;
        deferral.Complete();
    };

autenticação do Microsoft Entra

As Âncoras Espaciais do Azure também permitem que os aplicativos se autentiquem com tokens do Microsoft Entra ID (Active Directory). Por exemplo, você pode usar tokens do Microsoft Entra para se integrar ao serviço Âncoras Espaciais do Azure. Se uma empresa mantiver usuários no Microsoft Entra ID, você poderá fornecer um token de usuário do Microsoft Entra no SDK do Âncoras Espaciais do Azure. Isso permite que você se autentique diretamente no serviço Âncoras Espaciais do Azure para uma conta que faz parte do mesmo locatário do Microsoft Entra.

    this.cloudSession.Configuration.AuthenticationToken = @"MyAuthenticationToken";

Assim como acontece com tokens de acesso, se um token do Microsoft Entra não estiver definido, você deverá manipular o evento TokenRequired ou implementar o método tokenRequired no protocolo delegado.

Você pode manipular o evento de maneira síncrona definindo a propriedade nos argumentos do evento.

    this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
    {
        args.AuthenticationToken = @"MyAuthenticationToken";
    };

Se precisar executar o trabalho assíncrono em seu manipulador, você poderá adiar a configuração do token solicitando um objeto deferral e depois concluindo-o, como no exemplo a seguir.

    this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
    {
        var deferral = args.GetDeferral();
        string myToken = await MyGetTokenAsync();
        if (myToken != null) args.AuthenticationToken = myToken;
        deferral.Complete();
    };

Configurar a sessão

Invoque Start() para habilitar sua sessão a processar os dados do ambiente.

Para manipular eventos gerados pela sua sessão, anexe um manipulador de eventos.

Saiba mais sobre o método Start.

#if UNITY_ANDROID || UNITY_IOS
    this.cloudSession.Session = aRSession.subsystem.nativePtr.GetPlatformPointer();
#elif UNITY_WSA || WINDOWS_UWP
    // No need to set a native session pointer for HoloLens.
#else
    throw new NotSupportedException("The platform is not supported.");
#endif

    this.cloudSession.Start();

Fornecer quadros para a sessão

A sessão de âncora espacial funciona pelo mapeamento do espaço em torno do usuário. Fazer isso ajuda a determinar o local em que se encontram as âncoras. As plataformas móveis (iOS e Android) exigem uma chamada nativa ao feed da câmera para obter quadros da biblioteca RA da plataforma. Por outro lado, o HoloLens examina constantemente o ambiente e, portanto, não há necessidade de uma chamada específica como em plataformas móveis.

Saiba mais sobre o método ProcessFrame.

#if UNITY_ANDROID || UNITY_IOS
    XRCameraFrame xRCameraFrame;
    if (aRCameraManager.subsystem.TryGetLatestFrame(cameraParams, out xRCameraFrame))
    {
        long latestFrameTimeStamp = xRCameraFrame.timestampNs;

        bool newFrameToProcess = latestFrameTimeStamp > lastFrameProcessedTimeStamp;

        if (newFrameToProcess)
        {
            session.ProcessFrame(xRCameraFrame.nativePtr.GetPlatformPointer());
            lastFrameProcessedTimeStamp = latestFrameTimeStamp;
        }
    }
#endif

Fornecer comentários ao usuário

Você pode escrever um código para processar o evento atualizado da sessão. Esse evento é acionado toda vez que a sessão aprimora a compreensão do ambiente em que você está. Essa ação permite que você:

  • Use a classe UserFeedback para fornecer comentários ao usuário à medida que o dispositivo for movido e a sessão atualizar a compreensão do ambiente. Para fazer isso,
  • Determine em que ponto há dados espaciais controlados suficientes para criar âncoras espaciais. Determine isso com ReadyForCreateProgress ou RecommendedForCreateProgress. Depois que ReadyForCreateProgress estiver acima de 1, teremos dados suficientes para salvar uma âncora espacial de nuvem, embora recomendemos aguardar até que RecommendedForCreateProgress esteja acima de 1 para fazer isso.

Saiba mais sobre o delegado SessionUpdatedDelegate.

    this.cloudSession.SessionUpdated += (object sender, SessionUpdatedEventArgs args) =>
    {
        var status = args.Status;
        if (status.UserFeedback == SessionUserFeedback.None) return;
        this.feedback = $"Feedback: {Enum.GetName(typeof(SessionUserFeedback), status.UserFeedback)} -" +
            $" Recommend Create={status.RecommendedForCreateProgress: 0.#%}";
    };

Criar uma âncora espacial de nuvem

Para criar uma âncora espacial de nuvem, primeiro crie uma âncora no sistema RA da plataforma e, em seguida, crie um equivalente na nuvem. Use o método CreateAnchorAsync().

Saiba mais sobre a classe CloudSpatialAnchor.

    // Create a local anchor, perhaps by hit-testing and spawning an object within the scene
    Vector3 hitPosition = new Vector3();
#if UNITY_ANDROID || UNITY_IOS
    Vector2 screenCenter = new Vector2(0.5f, 0.5f);
    List<ARRaycastHit> aRRaycastHits = new List<ARRaycastHit>();
    if(arRaycastManager.Raycast(screenCenter, aRRaycastHits) && aRRaycastHits.Count > 0)
    {
        ARRaycastHit hit = aRRaycastHits[0];
        hitPosition = hit.pose.position;
    }
#elif WINDOWS_UWP || UNITY_WSA
    RaycastHit hit;
    if (this.TryGazeHitTest(out hit))
    {
        hitPosition = hit.point;
    }
#endif

    Quaternion rotation = Quaternion.AngleAxis(0, Vector3.up);
    this.localAnchor = GameObject.Instantiate(/* some prefab */, hitPosition, rotation);
    this.localAnchor.AddComponent<CloudNativeAnchor>();

    // 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.
    CloudNativeAnchor cloudNativeAnchor = this.localAnchor.GetComponent<CloudNativeAnchor>();
    if (cloudNativeAnchor.CloudAnchor == null) { await cloudNativeAnchor.NativeToCloud(); }  
    CloudSpatialAnchor cloudAnchor = cloudNativeAnchor.CloudAnchor;
    await this.cloudSession.CreateAnchorAsync(cloudAnchor);
    this.feedback = $"Created a cloud anchor with ID={cloudAnchor.Identifier}");

Conforme descrito anteriormente, você precisará ter dados do ambiente suficientes capturados antes de tentar criar uma âncora espacial de nuvem. Isso significa que ReadyForCreateProgress precisa estar acima de 1, embora recomendemos aguardar até que RecommendedForCreateProgress esteja acima de 1 para fazer isso.

Saiba mais sobre o método GetSessionStatusAsync.

    SessionStatus value = await this.cloudSession.GetSessionStatusAsync();
    if (value.RecommendedForCreateProgress < 1.0f) return;
    // Issue the creation request ...

Definir propriedades

Você pode optar por adicionar algumas propriedades ao salvar suas âncoras espaciais de nuvem. Como o tipo de objeto que está sendo salvo ou as propriedades básicas, como se elas devem ser habilitadas para interação. Fazer isso pode ser útil na descoberta: você pode renderizar imediatamente o objeto para o usuário, por exemplo, um quadro de imagem com o conteúdo em branco. Em seguida, um download diferente em segundo plano obtém detalhes de estado adicionais, por exemplo, a imagem a ser exibida no quadro.

Saiba mais sobre a propriedade AppProperties.

    CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor() { LocalAnchor = localAnchor };
    cloudAnchor.AppProperties[@"model-type"] = @"frame";
    cloudAnchor.AppProperties[@"label"] = @"my latest picture";
    await this.cloudSession.CreateAnchorAsync(cloudAnchor);

Atualizar as propriedades

Para atualizar as propriedades em uma âncora, use o método UpdateAnchorProperties(). Se dois ou mais dispositivos tentarem atualizar as propriedades para a mesma âncora ao mesmo tempo, usaremos um modelo de simultaneidade otimista. Ou seja, a primeira gravação ganhará. Todas as outras gravações receberão um erro de "Simultaneidade": uma atualização das propriedades será necessária antes que seja possível tentar novamente.

Saiba mais sobre o método UpdateAnchorPropertiesAsync.

    CloudSpatialAnchor anchor = /* locate your anchor */;
    anchor.AppProperties[@"last-user-access"] = @"just now";
    await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);

Não é possível atualizar o local de uma âncora após ela ter sido criada no serviço: você precisa criar uma âncora e excluir a antiga para acompanhar uma nova posição.

Se você não precisar localizar uma âncora para atualizar as propriedades dela, poderá usar o método GetAnchorPropertiesAsync(), que retorna um objeto CloudSpatialAnchor com propriedades.

Saiba mais sobre o método GetAnchorPropertiesAsync.

    var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
    if (anchor != null)
    {
        anchor.AppProperties[@"last-user-access"] = @"just now";
        await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);
    }

Definir a validade

Também é possível configurar sua âncora para expirar automaticamente em uma determinada data no futuro. Quando uma âncora expirar, ela não será mais localizada nem atualizada. A expiração só pode ser definida quando a âncora é criada, antes de salvá-la na nuvem. Não é possível atualizar a expiração posteriormente. Se nenhuma expiração for definida durante a criação da âncora, a âncora só expirará quando excluída manualmente.

Saiba mais sobre a propriedade Expiration.

    cloudAnchor.Expiration = DateTimeOffset.Now.AddDays(7);

Localizar uma âncora espacial de nuvem

Ser capaz de localizar uma âncora espacial de nuvem salva anteriormente é um dos principais motivos para usar as Âncoras Espaciais do Azure. Para isso, estamos usando "Observadores". Você só pode usar um Observador por vez; não há suporte para vários Observadores. Há várias maneiras diferentes (também conhecidas como Estratégias de Localização de Âncora) para um Observador localizar uma âncora espacial de nuvem. Você pode usar uma estratégia em um observador por vez.

  • Localizar âncoras por identificador.
  • Localizar âncoras conectadas a uma âncora localizada anteriormente. Saiba mais sobre as relações entre âncoras aqui.
  • Localizar âncora usando a Relocalização grosseira.

Observação

Cada vez que você localizar uma âncora, as Âncoras Espaciais do Azure tentarão usar os dados do ambiente coletados para aumentar as informações visuais na âncora. Se você tiver problemas para localizar uma âncora, poderá ser útil criar uma âncora e, em seguida, localizá-la várias vezes de diferentes ângulos e condições de iluminação.

Se estiver localizando âncoras espaciais de nuvem por identificador, você poderá armazenar o identificador da âncora espacial de nuvem no serviço de back-end do seu aplicativo e torná-lo acessível para todos os dispositivos que puderem se autenticar a ele corretamente. Para ver um exemplo disso, confira Tutorial: Compartilhar âncoras espaciais entre dispositivos.

Crie uma instância de um objeto AnchorLocateCriteria, defina os identificadores que está procurando e invoque o método CreateWatcher na sessão fornecendo seu AnchorLocateCriteria.

Saiba mais sobre o método CreateWatcher.

    AnchorLocateCriteria criteria = new AnchorLocateCriteria();
    criteria.Identifiers = new string[] { @"id1", @"id2", @"id3" };
    this.cloudSession.CreateWatcher(criteria);

Depois que o observador for criado, o evento AnchorLocated será acionado para cada âncora solicitada. Esse evento é acionado quando uma âncora é localizada ou se a âncora não puder ser localizada. Se essa situação ocorrer, o motivo será indicado no status. Após todas as âncoras de um observador serem processadas, sejam elas encontradas ou não, o evento LocateAnchorsCompleted será acionado. Há um limite de 35 identificadores por observador.

Saiba mais sobre o delegado AnchorLocatedDelegate.

    this.cloudSession.AnchorLocated += (object sender, AnchorLocatedEventArgs args) =>
    {
        switch (args.Status)
        {
            case LocateAnchorStatus.Located:
                CloudSpatialAnchor foundAnchor = args.Anchor;
                // Go add your anchor to the scene...
                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;
        }
    }

Excluir âncoras

Excluir âncoras quando elas não forem mais usadas é uma boa prática para incluir no início do seu processo e práticas de desenvolvimento para manter os recursos do Azure limpos.

Saiba mais sobre o método DeleteAnchorAsync.

    await this.cloudSession.DeleteAnchorAsync(cloudAnchor);
    // Perform any processing you may want when delete finishes

Excluir âncora sem localizar

Se você não consegue localizar uma âncora, mas ainda quer excluí-la, use a API GetAnchorPropertiesAsync, que usa anchorId como entrada, para obter o objeto CloudSpatialAnchor. Depois, você pode passar esse objeto para DeleteAnchorAsync e excluí-lo.

var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
await this.cloudSession.DeleteAnchorAsync(anchor);

Pausar, redefinir ou interromper a sessão

Para interromper a sessão temporariamente, você pode invocar Stop(). Isso interromperá inspetores e o processamento de ambiente, mesmo se você invocar ProcessFrame(). Em seguida, você pode invocar Start() para retomar o processamento. Ao retomar, os dados de ambiente já capturados na sessão são mantidos.

Saiba mais sobre o método Stop.

    this.cloudSession.Stop();

Para redefinir os dados de ambiente que foram capturados em sua sessão, você pode invocar Reset().

Saiba mais sobre o método Reset.

    this.cloudSession.Reset();

Para realizar a limpeza corretamente após uma sessão, invoque Dispose().

Saiba mais sobre o método Dispose.

    this.cloudSession.Dispose();

Próximas etapas

Neste guia, você aprendeu sobre como criar e localizar âncoras usando o SDK das Âncoras Espaciais do Azure. Para saber mais sobre os relacionamentos de âncora, vá para o próximo guia.

Relacionamentos de âncora