Como criar e localizar âncoras usando as Âncoras Espaciais do Azure no Unity
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, no Unity, 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.
- Conhecimentos básicos em C# e Unity.
- Conhecimento básico em ARCore se você quiser usar Android, ou ARKit se você quiser usar iOS.
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 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, 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 .
this.cloudSession.Configuration.AccountKey = @"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.
this.cloudSession.Configuration.AccessToken = @"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 .
this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
args.AccessToken = @"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.
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 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.
this.cloudSession.Configuration.AuthenticationToken = @"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.
this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
args.AuthenticationToken = @"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.
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 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 .
#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 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 .
#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 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
UserFeedbacksessã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 vezReadyForCreateProgressacima de 1, temos dados suficientes para salvar uma âncora espacial da nuvem, embora recomendemos que você espere atéRecommendedForCreateProgressque esteja acima de 1 para fazê-lo.
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 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 .
// 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ê 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 value = await this.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 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 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[@"last-user-access"] = @"just now";
await this.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 .
var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
if (anchor != null)
{
anchor.AppProperties[@"last-user-access"] = @"just now";
await this.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 a propriedade Expiration (Expiração ).
cloudAnchor.Expiration = DateTimeOffset.Now.AddDays(7);
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 = new AnchorLocateCriteria();
criteria.Identifiers = new string[] { @"id1", @"id2", @"id3" };
this.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 .
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 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 .
Excluir âncora depois de localizar (recomendado)
await this.cloudSession.DeleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes
Excluir âncora sem localizar
Se você não conseguir localizar uma âncora, mas ainda assim quiser excluí-la, você pode usar a API, GetAnchorPropertiesAsync que usa um anchorId como entrada para obter o CloudSpatialAnchor objeto. Em seguida, você pode passar esse objeto para DeleteAnchorAsync excluí-lo.
var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
await this.cloudSession.DeleteAnchorAsync(anchor);
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 .
this.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 .
this.cloudSession.Reset();
Para limpar corretamente após uma sessão, invoque Dispose().
Saiba mais sobre o método Dispose .
this.cloudSession.Dispose();
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.