Âncoras Espaciais do Azure no UnrealAzure Spatial Anchors in Unreal

Visão geralOverview

As Âncoras Espaciais do Azure são um serviço de Realidade Misturada da Microsoft, permitindo que dispositivos de realidade aumentada descubram, compartilhem e persistam pontos de ancoragem no mundo físico.Azure Spatial Anchors is a Microsoft Mixed Reality service, allowing augmented reality devices to discover, share, and persist anchor points in the physical world. A documentação abaixo fornece instruções para integrar o serviço Âncoras Espaciais do Azure a um projeto do Unreal.Documentation below provides instructions for integrating the Azure Spatial Anchors service into an Unreal project. Se estiver buscando mais informações, confira o serviço Âncoras Espaciais do Azure.If you're looking for more information, check out the Azure Spatial Anchors service.

Importante

As âncoras locais são armazenadas no dispositivo, enquanto as Âncoras Espaciais do Azure são armazenadas na nuvem.Local anchors are stored on device, while Azure Spatial Anchors are stored in the cloud. Se você está buscando armazenar suas âncoras localmente em um dispositivo, temos um documento Âncoras Espaciais locais que pode orientar você no processo.If you're looking to store your anchors locally on a device, we have a Local Spatial Anchors document that can walk you through the process. Você pode ter âncoras locais e do Azure no mesmo projeto sem conflitos.Note that you can have local and Azure anchors in the same project without conflict.

Pré-requisitosPrerequisites

Para concluir este guia, verifique se você:To complete this guide, make sure you have:

Como obter informações da conta das Âncoras Espaciais do AzureGetting Azure Spatial Anchors account info

Para usar as Âncoras Espaciais do Azure no seu projeto, você precisará:Before using Azure Spatial Anchors in your project, you need to:

  • Criar um recurso de âncoras espaciais e copiar os campos da conta listados abaixo.Create a spatial anchors resource and copy the account fields listed below. Esses valores são usados para autenticar os usuários na conta do seu aplicativo:These values are used to authenticate users with your application's account:
    • ID da ContaAccount ID
    • Chave de ContaAccount Key

Confira a documentação Autenticação das Âncoras Espaciais do Azure para obter mais informações.Check out the Azure Spatial Anchors authentication docs for more information.

Observação

As Âncoras Espaciais do Azure no Unreal 4.25 não dão suporte a tokens de autenticação do Azure AD, mas o suporte para essa funcionalidade será disponibilizado em uma versão posterior.Azure Spatial Anchors in Unreal 4.25 does not support Azure AD authentication tokens, but support for this functionality will be coming in a later release.

Como adicionar plug-ins das Âncoras Espaciais do AzureAdding Azure Spatial Anchors plugins

Habilite os plug-ins das Âncoras Espaciais do Azure no editor do Unreal:Enable the Azure Spatial Anchors plugins in the Unreal editor by:

  1. Clicando em Editar > Plug-ins e procurando AzureSpatialAnchors e AzureSpatialAnchorsForWMR .Clicking Edit > Plugins and searching for AzureSpatialAnchors and AzureSpatialAnchorsForWMR .
  2. Marque a caixa de seleção Habilitado nos dois plug-ins para permitir o acesso às bibliotecas de blueprints das Âncoras Espaciais do Azure no seu aplicativo.Select the Enabled checkbox in both plugins to allow access to the Azure Spatial Anchors blueprint libraries in your application.

Plug-ins das Âncoras Espaciais

Depois disso, reinicie o editor do Unreal para que as alterações do plug-in entrem em vigor.Once that's done, restart the Unreal Editor for the plugin changes to take effect. Agora, o projeto está pronto para usar as Âncoras Espaciais do Azure.The project is now ready to use Azure Spatial Anchors.

Como iniciar uma sessão das Âncoras EspaciaisStarting a Spatial Anchors session

Uma sessão das Âncoras Espaciais do Azure permite que os aplicativos cliente se comuniquem com o serviço Âncoras Espaciais do Azure.An Azure Spatial Anchors session allows client applications to communicate with the Azure Spatial Anchors service. Você precisará criar e iniciar uma sessão das Âncoras Espaciais do Azure para criar, persistir e compartilhar as Âncoras Espaciais do Azure:You'll need to create and start an Azure Spatial Anchors session to create, persist, and share Azure Spatial Anchors:

  1. Abra o blueprint do Peão que você está usando no aplicativo.Open the blueprint for the Pawn you're using in the application.
  2. Adicione duas variáveis de cadeia de caracteres à ID da Conta e à Chave de Conta e atribua os valores correspondentes da sua conta das Âncoras Espaciais do Azure para autenticar a sessão.Add two string variables for the Account ID and Account Key , then assign the corresponding values from your Azure Spatial Anchors account to authenticate the session.

