Como criar e localizar âncoras usando as Âncoras Espaciais do Azure no Objective-C
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 de Âncoras Espaciais do Azure, em Objective-C, 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 sobre o Objetivo-C.
- Conhecimentos básicos em ARKit.
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 ASACloudSpatialAnchorSession .
ASACloudSpatialAnchorSession *_cloudSession;
// In your view handler
_cloudSession = [[ASACloudSpatialAnchorSession alloc] init];
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 ASASessionConfiguration .
_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.
_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 método de protocolo tokenRequired .
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) 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.
_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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)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.
- (void)tokenRequired:(ASACloudSpatialAnchorSession *)cloudSession :(ASATokenRequiredEventArgs *)args {
ASACloudSpatialAnchorSessionDeferral *deferral = [args getDeferral];
[myGetTokenAsync callback:^(NSString *myToken) {
if (myToken) args.authenticationToken = myToken;
[deferral complete];
}];
}
Configuração da biblioteca
Invoque Start() para permitir que sua sessão processe dados do ambiente.
Para manipular eventos gerados pela sessão, defina a propriedade da sessão como um objeto, como a delegate exibição. Este objeto deve implementar o SSCCloudSpatialAnchorSessionDelegate protocolo.
Saiba mais sobre o método start .
_cloudSession.session = self.sceneView.session;
_cloudSession.delegate = self;
[_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 .
[_cloudSession processFrame:_sceneView.session.currentFrame];
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 método de protocolo sessionUpdated .
- (void)sessionUpdated:(ASACloudSpatialAnchorSession *)cloudSession :(ASASessionUpdatedEventArgs *)args {
ASASessionStatus *status = [args status];
if (status.userFeedback == ASASessionUserFeedbackNone) return;
_feedback = [NSString
stringWithFormat:@"Feedback: %@ - Recommend Create=%.0f%%",
FeedbackToString(status.userFeedback),
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 ASACloudSpatialAnchor .
// Create a local anchor, perhaps by hit-testing and creating an ARAnchor
NSArray<ARHitTestResult *> *hits = [_sceneView.session.currentFrame hitTest:CGPointMake(0.5, 0.5) types:ARHitTestResultTypeEstimatedHorizontalPlane];
if ([hits count] == 0) return;
// The hitTest method sorts the resulting list by increasing distance from the camera
// The first hit result will usually be the most relevant when responding to user input
ARAnchor *localAnchor = [[ARAnchor alloc] initWithTransform:hits[0].worldTransform];
[_sceneView.session addAnchor:localAnchor];
// 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.
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Save Failed:%@", error.localizedDescription];
return;
}
_feedback = [NSString stringWithFormat:@"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 getSessionStatusWithCompletionHandler .
[_cloudSession getSessionStatusWithCompletionHandler:^(ASASessionStatus *value, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Session status error:%@", error.localizedDescription];
return;
}
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 .
ASACloudSpatialAnchor *cloudAnchor = [[ASACloudSpatialAnchor alloc] init];
cloudAnchor.localAnchor = localAnchor;
cloudAnchor.appProperties = @{ @"model-type" : @"frame", @"label" : @"my latest picture" };
[_cloudSession createAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// ...
});
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 updateAnchorProperties .
ASACloudSpatialAnchor *anchor = /* locate your anchor */;
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
if (error) _feedback = [NSString stringWithFormat:@"Updating Properties Failed:%@", error.localizedDescription];
}];
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 getAnchorProperties .
[_cloudSession getAnchorProperties:@"anchorId" withCompletionHandler:^(SCCCloudSpatialAnchor *anchor, NSError *error) {
if (error) {
_feedback = [NSString stringWithFormat:@"Getting Properties Failed:%@", error.localizedDescription];
return;
}
if (anchor) {
[anchor.appProperties setValue:@"just now" forKey:@"last-user-access"];
[_cloudSession updateAnchorProperties:anchor withCompletionHandler:^(NSError *error) {
// ...
}];
}
}];
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 de expiração .
int secondsInAWeek = 60 * 60 * 24 * 7;
NSDate *oneWeekFromNow = [[NSDate alloc] initWithTimeIntervalSinceNow: (NSTimeInterval) secondsInAWeek];
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 .
ASAAnchorLocateCriteria *criteria = [ASAAnchorLocateCriteria new];
criteria.identifiers = @[ @"id1", @"id2", @"id3" ];
[_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 método de protocolo anchorLocation .
- (void)anchorLocated:(ASACloudSpatialAnchorSession *)cloudSession :(ASAAnchorLocatedEventArgs *)args {
ASALocateAnchorStatus status = [args status];
switch (status) {
case ASALocateAnchorStatusLocated: {
ASACloudSpatialAnchor *foundAnchor = [args anchor];
// Go add your anchor to the scene...
}
break;
case ASALocateAnchorStatusAlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case ASALocateAnchorStatusNotLocatedAnchorDoesNotExist:
// 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 ASALocateAnchorStatusNotLocated:
// 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 deleteAnchor .
[_cloudSession deleteAnchor:cloudAnchor withCompletionHandler:^(NSError *error) {
// 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 .
[_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 de redefinição .
[_cloudSession reset];
Para limpar corretamente após uma sessão, libere todas as referências.
_cloudSession = NULL;
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.