Como criar e localizar âncoras usando as Âncoras Espaciais do Azure em C++/WinRT

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

As Âncoras Espaciais do Azure permitem-lhe partilhar âncoras no mundo entre diferentes dispositivos. Ele suporta vários ambientes de desenvolvimento diferentes. Neste artigo, vamos nos aprofundar em como usar o SDK do Azure Spatial Anchors, em C++/WinRT, para:

• Configure e gerencie corretamente uma sessão de Âncoras Espaciais do Azure.
• Crie e defina propriedades em âncoras locais.
• Carregue-os para a nuvem.
• Localize e exclua âncoras espaciais da nuvem.

Pré-requisitos

Para completar este guia, certifique-se de:

• Leia a visão geral das Âncoras Espaciais do Azure.
• Completou um dos Quickstarts de 5 minutos.
• Conhecimento básico em C++ e APIs do Tempo de Execução do Windows.

Inicializar a sessão

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

Saiba mais sobre a classe CloudSpatialAnchorSession .

    CloudSpatialAnchorSession m_cloudSession{ nullptr };

    m_cloudSession = CloudSpatialAnchorSession();

Configurar a autenticação

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

Chaves de conta

As Chaves de Conta são uma credencial que permite que seu aplicativo se autentique com o serviço Âncoras Espaciais do Azure. O objetivo pretendido das Chaves de Conta é ajudá-lo a começar rapidamente. Especialmente durante a fase de desenvolvimento da integração do seu aplicativo com as Âncoras Espaciais do Azure. Como tal, você pode usar chaves de conta incorporando-as em seus aplicativos cliente durante o desenvolvimento. À medida que você avança além do desenvolvimento, é altamente recomendável mudar para um mecanismo de autenticação de nível de produção, suportado por Tokens de Acesso ou autenticação de usuário do Microsoft Entra. Para obter uma Chave de Conta para desenvolvimento, visite sua conta do Azure Spatial Anchors e navegue até a guia "Chaves".

Saiba mais sobre a classe SessionConfiguration .

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

Tokens de Acesso

Os Tokens de Acesso são um método mais robusto para autenticar com as Âncoras Espaciais do Azure. Especialmente enquanto você prepara seu aplicativo para uma implantação de produção. O resumo dessa abordagem é configurar um serviço back-end com o qual seu aplicativo cliente possa autenticar com segurança. Seu serviço back-end faz interface com o AAD em tempo de execução e com o Serviço de Token Seguro 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.

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

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

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

Saiba mais sobre o delegado TokenRequiredDelegate .

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

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

    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();
        });
    });

Autenticação do Microsoft Entra

As Âncoras Espaciais do Azure também permitem que os aplicativos se autentiquem com tokens de ID do Microsoft Entra (Ative Directory) do usuário. Por exemplo, você pode usar tokens do Microsoft Entra para integrar com as Âncoras Espaciais do Azure. Se uma Empresa mantiver usuários na ID do Microsoft Entra, você poderá fornecer um token do Microsoft Entra de usuário no SDK do Azure Spatial Anchors. 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.

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

Como acontece com os 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 forma síncrona definindo a propriedade nos argumentos do evento.

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

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

    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();
        });
    });

Configurar a sessão

Invoque Start() para permitir que sua sessão processe dados do ambiente.

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

Saiba mais sobre o método Start .

    m_cloudSession.Start();

Fornecer quadros para a sessão

A sessão de âncora espacial funciona mapeando o espaço ao redor do usuário. Isso ajuda a determinar onde as âncoras estão localizadas. As plataformas móveis (iOS ou Android) exigem uma chamada nativa para o feed da câmera para obter quadros da biblioteca de RA da sua plataforma. Em contraste, o HoloLens está constantemente verificando o ambiente, portanto, não há necessidade de uma chamada específica, como em plataformas móveis.

Saiba mais sobre o método ProcessFrame .

    m_cloudSession->ProcessFrame(ar_frame_);

Fornecer feedback ao utilizador