Plug-ins das Âncoras Espaciais

Inicie uma sessão das Âncoras Espaciais do Azure:Start an Azure Spatial Anchors session by:

  1. Verificando se uma Sessão de AR está em execução no aplicativo do HoloLens, pois a sessão das Âncoras Espaciais do Azure não pode ser iniciada até que uma Sessão de AR esteja em execução.Checking that an AR Session is running in the HoloLens application, as the Azure Spatial Anchors session can't start until an AR Session is running. Se você não tiver uma configuração, crie um ativo da Sessão de AR.If you don't have one setup, create an AR Session asset.
  2. Adicionando o evento personalizado Iniciar Sessão das Âncoras Espaciais do Azure e configurando-o conforme mostrado na captura de tela abaixo.Adding the Start Azure Spatial Anchors Session custom event and configure it as shown in the screenshot below.
    • A criação de uma sessão não inicia a sessão por padrão, o que permite ao desenvolvedor configurar a sessão para autenticação no serviço Âncoras Espaciais do Azure.Creating a session doesn't start the session by default, which allows the developer to configure the session for authentication with the Azure Spatial Anchors service.

Plug-ins das Âncoras Espaciais

  1. Configure a sessão das Âncoras Espaciais do Azure para fornecer a ID da Conta e a Chave de Conta .Configure the Azure Spatial Anchors session to provide the Account ID and Account Key .

Plug-ins das Âncoras Espaciais

  1. Inicie a sessão das Âncoras Espaciais do Azure, permitindo que o aplicativo crie e localize as Âncoras Espaciais do Azure.Start the Azure Spatial Anchors session, allowing the application to create and locate Azure Spatial Anchors.

Plug-ins das Âncoras Espaciais

Será uma boa prática limpar os recursos das Âncoras Espaciais do Azure no blueprint do Grafo de Eventos quando você não estiver mais usando o serviço:It's good practice to clean up Azure Spatial Anchors resources in your Event Graph blueprint when you're no longer using the service:

  1. Interrompa a sessão das Âncoras Espaciais do Azure.Stop the Azure Spatial Anchors session. A sessão não estará mais em execução, mas os respectivos recursos associados ainda existirão no plug-in das Âncoras Espaciais do Azure.The session will no longer be running, but its associated resources will still exist in the Azure Spatial Anchors plugin.

Plug-ins das Âncoras Espaciais

  1. Destrua a sessão das Âncoras Espaciais do Azure para limpar os recursos da sessão das Âncoras Espaciais do Azure ainda conhecidos pelo plug-in das Âncoras Espaciais do Azure.Destroy the Azure Spatial Anchors session to clean up any Azure Spatial Anchors session resources still known to the Azure Spatial Anchors plugin.

Plug-ins das Âncoras Espaciais

O blueprint do Grafo de Eventos será parecido com a captura de tela abaixo:Your Event Graph blueprint should look like the screenshot below:

Plug-ins das Âncoras Espaciais

Como criar uma âncoraCreating an anchor

Uma Âncora Espacial do Azure representa uma pose do mundo físico no espaço do aplicativo de realidade aumentada, que bloqueia o conteúdo de realidade aumentada em localizações do mundo físico.An Azure Spatial Anchor represents a physical world pose in the augmented reality application space, which locks augmented reality content to locations in the physical world. As Âncoras Espaciais do Azure também podem ser compartilhadas entre diferentes usuários.Azure Spatial Anchors can also be shared among different users. Esse compartilhamento permite que o conteúdo de realidade aumentada desenhado em diferentes dispositivos seja posicionado na mesma localização no mundo físico.This sharing allows augmented reality content drawn on different devices to be positioned in the same location in the physical world.

Para criar uma Âncora Espacial do Azure:To create a new Azure Spatial Anchor:

  1. Verifique se uma sessão das Âncoras Espaciais do Azure está em execução.Check that an Azure Spatial Anchors session is running. O aplicativo não pode criar nem manter uma Âncora Espacial do Azure quando não há nenhuma sessão das Âncoras Espaciais do Azure em execução.The application can't create or persist an Azure Spatial Anchor when no Azure Spatial Anchors session is running.

