Âncoras Espaciais do Azure no Unreal

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. A documentação abaixo fornece instruções para integrar o serviço Âncoras Espaciais do Azure a um projeto do Unreal. Se estiver buscando mais informações, confira o serviço Âncoras Espaciais do Azure.

Pré-requisitos

Para concluir este guia, verifique se você:

• Instalou o plug-in Microsoft OpenXR, disponível no Unreal Marketplace ou no GitHub.
• Instalou o Unreal versão 4.25 ou posterior
• Um projeto do HoloLens 2 configurado no Unreal
• Leia a visão geral das Âncoras Espaciais do Azure
• Conhecimento básico de C++ e Unreal

Como obter informações da conta das Âncoras Espaciais do Azure

Para usar as Âncoras Espaciais do Azure no seu projeto, você precisará:

• Criar um recurso de âncoras espaciais e copiar os campos da conta listados abaixo. Esses valores são usados para autenticar os usuários na conta do seu aplicativo:
  • ID da Conta
  • Chave de Conta

Confira a documentação Autenticação das Âncoras Espaciais do Azure para obter mais informações.

Habilitar funcionalidades e permissões

HoloLens

Abra Configurações do Projeto HoloLens e habilite a funcionalidade Cliente da Internet:

Android

Para que um aplicativo Android exiba uma caixa de diálogo de permissão e permita funcionalidades de localização, a função Solicitar Permissões do Android precisa ser chamada antes de você tentar iniciar a sessão de Âncora Espacial do Azure:

Crie uma variável local para as permissões de entrada e preencha-a com:

• android.permission.ACCESS_WIFI_STATE
• android.permission.CHANGE_WIFI_STATE
• android.permission.INTERNET
• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.CAMERA

Por fim, abra Configurações do Projeto Android e defina as mesmas permissões no campo Permissões Extras em Empacotamento Avançado de APK:

iOS

Para criar um aplicativo para iOS, você precisará usar o Unreal em um Mac. Para empacotá-lo com uma conta de desenvolvedor da Apple, abra Configurações do Projeto iOS e role o painel para baixo até a seção Build. Habilite a caixa de seleção Assinatura Automática e preencha a ID da Equipe do iOS com a sua ID da Equipe.

Encontre sua ID da Equipe fazendo logon em developer.apple.com, navegando até a guia Associação e procurando ID da Equipe.

Para ver uma caixa de diálogo de permissão e permitir que o dispositivo iOS acesse informações de localização, as funções Serviços de Localização de Inicialização e Iniciar Serviços de Localização precisam ser chamadas antes de você tentar iniciar a sessão de Âncora Espacial do Azure:

Como adicionar plug-ins das Âncoras Espaciais do Azure

HoloLens

Habilite os plug-ins das Âncoras Espaciais do Azure no editor do Unreal:

1. Clicando em Editar Plug-ins e procurando Âncoras Espaciais do Azure e Âncoras Espaciais do Azure para WMR.
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.

Depois disso, reinicie o editor do Unreal para que as alterações do plug-in entrem em vigor. Agora, o projeto está pronto para usar as Âncoras Espaciais do Azure.

Android

Habilite os plug-ins das Âncoras Espaciais do Azure no editor do Unreal:

1. Clicando em Editar Plug-ins e procurando Âncoras Espaciais do Azure e Âncoras Espaciais do Azure para ARCore.
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.

Depois disso, reinicie o editor do Unreal para que as alterações do plug-in entrem em vigor. Agora, o projeto está pronto para usar as Âncoras Espaciais do Azure.

iOS

Habilite os plug-ins das Âncoras Espaciais do Azure no editor do Unreal:

1. Clicando em Editar Plug-ins e procurando Âncoras Espaciais do Azure e Âncoras Espaciais do Azure para ARKit.
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.

3. Pesquise também Serviços de Localização Móvel e Serviços de Localização Móvel – Implementação do iOS
4. Marque a caixa de seleção Habilitado nos dois plug-ins para permitir que o dispositivo iOS acesse a localização atual.

Depois disso, reinicie o editor do Unreal para que as alterações do plug-in entrem em vigor. Agora, o projeto está pronto para usar as Âncoras Espaciais do Azure.

Como iniciar uma sessão das Âncoras Espaciais

Uma sessão das Âncoras Espaciais do Azure permite que os aplicativos cliente se comuniquem com o serviço Âncoras Espaciais do Azure. Você precisará criar e iniciar uma sessão das Âncoras Espaciais do Azure para criar, persistir e compartilhar as Âncoras Espaciais do Azure:

1. Abra o blueprint do Peão que você está usando no aplicativo.
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.

Inicie uma sessão das Âncoras Espaciais do Azure:

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. Se você não tiver uma configuração, crie um ativo da Sessão de AR.
2. Adicionando o evento personalizado Iniciar Sessão das Âncoras Espaciais do Azure e configurando-o conforme mostrado na captura de tela abaixo.
   • A criação de uma sessão não inicia a sessão por padrão, o que permite que você configure a sessão para autenticação no serviço Âncoras Espaciais do Azure.

3. Configure a sessão das Âncoras Espaciais do Azure para fornecer a ID da conta, a Chave de conta, o Domínio da conta e as Configurações de localização do curso. Todas as caixas de seleção devem ser habilitadas nas configurações de localização do curso para que o serviço de âncora espacial do Azure possa usar dados de sensor para localizar as âncoras.