Você pode escrever código para manipular o evento atualizado da sessão. Este evento é acionado sempre que a sessão melhora a sua compreensão do que o rodeia. Ao fazê-lo, permite-lhe:

• Use a classe para fornecer feedback ao usuário à medida que o dispositivo se move e a UserFeedback sessão atualiza sua compreensão do ambiente. Para tal,
• Determine em que ponto há dados espaciais rastreados suficientes para criar âncoras espaciais. Você determina isso com um ou ReadyForCreateProgressRecommendedForCreateProgress. Uma vez ReadyForCreateProgress acima de 1, temos dados suficientes para salvar uma âncora espacial da nuvem, embora recomendemos que você espere até RecommendedForCreateProgress que esteja acima de 1 para fazê-lo.

Saiba mais sobre o 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);
    });

Criar uma âncora espacial na nuvem

Para criar uma âncora espacial na nuvem, primeiro crie uma âncora no sistema de RA da sua plataforma e, em seguida, crie uma contraparte na nuvem. Você usa o CreateAnchorAsync() método.

Saiba mais sobre a classe 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();

Conforme descrito anteriormente, você precisa de dados de ambiente suficientes capturados antes de tentar criar uma nova âncora espacial na nuvem. Isso significa ReadyForCreateProgress que tem que estar acima de 1, embora recomendemos que você espere até RecommendedForCreateProgress estar acima de 1 para fazê-lo.

Saiba mais sobre o método GetSessionStatusAsync .

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

Definir as propriedades

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

Saiba mais sobre o 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);

Atualizar propriedades

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

Saiba mais sobre o método UpdateAnchorPropertiesAsync .

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

Você não pode atualizar o local de uma âncora depois que ela tiver sido criada no serviço - você deve criar uma nova âncora e excluir a antiga para rastrear uma nova posição.

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

Saiba mais sobre o 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);
    }

Definir expiração

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 ou 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 o método de validade .

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

Localizar uma âncora espacial na 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 "Watchers". Você só pode usar um Observador de cada vez; vários Observadores não são suportados. Existem várias maneiras diferentes (também conhecidas como Anchor Locate Strategies) de um Observador localizar uma âncora espacial na nuvem. Você pode usar uma estratégia em um observador de cada vez.

• Localize âncoras por identificador.
• Localize âncoras conectadas a uma âncora localizada anteriormente. Você pode aprender sobre relacionamentos âncora aqui.
• Localize a âncora usando a relocalização grosseira.

Nota

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

Se você estiver localizando âncoras espaciais na nuvem por identificador, poderá armazenar o identificador de âncora espacial na nuvem no serviço de back-end do seu aplicativo e torná-lo acessível a todos os dispositivos que possam autenticá-lo corretamente. Para obter um exemplo disso, consulte Tutorial: Compartilhar âncoras espaciais entre dispositivos.

Instancie um AnchorLocateCriteria objeto, defina os identificadores que você está procurando e invoque o método na sessão fornecendo AnchorLocateCriteriaseu CreateWatcher arquivo .

Saiba mais sobre o método CreateWatcher .

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

Depois que o observador for criado, o evento será acionado para cada âncora AnchorLocated solicitada. Esse evento é acionado quando uma âncora está localizada ou se a âncora não pode ser localizada. Se esta situação acontecer, o motivo será indicado no estado. Depois que todas as âncoras de um observador forem processadas, encontradas ou não encontradas, o LocateAnchorsCompleted evento será acionado. Há um limite de 35 identificadores por observador.

Saiba mais sobre o 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;
        }
    });

Excluir âncoras

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

Saiba mais sobre o método DeleteAnchorAsync .

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

Pausar, redefinir ou parar a sessão

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

Saiba mais sobre o método Stop .

    m_cloudSession.Stop();

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

Saiba mais sobre o método Reset .

    m_cloudSession.Reset();

Para limpar corretamente após uma sessão, libere todas as referências.

    m_cloudSession = nullptr;

Próximos passos

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

Relações âncora