Plug-ins das Âncoras Espaciais

  1. Crie ou obtenha um Componente de Cena do Unreal que deve ter a localização persistente.Create or obtain an Unreal Scene Component that should have its location persisted.
    • Na imagem abaixo, o componente Âncora que Precisa de um Componente de Cena é usado como uma variável.In the below image, the Scene Component Needing Anchor component is used as a variable. Um Componente de Cena do Unreal é necessário para estabelecer uma transformação do mundo do aplicativo em um Marcador de AR e uma Âncora Espacial do Azure.An Unreal Scene Component is needed to establish an application world transform for an AR Pin and Azure Spatial Anchor.

Plug-ins das Âncoras Espaciais

Para construir e salvar uma Âncora Espacial do Azure de um Componente de Cena do Unreal:To construct and save an Azure Spatial Anchor for an Unreal Scene Component:

  1. Chame o Componente de Marcador para o Componente de Cena do Unreal e especifique a Transformação do Mundo do Componente de Cena como a Transformação do Mundo usada para o Marcador de AR.Call the Pin Component for the Unreal Scene Component and specify the Scene Component's World Transform as the World Transform used for the AR Pin.
    • O Unreal acompanha os pontos de AR no espaço do aplicativo usando Marcadores de AR, que são usados para criar uma Âncora Espacial do Azure.Unreal tracks AR points in the application space using AR Pins, which are used to create an Azure Spatial Anchor. No Unreal, um Marcador de AR é similar a uma SpatialAnchor no HoloLens.In Unreal, an AR Pin is analogous to a SpatialAnchor on HoloLens.

Plug-ins das Âncoras Espaciais

  1. Chame Criar Âncora de Nuvem usando o Marcador de AR recém-criado.Call Create Cloud Anchor using the newly created AR Pin.
    • A função Criar Âncora de Nuvem cria uma Âncora Espacial do Azure localmente, mas não no serviço Âncora Espacial do Azure.Create Cloud Anchor creates an Azure Spatial Anchor locally but not in the Azure Spatial Anchor service. Os parâmetros para a Âncora Espacial do Azure, como uma data de validade, podem ser definidos antes da criação da Âncora Espacial do Azure com o serviço.Parameters for the Azure Spatial Anchor, such as an expiration date, can be set before creating the Azure Spatial Anchor with the service.

Plug-ins das Âncoras Espaciais

  1. Defina a validade da Âncora Espacial do Azure.Set the Azure Spatial Anchor expiration. O parâmetro Tempo de Vida da função permite que o desenvolvedor especifique, em segundos, quanto tempo a âncora deve ser mantida pelo serviço.This function's Lifetime parameter allows the developer to specify in seconds how long the anchor should be maintained by the service.
    • Por exemplo, uma validade de uma semana usará um valor igual a 60 segundos x 60 minutos x 24 horas x sete dias = 604.800 segundos.For example, a week long expiration would take a value of 60 seconds x 60 minutes x 24 hours x seven days = 604,800 seconds.

Plug-ins das Âncoras Espaciais

Depois de definir os parâmetros de âncora, declare a âncora como pronta para ser salva.After setting anchor parameters, declare the anchor as ready to save. No exemplo abaixo, a Âncora Espacial recém-criada do Azure é adicionada a um conjunto das Âncoras Espaciais do Azure que precisam ser salvas.In the example below, the newly created Azure Spatial Anchor is added to a set of Azure Spatial Anchors needing saving. Esse conjunto é declarado como uma variável do blueprint de Peão.This set is declared as a variable for the Pawn blueprint.

Plug-ins das Âncoras Espaciais

Como salvar uma âncoraSaving an Anchor

Depois de configurar a Âncora Espacial do Azure com os parâmetros, chame a função Salvar Âncora de Nuvem .After configuring the Azure Spatial Anchor with your parameters, call Save Cloud Anchor . A função Salvar âncora de Nuvem declara a âncora para o serviço Âncoras Espaciais do Azure.Save Cloud Anchor declares the anchor to the Azure Spatial Anchors service. Quando a chamada a Salvar Âncora de Nuvem for realizada com sucesso, a Âncora Espacial do Azure estará disponível para outros usuários do serviço Âncora Espacial do Azure.When the call to Save Cloud Anchor succeeds, the Azure Spatial Anchor is available to other users of the Azure Spatial Anchor service.

Plug-ins das Âncoras Espaciais

Observação