4. Inicie a sessão das Âncoras Espaciais do Azure, permitindo que o aplicativo crie e localize as Âncoras Espaciais do Azure.

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:

1. Interrompa a sessão das Âncoras Espaciais do Azure. 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.

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

O blueprint do Grafo de Eventos será parecido com a captura de tela abaixo:

Como criar uma âncora

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 físicas. As Âncoras Espaciais do Azure também podem ser compartilhadas entre diferentes usuários. Esse compartilhamento permite que o conteúdo de realidade aumentada desenhado em diferentes dispositivos seja posicionado na mesma localização no mundo físico.

Para criar uma Âncora Espacial do Azure:

1. Verifique se uma sessão das Âncoras Espaciais do Azure está em execução. 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.

2. Crie ou obtenha um Componente de Cena do Unreal que deve ter a localização persistente.
   • Na imagem abaixo, o componente Âncora que Precisa de um Componente de Cena é usado como uma variável. 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.

Para construir e salvar uma Âncora Espacial do Azure de um Componente de Cena do Unreal:

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.
   • 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. No Unreal, um Marcador de AR é similar a uma SpatialAnchor no HoloLens.

2. Chame Criar Âncora de Nuvem usando o Marcador de AR recém-criado.
   • A função Criar Âncora de Nuvem cria uma Âncora Espacial do Azure localmente, mas não no serviço Âncora Espacial do Azure. 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.

3. Defina a validade da Âncora Espacial do Azure. 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.
   • 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.

Depois de definir os parâmetros de âncora, declare a âncora como pronta para ser salva. No exemplo abaixo, a Âncora Espacial recém-criada do Azure é adicionada a um conjunto das Âncoras Espaciais do Azure que precisam ser salvas. Esse conjunto é declarado como uma variável do blueprint de Peão.

Como salvar uma âncora

Depois de configurar a Âncora Espacial do Azure com os parâmetros, chame a função Salvar Âncora de Nuvem. A função Salvar âncora de Nuvem declara a âncora para o serviço Âncoras Espaciais do Azure. 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.

No exemplo abaixo, a Âncora Espacial do Azure é armazenada em um conjunto durante um retorno de chamada de evento de entrada. Em seguida, a âncora é salva no 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. Por esse motivo, é uma boa ideia verificar se a chamada de salvamento foi bem-sucedida.

Se a âncora não for salva, adicione-a novamente ao conjunto de âncoras que ainda precisa ser salvo. Os EventTicks futuros continuarão tentando salvar a âncora até que ela seja armazenada com êxito.

Depois que a âncora é salva, a transformação dos Marcadores de RA funciona como uma transformação de referência para colocar o conteúdo no seu aplicativo. Outros usuários podem detectar essa âncora e alinhar o conteúdo de AR para diferentes dispositivos no mundo físico.

Como excluir uma âncora

Exclua âncoras do serviço Âncora Espacial do Azure chamando Excluir Âncora de Nuvem.

No exemplo abaixo, a âncora é sinalizada para exclusão em um evento de entrada personalizado. Em seguida, é feita a tentativa de exclusão no 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.

Agora, o blueprint do Grafo de Eventos será parecido com a captura de tela abaixo:

Como localizar âncoras pré-existentes

As âncoras existentes podem ser criadas por colegas com o serviço Âncoras Espaciais do Azure:

1. Obtenha um identificador de Âncora Espacial do Azure da âncora que deseja detectar.
   • Um identificador de âncora pode ser obtido para uma âncora criada pelo mesmo dispositivo em uma sessão anterior das Âncoras Espaciais do Azure. Ele também pode ser criado e compartilhado por dispositivos pares que interagem com o serviço Âncoras Espaciais do Azure.

2. Adicione um componente AzureSpatialAnchorsEvent ao blueprint de Peão.
   • 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.

3. Assine o Delegado Localizado de ASAAnchor para o componente AzureSpatialAnchorsEvent.
   • O delegado permite que o aplicativo saiba quando são localizadas novas âncoras associadas à conta das Âncoras Espaciais do Azure.
   • 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. 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.

Para localizar as Âncoras Espaciais do Azure criadas por colegas usando o serviço Âncora Espacial do Azure, o aplicativo precisará criar um Observador das Âncoras Espaciais do Azure:

1. Verifique se uma sessão das Âncoras Espaciais do Azure está em execução.
2. Crie um AzureSpatialAnchorsLocateCriteria.
   • Você pode especificar vários parâmetros de localização, como distância do usuário ou distância de outra âncora.
3. Declare o identificador de Âncora Espacial do Azure que você está procurando em AzureSpatialAnchorsLocateCriteria.
4. Chame Criar Observador.

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.

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.

Agora, o blueprint final do Grafo de Eventos será parecido com a captura de tela abaixo:

Próximo ponto de verificação de desenvolvimento

Se está seguindo o percurso de desenvolvimento do Unreal que estabelecemos, você está no meio da exploração dos principais blocos de construção do MRTK. Deste ponto, você pode prosseguir para o próximo bloco de construção:

Ou vá diretamente para as funcionalidades e APIs da plataforma de Realidade Misturada:

Você sempre pode voltar para os pontos de verificação de desenvolvimento do Unreal a qualquer momento.

Próximas etapas

• Âncoras Espaciais locais
• Documentação das Âncoras Espaciais
• Recursos da Âncora Espacial
• Diretrizes de experiência de ancoragem efetiva