A função Salvar Âncora de Nuvem é assíncrona e só pode ser chamada em um evento de thread de jogo, como EventTick .Save Cloud Anchor is an asynchronous function and can only be called on a game thread event such as EventTick . Talvez a função Salvar Âncora de Nuvem não seja exibida como uma função de blueprint disponível nas funções de blueprint personalizadas.Save Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. No entanto, ela deve estar disponível no editor de blueprint do Grafo de Eventos do Peão.However, it should be available in the Pawn Event Graph blueprint editor.

No exemplo abaixo, a Âncora Espacial do Azure é armazenada em um conjunto durante um retorno de chamada de evento de entrada.In the example below, the Azure Spatial Anchor is stored in a set during an input event callback. Em seguida, a âncora é salva no EventTick.The anchor is then saved on the EventTick. Para salvar uma Âncora Espacial do Azure, podem ser necessárias várias tentativas dependendo do volume de dados espaciais criado pela sessão das Âncoras Espaciais do Azure.Saving an Azure Spatial Anchor may take multiple attempts depending on the amount of spatial data that your Azure Spatial Anchors session has created. Por esse motivo, é uma boa ideia verificar se a chamada de salvamento foi bem-sucedida.That's why it's a good idea to check whether the save call succeeded.

Se a âncora não for salva, adicione-a novamente ao conjunto de âncoras que ainda precisa ser salvo.If the anchor doesn't save, re-add it to the set of anchors still needing to be saved. Os EventTicks futuros tentarão salvar a âncora até que ela seja armazenada com êxito no serviço Âncora Espacial do Azure.Future EventTicks will try to save the anchor until it's successfully stored in the Azure Spatial Anchor service.

Plug-ins das Âncoras Espaciais

Depois que a âncora for salva, use a transformação de Marcadores de AR como uma transformação de referência para colocar conteúdo no aplicativo.Once the anchor saves, you can use the AR Pins' transform as a reference transform for placing content in the application. Outros usuários podem detectar essa âncora e alinhar o conteúdo de AR para diferentes dispositivos no mundo físico.Other users can detect this anchor and align AR content for different devices in the physical world.

Como excluir uma âncoraDeleting an Anchor

Exclua âncoras do serviço Âncora Espacial do Azure chamando Excluir Âncora de Nuvem .You can delete anchors from the Azure Spatial Anchor service by calling Delete Cloud Anchor .

Plug-ins das Âncoras Espaciais

Observação

A função Excluir Âncora de Nuvem é latente e só pode ser chamada em um evento de thread de jogo, como EventTick.Delete Cloud Anchor is a latent function and can only be called on a game thread event, such as EventTick. Talvez a função Excluir Âncora de Nuvem não seja exibida como uma função de blueprint disponível nas funções de blueprint personalizadas.Delete Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. No entanto, ela deve estar disponível no editor de blueprint do Grafo de Eventos de Peão.It should however be available in the Pawn Event Graph blueprint editor.

No exemplo abaixo, a âncora é sinalizada para exclusão em um evento de entrada personalizado.In the example below, the anchor is flagged for deletion on a custom input event. Em seguida, é feita a tentativa de exclusão no EventTick.The deletion is then attempted on the EventTick. Se a exclusão da âncora falhar, adicione a Âncora Espacial do Azure ao conjunto de âncoras sinalizadas para exclusão e tente novamente em EventTicks posteriores.If the anchor deletion fails, add the Azure Spatial Anchor to the set of anchors flagged for deletion and tries again on later EventTicks.

Agora, o blueprint do Grafo de Eventos será parecido com a captura de tela abaixo:Your Event Graph blueprint should now look like the screenshot below:

Plug-ins das Âncoras Espaciais

Como localizar âncoras pré-existentesLocating pre-existing anchors

Além de criar Âncoras Espaciais do Azure, você pode detectar âncoras criadas por colegas com o serviço Âncoras Espaciais do Azure:In addition to creating Azure Spatial Anchors, you can detect anchors created by peers with the Azure Spatial Anchors service:

  1. Obtenha um identificador de Âncora Espacial do Azure da âncora que deseja detectar.Obtain an Azure Spatial Anchor identifier for the anchor that you would like to detect.
    • Um identificador de âncora pode ser obtido para uma âncora criada pelo mesmo dispositivo em uma sessão anterior das Âncoras Espaciais do Azure.An anchor identifier can be obtained for an anchor created by the same device in a previous Azure Spatial Anchors session. Ele também pode ser criado e compartilhado por dispositivos pares que interagem com o serviço Âncoras Espaciais do Azure.It can also be created and shared by peer devices interacting with the Azure Spatial Anchors service.

Plug-ins das Âncoras Espaciais

  1. Adicione um componente AzureSpatialAnchorsEvent ao blueprint de Peão.Add an AzureSpatialAnchorsEvent component to your Pawn blueprint.
    • Esse componente permite que você assine vários eventos das Âncoras Espaciais do Azure, como eventos chamados quando as Âncoras Espaciais do Azure são localizadas.This component allows you to subscribe to various Azure Spatial Anchors events, such as events called when Azure Spatial Anchors are located.

Plug-ins das Âncoras Espaciais

  1. Assine o Delegado Localizado de ASAAnchor para o componente AzureSpatialAnchorsEvent .Subscribe to the ASAAnchor Located Delegate for the AzureSpatialAnchorsEvent component.
    • O delegado permite que o aplicativo saiba quando são localizadas novas âncoras associadas à conta das Âncoras Espaciais do Azure.The delegate lets the application know when new anchors associated with the Azure Spatial Anchors account have been located.
    • Com o retorno de chamada do evento, as Âncoras Espaciais do Azure criadas pelos colegas que usam a sessão das Âncoras Espaciais do Azure não terão Marcadores de AR criados por padrão.With the event callback, Azure Spatial Anchors created by peers using the Azure Spatial Anchors session won't have AR Pins created by default. Para criar um Marcador de AR para a Âncora Espacial do Azure detectada, os desenvolvedores podem chamar a função Criar Marcador de RA em Torno da Âncora Espacial de Nuvem do Azure .To create an AR Pin for the detected Azure Spatial Anchor, developers can call Create ARPin Around Azure Cloud Spatial Anchor .

Plug-ins das Âncoras Espaciais

Para localizar Âncoras Espaciais do Azure criadas pelos pares usando o serviço Âncora Espacial do Azure, o aplicativo precisará criar um Observador das Âncoras Espaciais do Azure :In order to locate Azure Spatial Anchors created by peers using the Azure Spatial Anchor service, the application will have to create an Azure Spatial Anchors Watcher :

  1. Verifique se uma sessão das Âncoras Espaciais do Azure está em execução.Check that an Azure Spatial Anchors session is running.
  2. Crie um AzureSpatialAnchorsLocateCriteria .Create an AzureSpatialAnchorsLocateCriteria .
    • Você pode especificar vários parâmetros de localização, como distância do usuário ou distância de outra âncora.You can specify various location parameters like distance from the user or distance from another anchor.
  3. Declare o identificador desejado da Âncora Espacial do Azure em AzureSpatialAnchorsLocateCriteria .Declare your desired Azure Spatial Anchor identifier in the AzureSpatialAnchorsLocateCritieria .
  4. Chame Criar Observador .Call Create Watcher .

Plug-ins das Âncoras Espaciais

Agora, o aplicativo começa a procurar as Âncoras Espaciais do Azure conhecidas pelo serviço Âncoras Espaciais do Azure, o que significa que os usuários podem localizar as Âncoras Espaciais do Azure criadas pelos colegas.The application now begins looking for Azure Spatial Anchors known to the Azure Spatial Anchors service, meaning that users can locate Azure Spatial Anchors created by their peers.

Depois de localizar a Âncora Espacial do Azure, chame a função Parar Observador para interromper o Observador das Âncoras Espaciais do Azure e limpar os recursos do observador.After locating the Azure Spatial Anchor, call Stop Watcher to stop the Azure Spatial Anchors Watcher and clean up watcher resources.

Plug-ins das Âncoras Espaciais

Agora, o blueprint final do Grafo de Eventos será parecido com a captura de tela abaixo:Your final Event Graph blueprint should now look like the screenshot below:

Plug-ins das Âncoras Espaciais

Próximo ponto de verificação de desenvolvimentoNext Development Checkpoint

Se você está seguindo o percurso do ponto de verificação de desenvolvimento do Unreal, você está no meio da exploração dos principais blocos de construção do MRTK.If you're following the Unreal development checkpoint journey we've laid out, you're in the midst of exploring the MRTK core building blocks. De lá, você pode prosseguir para o próximo bloco de construção:From here, you can proceed to the next building block:

Ou vá diretamente para as funcionalidades e APIs da plataforma de Realidade Misturada:Or jump to Mixed Reality platform capabilities and APIs:

Você sempre pode voltar para os pontos de verificação de desenvolvimento do Unreal a qualquer momento.You can always go back to the Unreal development checkpoints at any time.

Próximas etapasNext steps